Field Marshal 2 & 3 » User guide – Support Centre - Lovestock & Leaf

1 Installing Field Marshal
1. 1.1 Setting up Lovely Up
2. 1.2 Installing Field Marshal (Help Center)
2 Configuring Field Marshal

2.6 Recommended configuration practices
1. 2.6.1 Conditional (nested) sub options
2. 2.6.2 Running plugins without showing or hiding a field
2.7 Field Aliases
1. 2.7.1 Naming of fields
2.8 Configuration Examples

Field Marshal 2 Release Notes
Field Marshal 3 Release Notes

Overview

Field Marshal handles conditional fields management for end-user request forms as well as tickets in the agent view of Zendesk. By using Field Marshal you can turn your Zendesk request form into a powerful form builder.

A brief description of the Field Marshal app is available here.

The conditional logic provides the capability to show or hide fields, and even the submit button on a Help Center request form, based on user selections. This allows you to the information your customer is asked to provide on your support site and tailor the form specifically to their needs.

On the agent ticket page your agents will only see fields and options that are relevant to the ticket/issue they are currently working on. This will also help prevent the agent from making mistakes if they are also required to create tickets on behalf of end-users, or complete ticket fields.

Customers who are not on an Enterprise Zendesk subscription can use Field Marshal to simulate multiple ticket forms.

Field Marshal runs on:

the New Zendesk Agent interface (historically referred to as “Lotus”)
the New Zendesk Help Center
and Lovestock & Leaf’s Feedback Widget.

Field Marshal does not have a user interface, it simply implements the configuration logic for the forms. This configuration guide only describes how to configure Field Marshal using Lovely app.

This guide was written based on version 2.4.26 of Field Marshal.

1 Installing Field Marshal

Installing Field Marshal can either be done by us or through our foxycart installer (docs).

If it was done by us, skip this section and go to 2. Configuring Field Marshal, as everything has been set up for you.
If through our foxycart installer, you will have 2 new apps installed: Field Marshal (agent) and Lovely. Field Marshal runs on agent ticket form and Lovely allows to define Field Marshal configs.
If Field Marshal (Help Center - running on end user request form), is not required, simply skip this section and go to 2. Configuring Field Marshal. Otherwise, contact us with your Field Marshal license key and Zendesk account (<<something>>.zendesk.com), we will provide you CloudMetro username & password to be used in the following steps.

1.1 Setting up Lovely

'Lovely' app (the grey cloud on the left bar) needs setup if it has not been set up during installation.

Click on the cloud icon:

On the left hand side of Lovely, there are 2 lists:

ZENDESK APPS: apps running on agent interface
CLOUDMETRO APPS: apps running on Help Center (end-user interface)

By default, Field Marshal will only appear under Zendesk Apps, but not Cloud metro apps, meaning Field Marshal is only running on the agent interface, but not end-user interface.

To get Field Marshal appears under CloudMetro app, select 'Lovely' on the left hand side (below 'CloudMetro Apps') and setup with:

CloudmetroURL = https://apps.cloudmetro.com/
Username = CloudMetro username we have provided (please contact us if you don't have this)
Password = CloudMetro password we have provided (please contact us if you don't have this)

If all info are correct, Field Marshal will now appear in both lists. Please contact us if this is not the case.

1.2 Installing Field Marshal (Help Center)

After Field Marshal appears under CloudMetro Apps list as above, clicking on it will allow to define Field Marshal config for the Help Center side.

At the bottom of the config space, there is a hash URL, record this hash.
(e.g. "0fcabe27756...." as in screenshot below)

Replace the hash_key in the following codes by the hash found above, then append the whole codes to the Document Head of your Help Center theme.

 <!-- [if lt IE 9]>
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.0.3/es5-shim.min.js"></script>
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/es5-shim/4.0.3/es5-sham.min.js"></script>
<![endif]-->
<script src="//cdn.cloudmetro.com/app-framework.js" type="text/javascript" data-lnl-hash="hash_key"></script>

In order to do this:

login as admin on Help Center
click on "Customize Design" on admin panel at the bottom right of the page
this will open theme selection page. On top left corner, click on "edit theme":
select Document Head in the dropdown

The Document Head may already have content in it, do not delete anything, just append the CloudMetro code to the bottom of it.

Save and publish the current theme. After this Field Marshal is running on the Help Center.

2 Configuring Field Marshal

2.1 Where to configure the Field Marshal app

Field Marshal (also referred to as FM) can be configured via our Lovely app.

Open Lovely by clicking on the cloud icon on your taskbar from agent interface, then click on corresponding Field Marshal side (Zendesk Apps = agent side, CloudMetro Apps = Help Center side) to configure FM for each side as screenshot below.

It is recommended to use YAML Configuration format to manage the config

2.2 Test Run

Test Run is currently available for Field Marshal Help Center only. This allows admin to test new config without deploying to all end users.

There are Release button and Update button at the bottom of Field Marshal (HelpCenter) config screen.

Update button is to save new config. And this new config does not apply to end-users ticket form yet. To see the new config in action, ticket form must be viewed with ?cache=off at the end of the url.

e.g. https://yourzendesk.zendesk.com/hc/en-us/requests/new?cache=off

This allows admin to test and see how new config work on the Help Center without affecting end-users request form.

Once tested , Release button is to roll out config to all end-users. This is irreversible and may take up to 30 mins for all end-users to have new Field Marshal config.

2.3 Basic concepts

The structure of the Field Marshal configuration has some basic concepts on which the app configuration is based. The key concept is that the rules are configured from the point of view of the fields.

When you are planning the construction of rules for Field Marshal, you can ask the following question for each field to get started: “This field must only show when….”.

The configuration settings for Field Marshal can be set using either JavaScript Object Notation (JSON) or Yet Another Markup Language (YAML). The examples in this guide are all in YAML format.

At a basic level Field Marshal hides/shows fields that are displayed by Zendesk on the customer request form and/or agent's interface ticket page. This means that Zendesk validations are still executed when the forms are submitted, regardless of whether the field was hidden or not.

Hidden mandatory fields:

FM has a built-in way to handle hidden fields that are set to mandatory under Admin > Ticket Fields by way of populating these mandatory fields on ticket submit if they are hidden at the time. Generally fields will be populated with a 0 or not_applicable, depending on field type. Dropdown fields are handled by selecting a special option, as detailed below.

The onus is on you to add an extra option to all mandatory dropdown fields that could be hidden by your FM config at any time. The option value is immaterial, but it is helpful to always use something like “n/a”. The tag for this option needs to be in the following format: ll_not_applicable_<number>, e.g. ll_not_applicable_1, ll_not_applicable_2, etc. Field Marshal will populate hidden mandatory fields with the option, but also hide this option from the dropdown field on the ticket page and request forms when the field is visible so that agents and end-users will not see this value.

2.3.1 Field map

The field map is used to define ‘friendly names’ for custom and system Zendesk ticket fields. These are then used in the FM configuration. You can also refer to fields on the Help Center request form or Feedback Widget using jQuery selectors.

More information about jQuery selectors can be found at the following link:

http://api.jquery.com/category/selectors/

The field map will be discussed in further detail in a later section.

2.3.2 Filter

A filter is used to determine whether the field configuration setting applies to the current state of the form. The available filters are described in a later section.

2.3.3 Plugin

A plugin is run on a field if that field setting applies to the current state of the form. Plugins generally start with a verb such as “show”. The available plugins are described in a later section.

2.4 Field map

As mentioned previously, the field map is a way of declaring friendly names or aliases for fields, in the following format.

alias: identifier

“alias” is the name you want to give to the field when you are referring to it in the configuration, and “identifier” is the way of identifying the field. The alias and identifier cannot have spaces, but you may use an underscore in the alias (_). Please note that the alias is case-sensitive.

The “identifier” can only be a number (for custom fields) or a text string (for system fields on the Help Center request form).

All fields referred to in the conditional setup must be declared in the field map section.

An example field map is shown below. Note that comments start with a hash (#).

field1: 1234578
field2: 2234577
field3: 3423435
field4: 4654578
field5: 5645453
# Help Center system fields
sys_email: '#request_anonymous_requester_email'
sys_subject: '#request_subject'
sys_description: '#request_description'
sys_attachment: '#request-attachments-pool'
sys_forms: '#request_issue_type_select'
sys_submit_button: '#new_request input[name="commit"]'

Where

field1 = Zendesk custom ticket field “custom_field_1234578”
field2 = Zendesk custom ticket field “custom_field_2234577”
field3 = Zendesk custom ticket field “custom_field_3423435”
field4 = Zendesk custom ticket field “custom_field_4654578”
field5 = Zendesk custom ticket field “custom_field_5645453”
email = jQuery selector for Help Center form field “#email_address”
sys_subject = jQuery selector for Help Center form field '#request_subject'
sys_description = jQuery selector for Help Center form field '#request_description'
sys_attachment = jQuery selector for Help Center form field '#request-attachments-pool'
sys_forms = jQuery selector for Help Center form field '#request_issue_type_select'
sys_submit_button = jQuery selector for Help Center form field '#new_request input[name="commit"]'

Custom ticket field IDs can be found by editing the ticket field via Admin>Ticket Fields, or by using the ID Viewer feature in the Cloudmetro Lovely app (the cloud icon) that was installed with your FM (recommended).

System fields don't have IDs as custom fields. However they can be referenced as follow (note that some are read-only):

# System fields on agent ticket form
sys_subject: 'subject'
sys_status: 'status'
sys_type: 'type'
sys_priority: 'priority'
sys_comment: 'comment'
sys_description: 'description'
sys_ticket_form_id: 'ticket_form_id'
sys_due_date: 'due_date'
sys_problem_ticket_id: 'problem'
sys_brand: 'brand'
sys_requester_id: 'requester.id'
sys_requester_email: 'requester.email'
sys_requester_name: 'requester.name'
sys_assignee_id: 'assignee.user.id'
sys_assignee_name: 'assignee.user.name'
sys_group_id: 'assignee.group.id'
sys_group_name: 'assignee.group.name'
sys_collaborator_id: 'collaborator.id'
sys_collaborator_email: 'collaborator.email'
sys_tags: 'tags'
sys_shared_with_id: 'sharedWith.id'
sys_shared_with_name: 'sharedWith.name'
sys_shared_with_partnername: 'sharedWith.partnerName'
sys_user_name: 'user.name'
sys_user_email: 'user.email'
sys_user_groups: 'user.groups'
sys_user_first_name: 'user.first_name'
sys_user_last_name: 'user.last_name'
sys_user_role: 'user.role'
sys_user_avatar_url: 'user.avatar_url'

# System fields on end user ticket form
sys_email: '#request_anonymous_requester_email'
sys_subject: '#request_subject'
sys_description: '#request_description'
sys_attachment: '#request-attachments-pool'
sys_forms: '#request_issue_type_select'
sys_submit_button: '#new_request input[name="commit"]'

2.5 Rules configuration

The configuration setting for Field Marshal houses the conditional logic. An example of a very simple configuration is shown below.

conditions:
  - show: field2
    when: [field1, '==', field1_tag1]
  - show: field3
    when: [field2, '<', 30]
  - show: [field4, field5]
    when: [field3, '>=', 50]

field2 (declared in the field map, as explained in the previous section) is only shown when dropdown field1 has the option with tag field1_tag1 selected, otherwise it remains hidden
field3 is only shown when field2 is less than 30, otherwise it remains hidden
field4 and field5 are shown when field3 is greater than or equal to 50, otherwise it remains hidden

NOTE: If a field is not configured with conditions, it will be displayed by default.

2.5.1 Filters

Filters are a way of determining whether the field configuration applies to the current form state. The filters can be placed in any one of following locations. Some filters cannot be placed in some filter locations. If this is the case, then these are noted in the description of the filter.

#globalFilter
- formLocation: agent
  #locationFilter
  - ticketForm: 54678
    conditions:
      #formFilter
      - show: field2
        #fieldFilter
        when: [field1, '==', field1_tag1]

When using the filters you can provide one, or multiple values. The following examples show these two different configuration options:

filter: single

The above is showing a single value being used for the filter.

filter: [multiple1, multiple2, multiple3]

The above is showing three different values used for the filter.

The following sections describe the filters which are available.

2.5.1.1 withOrganization

The “withOrganization” filter allows you to define rules based on the requester’s organisation. Note the configuration setting uses the American spelling to be in-line with the Zendesk names. An example of how to use this filter is shown below.

withOrganization: 24014300

The organisation is taken from the organisation that is assigned to users within Zendesk. You can also use a special value of “ll-none” which means that the requester is not in an organisation. The ID of the organisation (or organisations) can be found in the browser address bar when you view the organisation via Admin>Manage>People

Click on the “oganizations” link under the search box.

Search and find the organisation you would like to find the ID of and click on the name. The ID of the organisation is found in the URL when you view the organisation in Zendesk. It is the number to the right of “organizations/”.

2.5.1.2 withRole

The “withRole” filter allows you to define rules based on the assignee’s role. An example of how to use this filter is shown below.

withRole: [agent, admin]

The roles are the preconfigured roles within Zendesk or custom roles. A light agent is considered a custom role and has a number as an identifier.

end-user = End user
agent = Agent
admin = Administrator
123445 = Custom role or Light Agent (Enterprise only)

If you have an Enterprise subscription to Zendesk, the ID of the custom role (or roles) can be found via Admin<Manage>People.

Click on the “roles” link under the search box.

Search and find the role (or roles) you want to use, and hover over the edit button. The ID will be in the tooltip between “roles” and “edit”.

2.5.1.3 withGroup

The “withGroup” allows you to define rules based on the assignee’s group. An example of how to use the filter is shown below.

withGroup: 20166158

The group is taken from the group that is assigned to the agents within Zendesk. You can also use a special value of “ll-none” which means that the assignee is not in a group. The group ID can be found via the ID Viewer feature in the Cloudmetro app on the Field Marshal configuration page.

2.5.1.4 ticketForm

The “ticketForm” filter allows you to define rules based on the ticket form. This is only available to customers who have an Enterprise subscription to Zendesk. An example of how to use the filter is shown below.

ticketForm: 12345

The number is the ID of the ticket form. To ID of the ticket form can be found via the ID Viewer feature in the Cloudmetro app on the Field Marshal configuration page.

2.5.1.5 formLocation

The “formLocation” filter allows you to define rules based on the ticket form location. An example of how to use the filter is shown below.

formLocation: agent

The only supported values for this are:

agent = The ticket form found in the new Zendesk Agent interface
helpCenter = The new request form found in the new Zendesk Help Center
feedbackWidget = The feedback widget

Please note that, since the Help Center and Agent configurations are usually not identical, and you have two separate configuration files for these, the formLocation filter is not often used.

2.5.1.6 ticketStatus

The “ticketStatus” filter allows you to define rules based on the current ticket status. An example of how to use this filter is shown below.

ticketStatus: [new, open]

The values are the following values:

new
open
pending
hold
solved
closed

2.5.1.7 url

Note: this filter is only available on Help Center location.

The “url” filter allows you to define rules based on the url for the form. An example of how to use the filter is shown below.

[url, ‘contains’, ‘zendesk.com’]

The general form of the filter is:

[url, comparison, value]

The only supported values for the comparison are:

‘contains’ means that the URL where the request form is being hosted contains the value
‘not contains’ means that the URL where the request form is being hosted does not contain the value
‘==’ or ‘equals’ means that the URL where the request form must equal the value. Note you must include the protocol (eg: https://www.zendesk.com). This can also be passed an array of values and it will match one of those values
‘!=’ or ‘not equals’ means that the URL where the request form must not equal the value. Note you must include the protocol (eg: https://www.zendesk.com).

2.5.1.8 ticketTags

The “ticketTags” filter allows you to define rules based on a tag on a ticket. An example of how to use the filter is shown below. This filter is only valid on the agent ticket page.

[ticketTags, ‘contains’, ‘field1_tag1’]

The general form of the filter is:

[ticketTags, comparison, value]

The only supported values for the comparison are:

‘contains’ means that the tag is present on the ticket
‘not contains’ means that the tag is not present on the ticket

2.5.1.9 fieldLength

The general form of the filter is:

[fieldLength, comparison, value]

2.5.2 Plugins

Plugins are actions which can be run on a field to perform some sort of action. The type of plugin will determine where it can be placed in the configuration. Examples of how to use a plugin are shown below.

[examplePlugin, field1, argument1, argument2]

The above is showing the use of the “examplePlugin” which is being applied to the field “field1” and passing two arguments to the plugin. This example is when the plugin is in the “conditionalFieldPlugin” location.

examplePlugin: [field1, argument1, argument2, argument3]

The above is showing the use of the “examplePlugin” which is being applied to the field “field1” and passing three arguments to the plugin. This example is when the plugin is not in the “conditionalFieldPlugin” location.

If you would like to run a plugin on more than one field in a location other than “conditionalFieldPlugin” location you can use the following form:

examplePlugin: [[field1, argument1, argument2, argument3], [field2, argument1, argument2, argument3]]

conditions:
  #globalPlugin
  - formLocation: agent
    #locationPlugin
    - ticketForm: ticket_form_1
      #formPlugin
      - show: field2
        #fieldPlugin
        when:
          - [[field1,'==',field1_tag1], <conditionalFieldPlugin>]

The higher up the hierarchy the filter is defined, the more fields it applies to. In this case the different plugins shown in bold will apply to the following fields:

globalPlugin = All fields in all form locations for all ticket forms
locationPlugin = All fields for all ticket forms in a specific ticket form location
formPlugin = All fields in a specific ticket form for a specific ticket form location
fieldPlugin = Only the field which the plugin is defined for
conditionalFieldPlugin = Only the field when the condition is met shall the plugin run

As a guide, if you only need a plugin to be run once, then put it in the “globalPlugin”, “locationPlugin” or “formPlugin” locations.

The plugins which are run in the “conditionalFieldPlugin” location are run when the preceding condition is met.

Each of the available plugins and their use are explained below.

2.5.2.1 hideOptions

The “hideOptions” plugin allows you to hide certain options from a drop-down list.

[hideOptions, field1, field1_tag1, field1_tag2]

In the example above, the options with tags “field1_tag1” and “field1_tag2” will be hidden when field1 is shown. This example is when the plugin is in the “conditionalFieldPlugin” location.

hideOptions: [field1, field1_tag1, field1_tag2]

This above example is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.2 showOptions

The “showOptions” plugin only shows the listed options in a drop-down list.

[showOptions, field1, field1_tag1, field1_tag2]

In the example above only the options with tags “field1_tag1” and “field1_tag2” will be shown when field1 is shown. This example is when the plugin is in the “conditionalFieldPlugin” location.

showOptions: [field1, field1_tag1, field1_tag2]

This above example is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.3 prePopulate

The “prePopulate” plugin allows you to configure pre-populated information for a given field when the request form or ticket page is loaded. If the field already has a value, prePopulate will not change the value of the field.

[prePopulate, field1, “the value”]

The example above pre-populates the field “field1” with the value “the value”. This example is when the plugin is in the “conditionalFieldPlugin” location.

prePopulate: [field1, “the value”]

This above example is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.4 notEmpty

The “notEmpty” plugin allows you to stop the form submission or ticket being updated if the given field is empty. This can be used to simulate a mandatory field which only shows up in some cases. An example of how to use this plugin is shown below.

[notEmpty, field1, field2]

The example above defines that the fields “field1” and “field2” cannot be empty when it is visible and the form is submitted or saved. This example is when the plugin is in the “conditionalFieldPlugin” location.

notEmpty: [field1, field2]

The example above defines that the fields “field1” and “field2” cannot be empty when it is visible and the form is submitted or saved. This example is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.5 subjectText

The “subjectText” plugin can be used to pre-set the value of the subject field. This only applies for the formLocation of “helpCenter” and “feedbackWidget”.

[subjectText, “the text I want for the subject”]

The above example sets the subject field to have the value of “the text I want for the subject”. This example is when the plugin is in the “conditionalFieldPlugin” location.

subjectText: “the text I want for the subject”

The above example is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.6 show

The “show” plugin is used to show a field. The “show” plugin can also use the “when” plugin to define the conditional rules for when the field is shown. If “when” is not provided, the field is always shown. The “conditionalFieldPlugin” location cannot be used for this plugin.

show: [field1, field2]
when: [field3, ‘==’, ‘field3_tag1’]

The above example shows both the fields “field1” and “field2” when the field “field3” has the value of “field3_tag1”.

2.5.2.7 hide

The “hide” plugin is used to show a field. The “hide” plugin can also use the “when” plugin to define the conditional rules for when the field is hidden. If “when” is not provided then the field is always hidden. The “conditionalFieldPlugin” location cannot be used for this plugin.

hide: [field1, field2]
when: [field3, ‘==’, ‘field3_tag1’]

The above example hides both the fields “field1” and “field2” when the field “field3” has the value of “field3_tag1”.

2.5.2.8 when

The “when” plugin provides the majority of the conditional fields logic. The “when” plugin can only be used as a part of “show” and “hide” plugins.

show: [field1, field2]
when: [field3, ‘==’, ‘field3_tag1’]

The above example shows both the fields “field1” and “field2” when the field “field3” has the value of “field3_tag1”.

The “when” plugin understands the concept of “and” and “or” conditions. Examples of these are shown below:

AND condition:

show: [field1]
when: [[field3, ‘==’, ‘field3_tag1’], [field2, ‘==’, ‘field2_tag1’]]

which can also be writtent as:

show: [field1]
when:
  - [[field3, ‘==’, ‘field3_tag1’], [field2, ‘==’, ‘field2_tag1’]]

The above example shows the field “field1” when the field “field3” has the value “field3_tag1” and the field “field2” has the values “field2_tag1”. Note the two levels of square brackets. For clarity the above is the “AND” condition.

OR condition:

show: [field1]
when: [[[field3, ‘==’, ‘field3_tag1’], [field3, ‘==’, ‘field3_tag2’]]]

which can also be written as:

show: [field1]
when:
	- [field3, ‘==’, ‘field3_tag1’]
	- [field3, ‘==’, ‘field3_tag2’]

The above example shows the field “field1” when the field “field3” has the value “field3_tag1” or the field “field3” has the values “field3_tag2”. Note the three levels of square brackets. For clarity the above is the “OR” condition.

In the 2nd format of this example abvoe, the config lines preceded with a dash (-) make up OR statements. You can also combine one of the OR statements with an AND statement by adding the AND statement to the same OR line as follows.

show: [field1]
when:
	- [[field3, ‘==’, ‘field3_tag1’], [field4, ‘!=’, field4_tag1]]
	- [field3, ‘==’, ‘field3_tag2’]

In the above example field1 will show when field3 equals field3_tag1 AND field4 does not equal field4_tag1, OR it will show when field3 equals field3_tag2.

It is important to remember that only one OR condition must be able to be true at any time on the request form. If two OR conditions are found to be true, only one will be executed.

The general form of the “when” plugin when only using brackets is as follows. However, using dashes and new lines to separate OR conditions as above is recommended as it is more readable.

show: field
when: [[[clause1], [clause2]], [clause3], [[clause4], [clause5]]]

In psuedo-code you read this as:

if ( (clause1 or clause2) and clause3 and (clause4 or clause5) )

is satisfied then show field

This is a little bit mathematical, but this is also what gives Field Marshal the power and flexibility.

The clause has the general form of:

[field, comparison, value]

The comparison can have the following values:

‘==’ means that the field must equal the value. This can also be passed an array of values and it will match one of those values.
‘!=’ means that the field must not equal the value. This can also be passed an array of values and it will not match one of those values.
‘<’ means the the field must be less than the value
‘lower than’ means the the field must be less than the value
‘<=’ means the field must be less than or equal to the value
‘lower than or equal’ means the field must be less than or equal to the value
‘>’ means that the field must be greater than the value
‘higher than’ means that the field must be greater than the value
‘>=’ means that the field must be greater than or equal to the value
‘higher than or equal’ means that the field must be greater than or equal to the value

***Important***
For attachments count condition

e.g.

[sys_attachments, '>', 2]

the field mapping for the attachments must be set to #request-attachments-pool:

i.e.

sys_attachments: '#request-attachments-pool'

Otherwise the attachments count condition will not work.

2.5.2.9 placeHolder

The placeholder plugin allows you to configure placeholder text (form of help text telling the user what or how to populate into the field) which appears in a text box or textarea box in ticket forms. This plugin only works in the ticket form locations of helpCenter and feedbackWidget.

[placeHolder, field, “the text I want for the placeholder”]

The example above sets the placeholder text for the field “field”. This example is when the plugin is in the “conditionalFieldPlugin” location.

[placeHolder, field, “the text I want for the placeholder”]

The example above is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.10 fieldOrder

The fieldOrder plugin allows you to configure the order of fields in a ticket form. This plugin is only available in the globalPlugin, locationPlugin and formPlugin locations. If you want to configure the order of the fields you should nominate all the fields in the form. If you do not list all the fields, the fields you have listed will appear at the top of the form, and the other fields will appear in an unpredictable order above or below the ordered fields.

fieldOrder: [field1, field2]

The example above defines the order of the fields for the form.

2.5.2.11 keepValue

The “keepValue” plugin allows you to retain the value of a hidden field. The default behaviour of Field Marshal is to clear the value of hidden fields. This plugin changes that behaviour. Note that this also affects checks on the fields. So if you have a condition based on the value of a field with a “keepValue” you cannot assume that the field will be empty.

keepValue: [field1, field2]

2.5.2.12 Clobber

The “clobber” plugin allows you to configure pre-populated information for a given field. If the field already has a value, clobber will change the value of the field. Use this with caution! An example of how to use this plugin is shown below.

[clobber, field1, “the value”]

The example above sets the field “field1” with the value “the value”. This example is when the plugin is in the “conditionalFieldPlugin” location.

clobber: [field1, “the value”]

The example above is when the plugin is not in the “conditionalFieldPlugin” location.

2.5.2.13 noAutoScroll

By default Field Marshal will automatically scroll your form to help you with entering the details. If you do not want this functionality then you can turn off the auto scroll function. This is only valid when the plugin is not in the “conditionalFieldPlugin” location, and it is only valid for form location of “helpcenter”.

noAutoScroll: true

The default value is “false”.

There is also a helper which is shown on the bottom left of the screen which allows an end user to disable the auto scroll while completing a form.

Clicking on the tab will set the “Autoscroll” to be off. Clicking it again will turn “Autoscroll” on.

2.5.2.14 hideAutoScrollHelper

You may want to have auto scroll on for your forms and not allow the user to turn off the functionality. To do this set the “hideAutoScrollHelper” to true. This is only available when the plugin is not in the “conditionalFieldPlugin” location, and it is only valid for form location of “helpcenter”.

hideAutoScrollHelper: true

This setting has no effect if you have set the noAutoScroll plugin value is set to “true”. The default value for this plugin is “false”.

2.5.2.15 groupFields

Field Marshal can group fields together under a title for better presentation. This configuration option is only available for the form location of “helpcenter”. An example of how to use this configuration options is shown below.

groupFields: [“the title for the group of fields”, style_class, field1, field2, field3]

groupFields:
	- [“the title for the 1st group of fields”, ‘’, field1, field2]
	- [“the title for the 2nd group of fields”, ‘’, field3, field4]

The first example above groups fields “field1”, “field2”, “field3” into a group and gives it the title “the title for the group of fields”. This is available when the plugin is not in the “conditionalFieldPlugin” location. The 2nd example has two groups.

The first parameter is the title of the group, and this is optional. If you do not want to specify a title, then put an empty string (‘’). The second parameter is the CSS style class to use for the group heading, this is usually left as an empty string (‘’) as per the second example.

2.5.2.16 fakeRequired