This article describes the behaviour of forms when they are displayed in a read-only mode. It shouldn't be confused with individual form fields being set as read-only as part of a normal, active form.
When are read-only forms used?
There are two types of read-only form (known as read-only modes) used by the platform.
The first is generally only found within iCM, and is simply called readonly. You find these forms used by article extras when you "view" an article rather than editing it, and in the form data browser.
The second, called readonlynoctrl (read-only no control), is used more widely by the front-end sites when displaying form data that's already been saved. This data is stored using the history service, and you'll see it displayed by the Self Service and User Request templates. This mode, and these templates, are the focus of this article.
Where does the form data come from?
The read-only form data displayed by the Self Service and User Requests templates is stored in the history service. It is saved using the workflow related form fields (Workflow - Start Action, Workflow - Complete Task Action and Workflow - Message Action) or the History - Write Event field. Each of these fields let you choose whether or not the full form submission is saved, and give you some ability to manipulate the data before it's saved.
In the case of the workflow fields, saved form data will look something like:
"event": {
"private": false,
"event": "STARTWORKFLOW",
"userRole": "user",
"userId": "TIMG",
"proxyUserId": null,
"description": "Form submitted",
"formData": {
"data": {
"EMAIL": "support@gossinteractive.com",
"QUESTION": "Hi"
},
"formName": "STARTAPROCESS",
"typeName": "FORM_STARTAPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
}
}
(Note that in the case of the history write event, or if your form contains repeating pages, the structure of the data will be slightly different and include page names.)
You'll see this read-only data in the summaries displayed by the Self Service and User Requests templates. For more information about exactly what form data is displayed in which section of each template, see the Workflow and History Data In Assisted Service, Self Service and User Requests article.
Which form is used to display the data?
The name of the form that should be used to display the data is saved in the history event as the value of the formName. In the example above the data will be displayed by a form called "STARTAPROCESS". Once this has been set it can't be changed.
Most of the time, the form used to display the data is the same form that saved the data. However, the form fields that write history do let you override this and pick a different form. For example, in the Workflow Start Action form field, you can set a "Summary Form Name":
This is particularly useful for summary events, as they are designed to show a summary of data from across a history, not just a single form submission.
Standard read-only behaviour
The standard behaviour, when form data is requested from a history event, is to use the form that created the event to display all of the submitted data in the original fields, laid out as a table. Any empty fields will also be included as empty rows. Data is mapped to the correct field by field name.
JavaScript functions
Field default functions are executed in read-only mode. That means the value could be updated in the read-only view. The value from the history event is passed to the function as the currentValue, so the standard function signatures guard against any unexpected behaviour by checking to see if the value already exists:
Form and page server-side initialisation handlers are also called. Their function signatures are passed the mode ("normal", "readonly" or "readonlynoctrl"), which can be used like this:
In the majority of cases you will only want to run handlers in "normal" mode.
Field handlers and other browser-side functions are not executed.
Custom read-only templates
Every form can have a custom read-only template written using Handlebars Editors.
Custom read-only templates are designed to work when the form displaying the data is the same form that saved the data. You can use the
Other Handlebars helpers, like navigation buttons, cannot be used.
JavaScript functions
When you use a custom read-only template, because the form fields themselves are not used to generate the read-only view, none of the field functions are executed.
Form and page server-side initialisation handlers are called in the same way as described above.
Read-only data function
If you write your own read-only template (or use one of the defaults) you can also use the read-only data function to add to and manipulate the data that gets passed to it.
The current form data is passed to the function as a JSON object in the value parameter.
The result of the function is available to the template in the "this" object.
Example
This example calls an end point, then passes the result to the template. The form data, the value, is the same form data as shown in the history event at the top of this article.
Here's the data function:
And the template to display it (see this.example in the final row of the table):
<div class="icmformdata">
<table class="icmformdatapagetable">
<tbody>
<tr>
<td class="icmformdatalabel">From</td>
<td class="icmformdatavalue">{{FIELD "EMAIL"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">The question</td>
<td class="icmformdatavalue">{{FIELD "QUESTION"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">New value</td>
<td class="icmformdatavalue">{{this.example}}</td>
</tr>
</tbody>
</table>
</div>
And the result:
Share this page
