蜜豆视频

Get Started with input forms gs-ac-forms

When you create or extend a schema, you need to create or modify the associated input forms to make those changes visible to end-users.

An input form lets you edit an instance associated with a data schema from the 蜜豆视频 Campaign client console. The form is identified by its name and namespace.

The identification key of a form is a string made up of the namespace and the name separated by a colon, for example: 鈥渃us:contact鈥�.

Edit input forms

Create and configure input forms from the Administration > Configuration > Input forms folder of the client console:

The editing zone lets you enter the XML content of the input form:

The preview generates a display of the input form:

Form structure

The description of a form is a structured XML document that observes the grammar of the form schema xtk:form.

The XML document of the input form must contain the <form> root element with the name and namespace attributes to populate the form name and namespace.

<form name="form_name" namespace="name_space">
...
</form>

By default, a form is associated with the data schema with the same name and namespace. To associate a form with a different name, set the entity-schema attribute of the <form> element to the name of the schema key. To illustrate the structure of an input form, let us describe an interface using the 鈥渃us:recipient鈥� example schema:

<srcSchema name="recipient" namespace="cus">
  <enumeration name="gender" basetype="byte">
    <value name="unknown" label="Not specified" value="0"/>
    <value name="male" label="Male" value="1"/>
    <value name="female" label="Female" value="2"/>
  </enumeration>

  <element name="recipient">
    <attribute name="email" type="string" length="80" label="Email" desc="E-mail address of recipient"/>
    <attribute name="birthDate" type="datetime" label="Date"/>
    <attribute name="gender" type="byte" label="Gender" enum="gender"/>
  </element>
</srcSchema>

The input form based on the example schema:

<form name="recipient" namespace="cus">
  <input xpath="@gender"/>
  <input xpath="@birthDate"/>
  <input xpath="@email"/>
</form>

The description of the edit controls starts from the <form> root element. An edit control is entered in an <input> element with the xpath attribute containing the path of the field in its schema.

The edit control automatically adapts to the corresponding data type and uses the label defined in the schema.

By default, each field is displayed on a single line and occupies all available space depending on the type of data.

All form attributes are listed in Campaign Classic v7 documentation.

Formatting formatting

The layout of the controls looks like the layout used in HTML tables, with the possibility of dividing a control into several columns, interlacing elements, or specifying the occupation of available space. Remember, however, that formatting only lets you divide the area up by proportions; you cannot specify fixed dimensions for an object.

To display the controls of the above example in two columns:

<form name="recipient" namespace="cus">
  <container colcount="2">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email"/>
  </container>
</form>

The <container> element with the colcount attribute lets you force the display of child controls onto two columns.

The colspan attribute on a control extends the control by the number of columns entered in its value:

<form name="recipient" namespace="cus">
  <container colcount="2">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
</form>

By populating the 迟测辫别=鈥渇谤补尘别鈥� attribute, the container adds a frame around the child controls with the label contained in the label attribute:

<form name="recipient" namespace="cus">
  <container colcount="2" type="frame" label="General">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
</form>

A <static> element can be used to format the input form:

<form name="recipient" namespace="cus">
  <static type="separator" colspan="2" label="General"/>
  <input xpath="@gender"/>
  <input xpath="@birthDate"/>
  <input xpath="@email" colspan="2"/>
  <static type="help" label="General information about recipient with date of birth, gender, and e-mail address." colspan="2"/>
</form>

The <static> tag with the separator type lets you add a separator bar with a label contained in the label attribute.

A help text was added using the <static> tag with help type. The content of the text is entered in the label attribute.

Use containers containers

Use containers to group a set of controls. They are represented by the <container> element. They were used above to format controls over several columns.

The xpath attribute on a <container> lets you simplify the referencing of child controls. The referencing of controls is then relative to the parent <container> parent.

Example of a container without 鈥渪path鈥�:

<container colcount="2">
  <input xpath="location/@zipCode"/>
  <input xpath="location/@city"/>
</container>

Example with the addition of 鈥渪path鈥� to the element called 鈥渓ocation鈥�:

<container colcount="2" xpath="location">
  <input xpath="@zipCode"/>
  <input xpath="@city"/>
</container>

Containers are used to construct complex controls using a set of fields formatted in pages.

Add tabs (notebook) tab-container

Use a notebook container to format data in pages that are accessible from tabs.

<container type="notebook">
  <container colcount="2" label="General">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
  <container colcount="2" label="Location">
    ...
  </container>
</container>

The main container is defined by the 迟测辫别=鈥渘辞迟别产辞辞办鈥� attribute. Tabs are declared in the child containers, and the label of the tabs is populated from the label attribute.

Add the 蝉迟测濒别=鈥渄辞飞苍鈥� attribute to force the vertical positioning of tab labels below the control. This attribute is optional. Default value is 鈥涡辫鈥�.

<container style="down" type="notebook"> ... </container>

Add icons (iconbox) icon-list

Use this container to display a vertical icon bar that lets you select the pages to be displayed.

<container type="iconbox">
  <container colcount="2" label="General" img="xtk:properties.png">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
  <container colcount="2" label="Location" img="nms:msgfolder.png">
    ...
  </container>
</container>

The main container is defined by the 迟测辫别=鈥渋肠辞苍产辞虫鈥� attribute. The pages associated with the icons are declared in the child containers. The label of the icons is populated from the label attribute.

The icon of a page is populated from the img="<image>" attribute, where <image> is the name of the image corresponding to its key made up of the name and namespace (e.g., 鈥渪tk:properties.png鈥�).

The images are available from the Administration > Configuration > Images node.

Hide containers (visibleGroup) visibility-container

You can hide a set of controls via a dynamic condition.

This example illustrates the visibility of controls on the value of the 鈥淕ender鈥� field:

<container type="visibleGroup" visibleIf="@gender=1">
  ...
</container>
<container type="visibleGroup" visibleIf="@gender=2">
  ...
</container>

A visibility container is defined by the attribute 迟测辫别=鈥渧颈蝉颈产濒别骋谤辞耻辫鈥�. The visibleIf attribute contains the visibility condition.

Examples of condition syntax:

Conditional display (enabledGroup) enabling-container

This container lets you enable or disable a set of data from a dynamic condition. Disabling a control prevents it from being edited. The following example illustrates the enabling of controls from the value of the 鈥淕ender鈥� field:

<container type="enabledGroup" enabledIf="@gender=1">
  ...
</container>
<container type="enabledGroup" enabledIf="@gender=2">
  ...
</container>

An enabling container is defined by the 迟测辫别=鈥渆苍补产濒别诲骋谤辞耻辫鈥� attribute. The enabledIf attribute contains the activation condition.

Edit a link editing-a-link

Remember that a link is declared in the data schema as follows:

<element label="Company" name="company" target="cus:company" type="link"/>

The edit control of the link in its input form is as follows:

<input xpath="company"/>

Target selection is accessible via the edit field. Entry is assisted by type-ahead so that a target element can easily be found from the first few characters entered. The search is then based on the Compute string defined in the targeted schema. If the schema does not exist after validation in the control, a confirmation message of on-the-fly target creation is displayed. The confirmation creates a new record in the target table and associates it with the link.

A drop-down list is used to select a target element from the list of records already created.

The Modify the link (folder) icon launches a selection form with the list of targeted elements and a filter zone.

The Edit link (magnifier) icon launches the edit form of the linked element. The form used is deduced by default on the key of the targeted schema. The form attribute lets you force the name of the edit form (e.g. 鈥渃us:company2鈥�).

You can restrict the choice of target elements by adding the <sysfilter> element from the link definition in the input form:

<input xpath="company">
  <sysFilter>
    <condition expr="[location/@city] =  'Newton"/>
  </sysFilter>
</input>

You can also sort the list with the <orderby> element:

<input xpath="company">
  <orderBy>
    <node expr="[location/@zipCode]"/>
  </orderBy>
</input>

Control properties control-properties

Add a list of links (unbound) list-of-links

A link entered in the data schema as a collection element (unbound=鈥渢rue鈥�) must go through a list in order to view all the elements associated with it.

The principle consists in displaying the list of linked elements with optimized data loading (downloading by data batch, execution of the list only if it is visible).

Example of a collection link in a schema:

<element label="Events" name="rcpEvent" target="cus:event" type="link" unbound="true">
...
</element>

The list in its input form:

 <input xpath="rcpEvent" type="linklist">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

List control is defined by the 迟测辫别=鈥渓颈苍办濒颈蝉迟鈥� attribute. The list path must refer to the collection link.

The columns are declared via the <input> elements of the list. The xpath attribute refers to the path of the field in the target schema.

A toolbar with a label (defined on the link in the schema) is automatically placed above the list.

The list can be filtered via the Filters button and configured to add and sort the columns.

The Add and Delete buttons let you add and delete collection elements on the link. By default, adding an element launches the edit form of the target schema.

The Detail button is automatically added when the 锄辞辞尘=鈥渢谤耻别鈥� attribute is completed on the <input> tag of the list: it lets you launch the edit form of the selected line.

Filtering and sorting can be applied when the list is being loaded:

 <input xpath="rcpEvent" type="linklist">
  <input xpath="@label"/>
  <input xpath="@date"/>
  <sysFilter>
    <condition expr="@type = 1"/>
  </sysFilter>
  <orderBy>
    <node expr="@date" sortDesc="true"/>
  </orderBy>
</input>

Define a relationship table relationship-table

A relationship table lets you link two tables with N-N cardinality. The relationship table contains only the links to the two tables.

Adding an element to the list should therefore let you complete a list from one of the two links in the relationship table.

Example of a relationship table in a schema:

<srcSchema name="subscription" namespace="cus">
  <element name="recipient" type="link" target="cus:recipient" label="Recipient"/>
  <element name="service" type="link" target="cus:service" label="Subscription service"/>
</srcSchema>

For our example, we start with the input form of the 鈥渃us:recipient鈥� schema. The list must display the associations with subscriptions to services and must allow you to add a subscription by selecting an existing service.

<input type="linklist" xpath="subscription" xpathChoiceTarget="service" xpathEditTarget="service" zoom="true">
  <input xpath="recipient"/>
  <input xpath="service"/>
</input>

The xpathChoiceTarget attribute lets you launch a selection form from the link entered. Creating the relationship table record will automatically update the link to the current recipient and the selected service.

List properties list-properties

Add a memory list controls memory-list-controls

Memory lists let you edit the collection elements using list data preloading. This list cannot be filtered or configured.

These lists are used on XML mapped collection elements or on low-volume links.

Add a column list column-list

This control displays an editable column list with a toolbar containing Add and Delete buttons.

<input xpath="rcpEvent" type="list">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

The list control must be filled in with the 迟测辫别=鈥渓颈蝉迟鈥� attribute, and the path of the list must refer to the collection element.

The columns are declared in the child <input> tags of the list. Column label and size can be forced with the label and colSize attributes.

The toolbar buttons can be aligned horizontally:

<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

The toolbarCaption attribute forces the horizontal alignment of the toolbar and enters the title above the list.

Enable zoom in a list zoom-in-a-list

Insertion and editing of the data in a list can be entered in a separate edit form.

<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true" zoomOnAdd="true">
  <input xpath="@label"/>
  <input xpath="@date"/>

  <form colcount="2" label="Event">
    <input xpath="@label"/>
    <input xpath="@date"/>
  </form>
</input>

The edit form is completed from the <form> element under list definition. Its structure is identical to that of an input form. The Detail button is added automatically when the 锄辞辞尘=鈥渢谤耻别鈥� attribute is completed on the <input> tag of the list. This attribute lets you launch the edit form of the selected line.

List properties list-properties-1

Add non-editable fields non-editable-fields

To display a field and prevent it from being edited, use the <value> tag or complete the 谤别补诲翱苍濒测=鈥渢谤耻别鈥� attribute on the <input> tag.

Example on the 鈥淕ender鈥� field:

<value value="@gender"/>
<input xpath="@gender" readOnly="true"/>

Add radio button radio-button

A radio button lets you choose from several options. The <input> tags are used to list the possible options, and the checkedValue attribute specifies the value associated with the choice.

Example on the 鈥淕ender鈥� field:

<input type="RadioButton" xpath="@gender" checkedValue="0" label="Choice 1"/>
<input type="RadioButton" xpath="@gender" checkedValue="1" label="Choice 2"/>
<input type="RadioButton" xpath="@gender" checkedValue="2" label="Choice 3"/>

Add a checkbox checkbox

A checkbox reflects a Boolean state (selected or not). By default, this control is used by 鈥淏oolean鈥� (true/false) fields. A variable taking a default value of 0 or 1 can be associated with this button. This value can be overloaded via the checkValue attributes.

<input xpath="@boolean1"/>
<input xpath="@field1" type="checkbox" checkedValue="Y"/>

Edit navigation hierarchy navigation-hierarchy-edit

This control builds a tree on a set of fields to be edited.

The controls to be edited are grouped in a <container> entered under the <input> tag of the tree control:

<input nolabel="true" type="treeEdit">
  <container label="Text fields">
    <input xpath="@text1"/>
    <input xpath="@text2"/>
  </container>
  <container label="Boolean fields">
    <input xpath="@boolean1"/>
    <input xpath="@boolean2"/>
  </container>
</input>

Add an expression field expression-field

An expression field updates a field dynamically from an expression; the <input> tag is used with an xpath attribute to enter the path of the field to be updated and an expr attribute containing the update expression.

<!-- Example: updating the boolean1 field from the value contained in the field with path /tmp/@flag -->
<input expr="Iif([/tmp/@flag]=='On', true, false)" type="expr" xpath="@boolean1"/>
<input expr="[/ignored/@action] == 'FCP'" type="expr" xpath="@launchFCP"/>

Context of forms context-of-forms

The execution of an input form initializes an XML document containing the data of the entity being edited. This document represents the context of the form, and can be used as a workspace.

Update the context updating-the-context

To modify the context of the form, use the <set expr="<value>" xpath="<field>"/> tag, where <field> is the destination field, and <value> is the update expression or value.

Examples of use of the <set> tag:

The context of the form can be updated when initializing and closing the form via the <enter> and <leave> tags.

<form name="recipient" namespace="cus">
  <enter>
    <set...
  </enter>
  ...
  <leave>
    <set...
  </leave>
</form>

Expression language expression-language-

A macro-language can be used in form definition in order to perform conditional tests.

The <if expr="<expression>" /> tag executes the instructions specified under the tag if the expression is verified:

<if expr="([/tmp/@test] == 'Test' or @lastName != 'Doe') and @boolean2 == true">
  <set xpath="@boolean1" expr="true"/>
</if>

The <check expr="<condition>" /> tag combined with the <error> tag prevents validation of the form and displays an error message if the condition is not satisfied:

<leave>
  <check expr="/tmp/@test != ''">
    <error>You must populate the 'Test' field!</error>
  </check>
</leave>

Assistant (wizard) wizards

An assistant guides you through a set of data entry steps in the form of pages. The data entered is saved when you validate the form.

To add an assistant, use the following type of structure:

<form type="wizard" name="example" namespace="cus" img="nms:rcpgroup32.png" label="Wizard example" entity-schema="nms:recipient">
  <container title="Title of page 1" desc="Long description of page 1">
    <input xpath="@lastName"/>
    <input xpath="comment"/>
  </container>
  <container title="Title of page 2" desc="Long description of page 2">
    ...
  </container>
  ...
</form>

The presence of the 迟测辫别=鈥渨颈锄补谤诲鈥� attribute on the <form> element lets you define the wizard mode in the construction of the form. The pages are completed from <container> elements, which are children of the <form> element. The <container> element of a page is populated with the title attributes for the title and desc to display the description under the page title. The Previous and Next buttons are automatically added to allow browsing between pages.

The Finish button saves the data entered and closes the form.

SOAP methods soap-methods

SOAP method execution can be launched from a populated <leave> tag at the end of a page.

The <soapcall> tag contains the call for the method with the following input parameters:

<soapCall name="<name>" service="<schema>">
  <param type="<type>" exprIn="<xpath>"/>
  ...
</soapCall>

The name of the service and its implementation schema are entered via the name and service attributes of the <soapcall> tag.

The input parameters are described on the <param> elements under the <soapcall> tag.

The parameter type must be specified via the type attribute. The possible types are as follows:

The exprIn attribute contains the location of the data to be passed as a parameter.

Example:

<leave>
  <soapCall name="RegisterGroup" service="nms:recipient">
    <param type="DOMElement" exprIn="/tmp/entityList"/>
    <param type="DOMElement" exprIn="/tmp/choiceList"/>
    <param type="boolean"    exprIn="true"/>
  </soapCall>
</leave>