Version 1
Visibility: Open to anyone


    Overview:

    Intall the Forms App from the Jive Apps Market

    • Configure the App
    • Select, Fill Out, and Submit a Form
    • or follow this document

    The Forms app is designed to simplify the process of creating form-based, templated content within Jive.  The same type of content, with a consistent structure and style, can easily be created time and time again in a consistent, reproducable way.

     

    The app requires no custom content types and no other plugins, it simply leverages existing Jive content types (Documents, Discussions, Questions), and provides a semi-structured body for the content, based on form data input by the user.

     

    Any number of templates can be created in any number of categories, and a single app can now be the place to generate just about any kind of content you can think of.  Anything that can be created, manually, in Jive can also be created using the Forms app.

     

    Steps to be done before getting started:

    • Check for the Forms App in App Store under "Apps" tag.
    • Open the app check if you have any sample forms in that App.
    • Go back to community page and start with creating new documents.
      • HTML document
      • Template document
    • For Sample documents look at them in Jive community.
    • After starting creating documents don't forgot to save then (Save Draft) and remember the document Id's of them.

    Getting Started

     

    There are 3 things that are needed in order to start using the Forms App:

     

    • At least one HTML source document - used by a form template to create Jive content
      • This is what will be used to create the body of the document, discussion, etc.
    • At least one Form template - used by the Forms App to create an input form
      • This can either be created within the Forms App using the Form Creator, or can be created by hand, manually
    • The Forms App - installed from the Apps Market
      • The Forms App will be used to select a form from the list of forms available (that you've created) and to enter information into the form and publish the output into your Jive community.
      • The Forms App can also be used to create Templates that you may use within the Forms App to generate new documents.

     

    Use the following steps to install a sample template into your community for use by the Forms App.  There are a multiple ways you can utilize the following exercises, but the recommended approach, for initially getting started with the app would be to perform the steps in the following order:

    First Exercise,  Post a New Document Using a Pre-Defined Template

     

    This is the simplest way to get started, and to see how the app will be used the majority of the time.

     

    • Step 1.  Create an HTML Source Document
      • This is required before doing anything else.  The HTML source document is where you will perform most of the layout of how your document will look.
      • You only need to do this once for the following exercises.  The single sample HTML document below may be used to create both the pre-defined template and/or a new template.
    • Step 2a.  Create a Form Template Document - Using a Pre-Defined Template
      • This will quickly get you started with using the app, without having to immediately worry about how to create templates
    • Step 3.  Use the Forms App to Create a New Document
      • This will allow you to quickly see the results of the app, by merging the contents of a form and the HTML source - quick and easy results.

    Second Exercise, Post a New Document using a Newly Created TemplateNow that you have used the app, once, and learned about using an HTML source and a form template, now would be a better time to learn to create a template in the app.

    • Go Back to Step 2b.  Create a Form Template - Using a Newly Created Template
      • Remember, you can re-use the HTML source from Step 1, for this newly created template, and do not need to repeat that step
    • Go Back and Repeat Step 3.  Use the Forms App to Create a New Document
      • This time you will use your newly created form template, rather than the pre-defined one
      • Note that since you are using the same HTML source, then resulting document will look the same in both exercises


    Step 1.  Create an HTML Source Document (for more info refer to the end of the document)

    1. Create a new document in your Jive community, in a place where every user can read it.
    2. Make an exact copy of the sample HTML document - Sample HTML: {$msgFrom.label} {$msgFrom}, {$msgTo.label} {$msgTo}
      1. Make sure the title is specified exactly as - Sample HTML: {$msgFrom.label} {$msgFrom}, {$msgTo.label} {$msgTo}
      2. Copy the entire body content into the body of your document
        1. You may reformat your copy of the document however you like - move things around, change highlights / styles, colors, etc.
        2. The only important parts are the {$value} which specify where form field data will go - feel free to re-style these items, just don't delete or rename them
    3. Save the document - you now have an HTML source document in your community that can be used by a form template
      1. Make note of the document ID for the HTML document that has just been created, you will be required to use it in the next step
      2. Note: the document ID is strictly the numeric portion of the ID and the numeric portion only
        1. For the sample document at, https://community.jivesoftware.com/docs/DOC-69936, 69936 is the document ID, not DOC-69936


    Step 2a.  Create a Form Template Document - Using a Pre-Defined Template

     
    Follow these steps if you would like to skip the template creation process and just get started using a pre-defined sample template.      If you would like to create a custom template, and use that, then skip down to Step 2b.

    1. Create a new document in your Jive community, in an place where every user can read it.
    2. Give the document a title of Sample Templates
    3. Add the tag fbldr_templates to the document
      1. This is so the Forms App will be able to recognize the document as containing form templates
    4. Switch the document editor to the HTML view (click the HTML button in the toolbar) and enter the following text - <pre></pre>
      1. The Forms App only looks for valid templates contained in <pre> tags within a document
    5. Copy the JSON contents of the Message Template - Template Source: Forms App: Message Template - and paste in between the <pre> tags you entered in the previous step
      1. Copy the content of the template, from "{" to "}", including those curly braces
    6. Edit the docId in the content section of the template, and replace with the document ID from the HTML source document that was created earlier
      1. Replace 69936 with your sample HTML document ID
    7. Save the document - you now have a template in your community that can be used by the Forms App
      1. Make note of the document ID for the template document that has just been created, you may (optionally) use it in the next step
      2. Note: the document ID is strictly the numeric portion of the ID and the numeric portion only
        1. For the sample document at, https://community.jivesoftware.com/docs/DOC-69936, 69936 is the document ID, not DOC-69936


    Step 2b.  Create a Form Template Document - Using a Newly Created Template

     

    Steps to Create a New Template:  (this will essentially be a slightly simpler recreation of the above pre-defined template)

    1. Open the Forms App
    2. Select the Create New Form link in the upper right
      1. This will open the app to the template creator, for which more in-depth information can be found here - Forms App: Template Creator
    3. Select the Form Template tab in the upper right
      1. Enter "Your Templates" as the template Category
      2. Enter "Message Template" as the template Name
      3. Enter "This is a template that I use to message stuff." as the template Description
      4. Select "Document" as the template Content Type
      5. Select "Another Jive Document" as the template HTML Source
      6. Enter the document ID of the HTML source document, created in Step 1, as the template HTML Doc ID
    4. Select the Form Fields tab in the upper right
      1. Add the following 6 fields, ID and Label
        1. msgTo / To
        2. msgFrom / From
        3. msgCopy / CC
        4. msgSubj / Subject
        5. msgBody / Message
        6. msgSend / Send
      2. For the sake of simplicity, just set all field types as Text Field
      3. You can adjust field types, titles (tooltips), default values, required as desired
        1. See the Forms App: Template Creator for more detailed information on the available options
    5. Now that the form and fields have been defined, select the available tabs on the left and look for the following
      1. The Form Preview tab on the left should now show a valid form with 6 fields displayed
      2. The Form Source tab on the right should now show a valid JSON template within the text pane
    6. Select the Form Preview tab in the upper left, fill out the preview form, and click the Create Document button
    7. Given no form errors, the Content Preview tab in the upper left should now be active, select the Content Preview tab
      1. The HTML content, complete with the form data you entered, should now be displayed
      2. The HTML content may not be as rich as that rendered in the RTE, since it is a more basic HTML preview, but it should be relatively similar
    8. Select the Form Source tab in the upper left, and keep a copy of the JSON displayed in the text pane for use in the next step

    Steps to Install the New Template:

    1. Create a new document in your Jive community, in an place where every user can read it.
    2. Give the document a title of Created Templates
    3. Add the tag fbldr_templates to the document
      1. This is so the Forms App will be able to recognize the document as containing form templates
    4. Switch the document editor to the HTML view (click the HTML button in the toolbar) and enter the following text - <pre></pre>
      1. The Forms App only looks for valid templates contained in <pre> tags within a document
    5. Copy the JSON contents of the Form Source tab, from the app in the previous step, containing your newly created template
      1. Copy the content of the template, from "{" to "}", including those curly braces
    6. Edit the docId in the content section of the template, and replace with the document ID from the HTML source document that was created earlier
      1. Replace 69936 with your sample HTML document ID
    7. Save the document - you now have a template in your community that can be used by the Forms App
      1. Make note of the document ID for the template document that has just been created, you may (optionally) use it in the next step
      2. Note: the document ID is strictly the numeric portion of the ID and the numeric portion only
        1. For the sample document at, https://community.jivesoftware.com/docs/DOC-69936, 69936 is the document ID, not DOC-69936


    Step 3.  Use the Forms App to Create a New Document


    Important Note:  After you create the template document above, you may have to wait a few minutes to be able to locate the template in the Forms App.  The delay varies based on the time to index the new document and its tags within Jive's search service.  You have a couple options at this point:

    1) wait 5 to 10 minutes in order for your template to be indexed by the search engine; or,

    2) go into the Forms App, edit your app settings, and add your document template ID, not your HTML source ID (ID from Step 2, not Step 1) and place it in the document ID settings in the app.


    The app, by default, only looks for tagged documents, but can be set up to also look for specific document IDs as well.  You can also use this method (a hard-coded document ID and not a tag) to test a template in your app before you tag the document and make the template available for everyone to use.

    1. Open the Forms App
    2. Select the Sample template that was previously created
      1. Category - Your Templates (Your Category Name)
      2. Name - Message Template (Your Template Name)
    3. Enter values for all the fields in the form
    4. Post the form to a place where everyone can read
      1. Note: After posting you should be asked where you would like to post the document, using the Jive place picker
    5. You should then be automatically redirected to the new document
      1. If you kept the same formatting as the sample HTML document source, it should look something like this - Sample HTML: From Me, To You

     

    Congratulations!  You have now successfully used the Forms App to create a new, templated piece of Jive content.

     

    Creating HTML Source and Form Template

     

    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.

     

    Now we learn how to create Form Templates using Forms App.

    Creating Form Templates:

     

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

    create-00.png

     

    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:

    fbldr01.png

     

    Initial View of Form Template Panel

    create-01.png

     

    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

    create-02.png

     

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

    create-03.png


    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.

    create-04.png

    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:

    create-05.png

     

    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

    create-06.png

     

    Sample Content Preview

    create-07.png

    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. 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:

    create-08.png

    User Guide:

    This describes how to use the newly created form

    The purpose of this document is to describe the use of the Forms App.

     

    Configuring the App

     

    There are 3 options that can be configured for the app:

     

    • Template tags - which tags to search for when locating documents containing templates
      • Default value - "fbldr_templates,fbldr_template"
      • This is set in the app for each user so that each user can control which templates will be in their view of the app
    • Default template category - the template category to select by default after templates are first loaded
    • Default template name - the template to select by default after templates are first loaded

    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

     

    Here is how to configure the app preferences:

     

    Step 1:  Open the app menu and select "Your Settings"

    settings02.png


    Step 2:  Enter the appropriate values and select "Save Settings"

    settings01.png

     

    Initializing the App

     

    Nothing needs to be done here, once the app is configured with the appropriate preferences (the default values for the preference may often suffice), it will automatically load and categorize all templates that are located by the search.  The following loading screen will appear as the app is initializing and loading the templates:

    loading01.png

     

     

    Using the App

     

    Creating Jive content can now be created in 3 easy steps:

    • Select a template
    • Fill out the form
    • Submit the form

     

    That's it.  That's all you need to do in order to create customized content within Jive.

     

    Step 1: Select a Template

     

    The first step is to select a category and a template.  Choose a category from the drop down list, which will then populate the list of templates for that category.  Following the category selection, select one of the available templates from the Template drop down list.

     

    Note: If only one single template is found when initially loading the templates, or if a default category and template is set in the app preferences, then that will already be selected here and the template form will be auto-generated when the app is loaded.

    fbldr01.png

     

    Step 2:  Fill Out the Form

     

    Once a template has been selected, a form will be created, dynamically, based on the template definition.  For more information on how these templates are defined, see Forms App: Template Specification.

     

    Note that if an item as a next to it, you may mouse over the to display a helpful tooltip describing the purpose and/or validation rules for the field.

    form-sample02.png

     

    Step 3:  Submit the Form

     

    Once the form has been successfully filled out (no validation errors - see below), then the following confirmation dialog will be display, and the form status at the bottom will be updated to reflect the same.

     

    Confirmation DialogConfirmation in Form
    success01.pngsuccess02.png

    Step 4:  Success

     

    If all goes well, you will now have a new piece of content created in Jive, based upon the provided template and the form values you have provided.  Which may look something like the following:

    content01.png

    Handling Template Errors

     

    When there is an error in a template definition, a form will not be displayed when the template is selected.  Also note that the template will be listed in red with a warning in the template drop down box.  Rather than render the input form, a list of template validation errors will be displayed on the screen.  Editing the template to fix the listed errors, re-saving the updated attachment on the appropriate document, and reloading the app should address the problem.  Here is an example of a problematic template:

    template-error01.png

     

    Handling Form Errors

     

    When there is an error in an input form (required field is missing, does not match validation rules, etc.) then individual form errors will be displayed.  The field will become highlighted with a red border and a indicator will show next to each problematic field.  Simply update each problematic field with an appropriate value and re-submit the form.  The form will automatically refresh to show which, if any errors are resolved.  If all errors have been resolved, then the form will submit and the content will be created.

     

    Note:  Hovering your mouse over the indicator will show a helpful tooltip describing the problem with the field's value.

    form-error01.png

     

     

    Notable Input Type:  Date Picker

     

    One of the allowable data types for a field is a date.  When a date is the defined type, a date picker will be displayed with the field, see the following example:

    datepicker01.png

     

     

    Notable Input Type:  User Picker

     

    Another allowable data type for a field is a user.  When a user is the defined type, a user picker (Jive-provided) will be displayed, see the following example:

     

    User Picker Before User Selection
    User Picker After User Selection
    form-sample01.pnguserpicker01.png

     

    Note:

    • Ask Question, Submit Issues, and Provide Feedback here: Forms App

    Forms App Useful Links:


    Forms App: User Guide

    https://community.jivesoftware.com/docs/DOC-59709

     

    Forms App: Where to Begin

    https://community.jivesoftware.com/docs/DOC-70148

     

    Forms App: How to Create Templates

    https://community.jivesoftware.com/docs/DOC-63420

     

    Forms App Update: Embedded Images, Multiple Attachment Support

    https://community.jivesoftware.com/docs/DOC-73053

     

    Forms App: Template Specification

    https://community.jivesoftware.com/docs/DOC-59708

     

    Forms App: Sample Templates

    https://community.jivesoftware.com/docs/DOC-59698


    Forms App:  Linking to a Specific Template or Place

    https://community.jivesoftware.com/docs/DOC-73054

    Forms App:  Minor Update and Big Announcement

    https://community.jivesoftware.com/community/developer/blog/2013/06/24/forms-app-minor-update-and-big-announcement

     

    Forms App: Now Includes Tags, Lists, URLs, and More

    https://community.jivesoftware.com/community/developer/blog/2013/05/06/forms-app-now-includes-tags-lists-urls-and-more