Edit forms editing-forms
Overview
Marketers and operators use input forms to create, modify, and preview records. Forms show a visual representation of information.
You can create and modify input forms:
- You can modify the factory input forms that are delivered by default. The factory input forms are based on the factory data schemas.
- You can create custom input forms, based on data schemas that you define.
Forms are entities of xtk:form
type. You can view the input form structure in the xtk:form
schema. To view this schema, choose Administration > Configuration > Data schemas from the menu. Read more about form structure.
To access input forms, choose Administration > Configuration > Input forms from the menu:
To design forms, edit the XML content in the XML editor:
To preview a form, click the Preview tab:
Form types
You can create different types of input forms. The form type determines how users navigate the form:
-
Console screen
This is the default form type. The form comprises a single page.
-
Content Management
Use this form type for content management. See this use case.
-
Wizard
This form comprises multiple floating screens that are ordered in a specific sequences. Users navigate from one screen to the next. Read more.
-
Iconbox
This form comprises multiple pages. To navigate the form, users select icons at the left of the form.
-
Notebook
This form comprises multiple pages. To navigate the form, users select tabs at the top of the form.
-
Vertical pane
This form shows a navigation tree.
-
Horizontal pane
This form shows a list of items.
Containers
In forms, you can use containers for various purposes:
- Organize content within forms
- Define access to input fields
- Nest forms within other forms
Organize content
Use containers to organize content within forms:
- You can group fields into sections.
- You can add pages to multipage forms.
To insert a container, use the <container>
element. Read more.
Group fields
Use containers to group input fields into organized sections.
To insert a section into a form, use this element: <container type="frame">
. Optionally, to add a section title, use the label
attribute.
Syntax: <container type="frame" label="
section_title"> […] </container>
In this example, a container defines the Creation section, which comprises the Created by and Name input fields:
<form _cs="Coupons (nms)" entitySchema="xtk:form" img="xtk:form.png" label="Coupons"
name="coupon" namespace="nms" type="default" xtkschema="xtk:form">
<input xpath="@code"/>
<input xpath="@type"/>
<container label="Creation" type="frame">
<input xpath="createdBy"/>
<input xpath="createdBy/@name"/>
</container>
</form>
Add pages to multipage forms
For multipage forms, use a container to create a form page.
This example shows containers for the General and Details pages of a form:
<container img="ncm:book.png" label="General">
[…]
</container>
<container img="ncm:detail.png" label="Details">
[…]
</container>
Define access to fields
Use containers to define what is visible and to define access to fields. You can turn on or off groups of fields.
Nest forms
Use containers to nest forms within other forms. Read more.
References to images
To find images, choose Administration > Configuration > Images from the menu.
To associate an image with an element in the form, for example, an icon, you can add a reference to an image. Use the img
attribute, for example, in the <container>
element.
Syntax: img="
namespace
:
filename
.
extension
"
This example shows references to the book.png
and detail.png
images from the ncm
namespace:
<container img="ncm:book.png" label="General">
[…]
</container>
<container img="ncm:detail.png" label="Details">
[…]
</container>
These images are used for icons that users click to navigate a multipage form:
Create a simple form create-simple-form
To create a form, follow these steps:
-
From the menu, choose Administration > Configuration > Input forms.
-
Click the New button at the top right of the list.
-
Specify the form properties:
-
Specify the form name and the namespace.
The form name and the namespace can match the related data schema. This example shows a form for the
cus:order
data schema:code language-xml <form entitySchema="xtk:form" img="xtk:form.png" label="Order" name="order" namespace="cus" type="iconbox" xtkschema="xtk:form"> […] </form>
Alternatively, you can explicitly specify the data schema in the
entity-schema
attribute.code language-xml <form entity-schema="cus:stockLine" entitySchema="xtk:form" img="xtk:form.png" label="Stock order" name="stockOrder" namespace="cus" xtkschema="xtk:form"> […] </form>
-
Specify the label to be displayed on the form.
-
Optionally, specify the form type. If you do not specify a form type, the console screen type is used by default.
If you are designing a multipage form, you can omit the form type in the
<form>
element and specify the type in a container.
-
-
Click Save.
-
Insert the form elements.
For example, to insert an input field, use the
<input>
element. Set thexpath
attribute to the field reference as an XPath expression. Read more.This example shows input fields based on the
nms:recipient
schema.code language-xml <input xpath="@firstName"/> <input xpath="@lastName"/>
-
If the form is based on a specific schema type, you can look up the fields for this schema:
-
Click Insert > Document fields.
-
Select the field and click OK.
-
-
Optionally, specify the field editor.
A default field editor is associated with each data type:
- For a date-type field, the form shows an input calendar.
- For an enumeration-type field, the form shows a selection list.
You can use these field editor types:
table 0-row-2 1-row-2 2-row-2 3-row-2 Field editor Form attribute Radio button type="radiobutton"
Checkbox type="checkbox"
Edit tree type="tree"
Read more about memory list controls.
-
Optionally, define access to the fields:
table 0-row-3 1-row-3 2-row-3 3-row-3 Element Attribute Description <input>
read-only="true"
Provides read-only access to a field <container>
type="visibleGroup" visibleIf="
edit-expr"
Conditionally displays a group of fields <container>
type="enabledGroup" enabledIf="
edit-expr"
Conditionally enables a group of fields Example:
code language-xml <container type="enabledGroup" enabledIf="@gender=1"> […] </container> <container type="enabledGroup" enabledIf="@gender=2"> […] </container>
-
Optionally, use containers to group fields into sections.
code language-xml <container type="frame" label="Name"> <input xpath="@firstName"/> <input xpath="@lastName"/> </container> <container type="frame" label="Contact details"> <input xpath="@email"/> <input xpath="@phone"/> </container>
Create a multipage form create-multipage-form
You can create multipage forms. You can also nest forms within other forms.
Create an iconbox
form
Use the iconbox
form type to show icons at the left of the form, which take users to different pages in the form.
To change the type of an existing form to iconbox
, follow these steps:
-
Change the
type
attribute of the<form>
element toiconbox
:code language-xml <form […] type="iconbox">
-
Set a container for each form page:
-
Add a
<container>
element as a child of the<form>
element. -
To define a label and an image for the icon, use the
label
andimg
attributes.code language-xml <form entitySchema="xtk:form" name="Service provider" namespace="nms" type="iconbox" xtkschema="xtk:form"> <container img="xtk:properties.png" label="General"> <input xpath="@label"/> <input xpath="@name"/> […] </container> <container img="nms:msgfolder.png" label="Details"> <input xpath="@address"/> […] </container> <container img="nms:supplier.png" label="Services"> […] </container> </form>
Alternatively, remove the
type="frame"
attribute from the existing<container>
elements. -
Create a notebook form
Use the notebook
form type to show tabs at the top of the form, which take users to different pages.
To change the type of an existing form to notebook
, follow these steps:
-
Change the
type
attribute of the<form>
element tonotebook
:code language-xml <form […] type="notebook">
-
Add a container for each form page:
- Add a
<container>
element as a child of the<form>
element. - To define the label and the image for the icon, use the
label
andimg
attributes.
code language-xml <form entitySchema="xtk:form" name="Service provider" namespace="nms" type="notebook" xtkschema="xtk:form"> <container label="General"> <input xpath="@label"/> <input xpath="@name"/> […] </container> <container label="Details"> <input xpath="@address"/> […] </container> <container label="Services"> […] </container> </form>
Alternatively, remove the
type="frame"
attribute from the existing<container>
elements. - Add a
Nest forms
You can nest forms within other forms. For example, you can nest notebook forms within iconbox forms.
The level of nesting controls navigation. Users can drill down to subforms.
To nest a form within another form, insert a <container>
element and set the type
attribute to the form type. For the top-level form, you can set the form type in an outer container or in the <form>
element.
Example
This example shows a complex form:
-
The top-level form is an iconbox form. This form comprises two containers labelled General and Details.
As a result, the outer form shows the General and Details pages at the top level. To access these pages, users click the icons at the left of the form.
-
The subform is an notebook form that is nested within the General container. The subform comprises two containers that are labelled Name and Contact.
<form _cs="Profile (nms)" entitySchema="xtk:form" img="xtk:form.png" label="Profile" name="profile" namespace="nms" xtkschema="xtk:form">
<container type="iconbox">
<container img="ncm:general.png" label="General">
<container type="notebook">
<container label="Name">
<input xpath="@firstName"/>
<input xpath="@lastName"/>
</container>
<container label="Contact">
<input xpath="@email"/>
</container>
</container>
</container>
<container img="ncm:detail.png" label="Details">
<input xpath="@birthDate"/>
</container>
</container>
</form>
As a result, the General page of the outer form shows the Name and Contact tabs.
To nest a form within another form, insert a <container>
element and set the type
attribute to the form type. For the top-level form, you can set the form type in an outer container or in the <form>
element.
Example
This example shows a complex form:
-
The top-level form is an iconbox form. This form comprises two containers labelled General and Details.
As a result, the outer form shows the General and Details pages at the top level. To access these pages, users click the icons at the left of the form.
-
The subform is an notebook form that is nested within the General container. The subform comprises two containers that are labelled Name and Contact.
<form _cs="Profile (nms)" entitySchema="xtk:form" img="xtk:form.png" label="Profile" name="profile" namespace="nms" xtkschema="xtk:form">
<container type="iconbox">
<container img="ncm:general.png" label="General">
<container type="notebook">
<container label="Name">
<input xpath="@firstName"/>
<input xpath="@lastName"/>
</container>
<container label="Contact">
<input xpath="@email"/>
</container>
</container>
</container>
<container img="ncm:detail.png" label="Details">
<input xpath="@birthDate"/>
</container>
</container>
</form>
As a result, the General page of the outer form shows the Name and Contact tabs.
Modify a factory input form modify-factory-form
To modify a factory form, follow these steps:
-
Modify the factory input form:
- From the menu, choose Administration > Configuration > Input forms.
- Select an input form and modify it.
You can extend factory data schemas, but you cannot extend factory input forms. We recommend that you modify factory input forms directly without recreating them. During software upgrades, your modifications in the factory input forms are merged with the upgrades. If the automatic merge fails, you can resolve the conflicts. Read more.
For example, if you extend a factory schema with an additional field, you can add this field to the related factory form.
Validate forms validate-forms
You can include validation controls in forms.
Grant read-only access to fields
To grant read-only access to a field, use the readOnly="true"
attribute. For example, you might want to show the primary key of a record, but with read-only access. Read more.
In this example, the primary key (iRecipientId
) of the nms:recipient
schema is displayed in read-only access:
<value xpath="@iRecipientId" readOnly="true"/>
Check mandatory fields
You can check mandatory information:
- Use the
required="true"
attribute for the required fields. - Use the
<leave>
node to check these fields and show error messages.
In this example, the email address is required, and an error message is displayed if the user has not provided this information:
<input xpath="@email" required="true"/>
<leave>
<check expr="@email!=''">
<error>The email address is required.</error>
</check>
</leave>
Read more about expression fields and form context.
Validate values
You can use JavaScript SOAP calls to validate form data from the Console. Use these calls for complex validation, for example, to check a value against a list of authorized values. Read more.
-
Create a validation function in a JS file.
Example:
code language-js function nms_recipient_checkValue(value) { logInfo("checking value " + value) if (…) { logError("Value " + value + " is not valid") } return 1 }
In this example, the function is named
checkValue
. This function is used to check therecipient
data type in thenms
namespace. The value that is being checked is logged. If the value is not valid, then an error message is logged. If the value is valid, then the value 1 is returned.You can use the returned value to modify the form.
-
In the form, add the
<soapCall>
element to the<leave>
element.In this example, a SOAP call is used to validate the
@valueToCheck
string:code language-xml <form name="recipient" (…)> (…) <leave> <soapCall name="checkValue" service="nms:recipient"> <param exprIn="@valueToCheck" type="string"/> </soapCall> </leave> </form>
In this example, the
checkValue
method and thenms:recipient
service are used:- The service is the namespace and the data type.
- The method is the function name. The name is case-sensitive.
The call is performed synchronously.
All exceptions are displayed. If you use the
<leave>
element, then users cannot save the form until the entered information is validated.
This example shows how you can make service calls from within forms:
<enter>
<soapCall name="client" service="c4:ybClient">
<param exprIn="@id" type="string"/>
<param type="boolean" xpathOut="/tmp/@count"/>
</soapCall>
</enter>
In this example, the input is an ID, which is a primary key. When users fill the form for this ID, a SOAP call is made with this ID as the input parameter. The output is a boolean that is written to this field: /tmp/@count
. You can use this boolean inside the form. Read more about form context.