Version 12

    Template Specification Topics

     

     

    Overview

     

    The purpose of this document is to describe the template specification for the Forms App

    How are Templates Defined?

     

    Templates are defined using JSON and are structured in the following manner.  All items are required, unless otherwise noted.

     

    Template Definition


    The following is the basic structure of a form template.  Each Main section is then defined in further detail below.

    {

        "category" : "template category", (optional - if not specified, will use the title of the document to which the template is attached)

        "name" : "template name",

        "desc" : "template description",

        "dateFormat" : "mm/dd/yy" (optional),

        "labelPosition" : "top/left" (optional)

        "fields" : [

              (array of Field definitions, defined below)

        ],

        "content" : {

              (see Content definition, defined below)

        }

    }

     

    Field Definition

    {

        "type" : "field type", (valid values: 'boolean', 'date', 'select', 'text', 'textarea', 'userpicker', 'userselect')

        "id" : "field ID",

        "label" : "field label",

        "required" : true/false, (optional - whether or not the field is required)

        "patterns" : [

              (array of regular expression strings, used during form validation - use pattern string only not /pattern/)

        ] (optional),

        "patternError" : "pattern validation error", (optional - in case of pattern match failure, a user-friendly message to display, if not specified then displays pattern)

        "title" : "field tooltip", (optional - if specified, displays as a tooltip for the field)

        "value" : "default value", (optional - the default value for the field)

        "values" : [

              (array of Value definitions)

        ] (required only for 'select' and 'userselect' field types, to populate option list)

    }

     

    Field Types


    Here is how field types are actually rendered in the form:

    boolean - checkbox

    date - text field with date picker (uses the dateFormat attribute from the form)

    select - drop down box

    text - input field

    textarea - textarea input field

    userpicker - Jive user picker (choose link, etc.)

    userselect - drop down box, specific to user IDs

     

    Value Definition


    There are two ways to define option values - either as a string value or a value/label object.  Use the string method if you do not need to separate your option value from its display.  Use the object method if you need to have an actual field value that is separate from the display value.

     

    Note: In the case of a 'userselect' field type, it is most applicable for the object specification - since the value must be the user ID (Jive internal ID, not name), and a better display (name or email address) would be warranted.  But this approach may be used for any select type.

    String approach (use same value and label)

     

        [ "My Account", "Your Account", "His Account", "Her Account" ]

     

    Object approach (use separate value and label)

     

        [

              { "value" : "12345", "label" : "My Account" },

              { "value" : "23456", "label" : "Your Account" },

              { "value" : "45678", "label" : "His Account" },

              { "value" : "56789", "label" : "Her Account" }

        ]

     

    Content Definition

     

    There are two ways to specify the HTML content used when creating the Jive content from the template form - by referencing an existing Jive document (using its document ID) or by embedding the HTML content within the template.

     

    Important note:  Container type and container ID are no longer part of the template specification and are also no longer part of the user settings.  Users now choose, from within the app, where they would like the content posted.  This can be controlled by using a link to the app, as to which template is loaded and where the content is posted, by following the instructions here - Forms App: Linking to a Specific Template or Place

     

    Referencing an Existing Jive Document

     

    This is the recommended method, and makes it much easier to create, edit, and view the content which will be created by Jive when submitting the form.

    "content" : {

              "type" : "content type", (valid values: 'document''discussion', 'question'),

              "docId" : document ID, (for a document URL ending in DOC-####, use just the #### portion as the ID),

              "includeAttachment" : true (optional, allows for images and attachments to be added, to 'document' type ONLY)

    }

     

    Here is an sample document that could be used by a template:  https://community.jivesoftware.com/docs/DOC-62193 (the docId to use in this case would be 62193)

     

    Here is what that sample document would look like, after being posted by a form:  https://community.jivesoftware.com/docs/DOC-62194

     

    Embedding HTML Content within the Template

     

    Rather than reference an existing document, the HTML content can be embedded within the template itself by removing the "docId" attribute from the content definition and by added both a "title" and "body" attribute in its place.

    "content" : {

              "type" : "content type", (valid values: 'document''discussion', 'question')

              "title" : "content title", (may use field substitutions of any non-user field type)

              "body" : "<body>content body here</body>", (may use field substitutions of any type)

              "includeAttachment" : true (optional, allows for images and attachments to be added, to 'document' type ONLY)

    }

     

    Field Substitutions

     

    When the template form is submitted and validated, and the Jive content is actually created, a substitution is performed on both the content title and body elements.  The substitution looks for the following patterns:

     

    • {$fieldId} - will substitute the field value
    • {$fieldId.label} - will substitute the field label

     

    Example:

     

    Fields:

        Who Field:  ID = "who", label = "Who is this for?", value = "John"

        What Field:  ID = "what", label = "What is happening?", value = "Party"

     

    Before Substitution:

        Content Title:  "A {$what} is Happening!"

        Content Body: "<body><div>{$who.label} - {$who}</div><div>{$what.label} - {$what}</body>"

     

    After Substitution:

        Content Title:  "A Party is happening!"

        Content Body: "<body><div>Who is this for? - John</div><div>What is happening? - Party</body>"

     

    Sample Template

     

    Here is a sample of a fully-defined template:

        {

            "category": "My Templates",

            "name": "ABC Template",

            "desc": "This is a template that I use to record stuff.",

            "fields": [

                { "type": "userpicker", "id": "who", "label": "Who", "required": true },

                { "type": "text", "id": "what", "label": "What", "value": "this is what" },

                { "type": "text", "id": "why", "label": "Why", "value": "this is why" },

                { "type": "text", "id": "where", "label": "Where", "value": "this is where" },

                { "type": "date", "id": "when", "label": "When", "title": "Pick a date, any date." },

                { "type": "textarea", "id": "how", "label": "How", "value": "this is how" },

                { "type": "text", "id": "quantity", "label": "How Many", "value": "this is how many", "title": "Must be a number", "patterns": ["\\d+"] },

                { "type": "boolean", "id": "like", "label": "Like", "value": true }

            ],

            "content": {

                "type": "document",

                "title": "A {$what} is Happening",

                "body": "<body><div><h4>For</h4>{$who}</div><div><h4>{$why.label}</h4><span>{$why}</span></div><div><h4>{$where.label}</h4><span>{$where}</span></div><div><h4>{$when.label}</h4><span>{$when}</span></div><div><h4>{$how.label}</h4><span>{$how}</span></div><div><h4>Liked?</h4><span>{$like}</span></div></body>"

            }

        }

     

    Here is the form that will be generated based on the above template:

    form-sample01.png

     

    How are Templates Loaded?

     

    The process for locating available templates is as follows:

    • Perform a Jive content search for documents, based on a list of tags
      • See below (How to Set the List of Tags) for how to specify that list
    • Locate all "<pre>{template_spec}</pre>" tags within the document body text
    • Parse each {template_spec} contained in each tag (only one template is allowed per tag)

     

    So the process for creating templates is actually quite simple:

    • Create templates
      • Important!  Templates are part of the Jive document body, and not an attachment, the HTML contained in the template content.body element must have HTML tags escaped.
      • The easiest way to do this is to just create the template, as normal, and then replace all '<' with '&lt;' and all '>' with '&gt;' before copying/pasting into the Jive document.
    • Create a new document in Jive
      • Assign appropriate tags to new document
      • Switch document to HTML view
      • Place each template inside of a <pre></pre> tag, and make sure all HTML tags in the template body have been escaped, as specified above
    • Publish document
    • New templates should now appear in the app
      • Due to the potential delay in the search index updating, when using the Jive cloud search, there may be a slight delay before the templates can be loaded

     

    For an example document, containing templates, see the following:  Forms App: Sample Templates

     

    How to Set the List of Tags

     

    The list of tags is determined by a user preference within the app.  The default value for the list of tags is "fbldr_templates,fbldr_template".  The list is comma-separated and will be turned into an "or" search query based on all the items in the list.  So only a single tag, not all tags, must be present on a document containing templates.  In order to alter the list of tags and specify additional/alternative tags then perform the following:

     

    View App User Preferences (Your Settings)

    settings02.png

     

    Edit App User Preference for Template Tags

    settings01.png

     

    Now when loading the app it will look for any documents, with the appropriate tags, having any templates in the document body text.

     

    Important note:  Container type and container ID are no longer part of the template specification and are also no longer part of the user settings.  Users now choose, from within the app, where they would like the content posted.  This can be controlled by using a link to the app, as to which template is loaded and where the content is posted, by following the instructions here - Forms App: Linking to a Specific Template or Place