Form Blueprints, Snippets and Smart Snippets

Smart snippets are similar to snippets, but when you add a smart snippet to your form, the fields inside it are linked to the snippet they belong to. Updates made to the smart snippet can be pushed out to all of the forms using it.

That means the fields inside a smart snippet can't be edited from the form they are added to - they are managed from the smart snippet. When you make changes to a smart snippet, any forms that use it will be updated the next time they are published.

Creating smart snippets

You can create a smart snippet from the forms explorer in the same way as any other type of form. Right-click on the group where you would like to create a smart snippet and select "Create a form" then "Smart Snippet".

Smart snippets can also be created when you are working in the forms designer. Right-click on a layout field with other fields inside it, and select "Save this field as a smart snippet".

iCM will prompt you to give the smart snippet a name and description. It will be saved in the same group as your current form (and can be moved later).

Using smart snippets

Snippets in the toolbox are organised by the groups they are in:

To add a smart snippet to your form, expand a group, then drag the snippet onto the page:

Alternatively, you can add a Smart Snippet layout to your form, then pick a snippet from the drop-down.

The fields added using a smart snippet can't be edited from the form they have been added to. Instead, they are linked to their smart snippet. If a smart snippet is updated, changes will be picked up by any forms using it the next time the forms are published.

Field names in smart snippets

When you create a smart snippet, you must enter proper names for the fields. Leaving the default names (FIELD1, FIELD2, FIELD3 etc) will display an error and prevent you from saving the snippet.

When you add a smart snippet to your form, if the names of any fields in the snippet conflict with any fields already on your form (or if you add the same smart snippet more than once), the fields will be highlighted in red:

For example, if your form already has a field called DOB, the DOB field in the snippet will be highlighted.

To resolve the conflict, add a prefix to the Smart Snippet layout:

When a prefix is added to a smart snippet layout, all of the fields in the snippet have the prefix applied while they are part of this form:

The forms designer also checks for any references to those names within the snippet, and updates them too. This is to make sure that any JavaScript, Blockly or templating within the snippet continues to function after a field name has had a prefix applied.

This checking applies to field names in:

• Default functions
• Handler functions
• Validation functions
• Template manipulation functions
• Buttons
• The script action field
• The history writing actions
• The workflow actions
• Handlebars templates that use the {{FIELD}} helper
• Tokens that use the #FIELDNAME# syntax

If you create form variables using the Form Variable field, and don't set a variable name (ie, you use the field name as the variable name) references to that name will be updated too. You'll see this when using the Handlebars {{VARIABLE}} helper and tokens that use the %VARIABLENAME% syntax.

Updating smart snippets

If you make changes to the fields in a smart snippet, you can see which forms are using it from the "Show content using this smart snippet" menu item:

Once you have saved the changes in your snippet, iCM will display a list of any forms that have now become "stale". Stale forms are forms using a smart snippet that need to be republished so that they pick up your changes:

If you don't republish stale forms they'll continue to use the previous version of the smart snippet. The forms designer will display a warning when you edit a stale form:

You can also right click on a smart snippet and publish any forms using it:

Once forms have been republished, they'll automatically start using the latest version of the smart snippet.

Updates that result in conflicts

It might happen that you edit a smart snippet that is already being used on other forms, and add or change a field name that results in a conflict with a field on one of those forms.

If there are naming conflicts, you'll see an error message when republishing stale forms:

If this happens you can either change the name of the field in the snippet or form, or add a prefix to the snippet layout in the form that's using the snippet.