Forms App: How to Create Templates

Version 10

    Template Creator Topics



    Creating HTML Source


    Prior to creating any form templates, you will first want to create HTML source to be used / referenced by your template.


    The reason being, the recommended approach for creating HTML source, for a from template, is to use a separate Jive document to store the formatted HTML and not embed all of that rich HTML into the form template itself.  The HTML source is really the bulk of the content for that which is posted to Jive - the user fills out the form in the app, the HTML source is loaded and populated with the values entered into the form by the user, and a new piece of Jive content is posted, after that merge.


    So, the entire process really is as follows:

    • Create an HTML source document to be used by a form template
    • Create a form template - either using the template creator in the app, documented here, or manually using the Forms App: Template Specification
    • Use the Forms App to load a form template, populate the form, and post new Jive content


    Here is an example, of the above 3 items, to use for reference:


    Things to take note of:

    • The way to include form field data into the HTML document is to use the following syntax:  {$field_id}
    • The way to include a form field label into the HTML document is to use the following syntax:  {$field_id.label}
    • When the template is set to create a Document it is VERY critical to include a form field value into the TITLE of the HTML Document.
      • For Documents posted in a Place in Jive, the title must be unique, so a single title in the template will not do, part of the form data must be in the HTML Document title.
      • The Document title has no bearing when the !App action is used to embed the HTML content inline.  This only applies when posting the form from the App home / canvas view.
    • The combination of Form Template, and its matching HTML source document is key.  The template definition should include a pointer to the correct Document ID.
    • Modifying the HTML source document will only affect newly posted / created content and will not retroactively re-format any previously posted form content.


    Creating Form Templates


    In the upper-right corner of the app, there is a link for creating forms, which looks like this:



    When you click that link, you will be taken to a canvas view of the app, showing a new creation page.  The UI consists of 2 main panels, each with a set of related tabs.


    • Left side:  Form Views - this is where you preview the generated form, the generated template, and the content preview
      • The content preview is only available after creating and submitting a generated form
    • Right side:  Form Inputs Controls - this is where you enter the information which is required to generate the template
      • Form Template - basic template information such as the name, category, description, etc.
      • Form Fields - this is where you add / create the fields for your form template


    A couple items of note here - first is that the form input UI is wired live into the preview UI.  So, as you enter information for the form and add fields, the form preview and form source are automatically updated, as the data is entered into the form.  Second, notice that the input forms for the template are of the exact same style and format of the rendered form template, in order to make for a consistent experience across the app UI.


    Form Template Panel Field Descriptions


    The list of the fields in the Form Template panel include the following:


    • Category - The category of the template, under which the template will appear under when selecting from the list of available templates in the app.
    • Name - The name of the template, which again will appear when selecting the template from the list of available templates in the app.
    • Description - A more verbose description of the template, and its intended use / purpose.  This will display above the template form, once the template is selected in the app.
    • Content Type - What type of content to create (Document, Discussion, etc.) when using the template to post from the home / canvas app view.
      • Note:  This setting has no bearing when the template is used to post to an piece of content using the !App action, there content is embedded inline.
    • Attachment - If checked, the user will be allowed to add an attachment to the piece of content, after the form has been successfully posted to Jive.
      • Note: Attachment currently only works with the "Document" content type, and not with "Discussion" or "Question" and is a limitation of the Jive API, not of the app itself.  A future update of the app should alleviate this restriction, likely mid-late 2013.
    • HTML Source - Another Jive Document
      • Selecting this option will allow the specification of an existing Jive Document which contains the HTML into which the submitted form will be rendered.
      • This is the default, and recommended, value for this setting.  It is intended to provide better, and easier separation between the form template and the generated HTML.
    • HTML Source - Within This Template
      • Selecting this option will allow the specification of a block of HTML that will be used to create the Jive content from the posted form.
      • This setting is mainly for backwards compatibility with older app templates and should not be used for newly created templates.
      • It is highly recommended to store the HTML content, which the template will use, in a separate Jive document - which allows for the easy separation of the form template and its HTML-formatted content.  Using the rich Jive editor allows for a much better HTML content creation experience as well, rather than trying to embed a large block of HTML within the template.
    • Container Type / Container ID (removed / deprecated)
      • These options will no longer be visible to new templates and are only included for backwards compatibility with older app templates.
      • In the current version of the app, the container in which to post Jive content is not determined by the template, a Place Picker will be displayed and will prompt the user for a location in which to post the content.


    Template category and template name will be displayed in this part of the forms app, when after it initially locates and loads all of the form templates:



    Initial View of Form Template Panel



    Form Fields Panel Field Descriptions


    The list of the fields in the Form Fields panel include the following:


    • ID - The unique identifier for the field, used within the HTML content to reference the data entered into the field.
      • This ID must not contain any special characters or spaces, valid characters are any alphanumeric value, "_" and "-"
    • Label - The user-friendly label for the field, which will show next to the field when rendered in the form.
    • Type - The data / UI entry type of the field, Text Field, Date, etc.
    • Default Value - For text fields, and select fields, provides the default value that will be placed in the form when it first loads (does not apply to all field types)
    • Tooltip - A more verbose, descriptive text describing the use or format of the field, which is displayed when the user hovers over the "i" info icon to the right of the form field.
    • Required - If checked, the user will be required to provide a value for this form field, and will not be allowed to submit the form successfully until a value is provided.
    • Patterns - A comma-delimited list of regular expressions which can be used to validate the value entered for the field.
      • The concept of regular expressions is out of the scope of this document, though there are many online references which discuss the topic in depth.
    • Pattern Error - A more user-friendly, human readable error to display when a regular expression is provided for validation and the value does not match.
      • The default error is "Value does not match the pattern <regular expression>", which may not be the user experience you want to deliver when the value does not validate.


    Initial View of Form Fields Panel



    Initial View of Form Source Panel, Immediately Contains the Basic JSON Shell of the Template


    Again, remember that the input UI is wired into the preview, so as you enter information, the JSON will automatically be updated to reflect the changes.


    Adding Form Fields


    Adding form fields is as simple as filling out the field form and clicking the "Add Field" button.  After entering the appropriate form information and adding at least one field, the list of fields will be displayed, and the form preview will now be rendered.


    Once you add fields, you can then modify the list of fields.  You can use the delete button to remove a field from the list, and use the up/down arrow buttons to change the placement of the field within the list.  Again, as you remove fields or alter the order of fields the form preview will be updated as well.


    One important thing to be aware of is that the form field ID must be unique for all fields - if an attempt is made to add a second field with a duplicate ID, the field will not be added and an error will be displayed.


    Form Preview and Content Preview


    After all information has been entered, and fields have been added, the form preview can now be used to test out the form.  This preview form will behave in the exact same manner as the live template will behave once posted to Jive and loaded into the app.  While the form will behave the same way, the action of the form is slightly different:


    • Clicking the "Create" button will NOT actually create content.  This is only a preview and not for actually creating content, it is for testing only.
    • Clicking the "Create" button will instead place a preview of the created content into the Content Preview tab, using the filled out form and the content body of the template.


    Here is a screenshot showing the preview form doing form validation, as it would in the live app:



    After the preview form has been filled out successfully, without errors, and the "Create" button is clicked, then the following success status will be displayed, and the Content Preview will become available.


    Successful Form Submission



    Sample Content Preview


    Important note:  Content Preview will not be able to preserve/render any custom RTE styling that may be applied to the template content.  So, the preview, while able to render nearly all HTML content, will not necessarily be 100% accurate - given the missing custom styling that may be present on the live, posted content.


    Utilizing the Generated Template


    Success!  At this point, there is now a newly generated template waiting to be used within Jive.  Note that there is no automated way to push the template into Jive, due to the current complexity of placing all templates in custom-tagged Jive documents.  So there is a manual step involved at this point, however, it is relatively minor.  The template creator now has a way to automatically publish your new template, no manual copy and pasting involved!  See Forms App: 03/13 Update - Date Formats, Direct Messages, Label Position, Template Creation for details on this newly released features.  There is still one more manual step you must do, however, which is:


    • Open the Form Source tab
    • Click the Create Template button
      • Assuming there are no template errors, the Create Template button should be active, if not then address any template errors first
    • Select a place to store the new template
      • This will create the new template document, and redirect your browser to view the document
    • As noted within the new template document Tag the Jive document, as appropriate
      • Use the tag "fbldr_template" to allow all users to be able to utilize your new template
    • Save the Jive document with the new tag
    • The Forms App is now ready to use your new template
      • Note: There may be a slight delay in availability due to potential lag in the Jive search index updating to reflect the new document, this may take a few minutes


    These steps are necessary to actually utilize the generated template.  For more information on how templates are actually loaded into the app, see the "How Templates are Loaded" section of the Forms App: Template Specification


    Here is a sample of the generated form source: