| Table of Contents |
|---|
What are forms
A form is a graphical representation of a repository object as a set of fields, corresponding to the attributes of the object. It is possible to create new objects, view and edit existing ones, using the forms. An example of the edit form with two fields is shown in the figure below:
Structure of forms
Forms consist of three different kinds of blocks:
...
Description of forms is done in XML, in particular, description can be as follows for the presented form:
| Code Block |
|---|
<view class="letters:income" id="register"> <field prop="idocs:registrationNumber"> <region name="select" template="number-generate"> <param name="template">idocs-income-number-template</param> </region> <invariant on="mandatory" language="explicit">true</invariant> </field> <field prop="idocs:registrationDate"> <invariant on="mandatory" language="explicit">true</invariant> </field> </view> |
...
Finally, one can see from the given example of the XML definition of the form that additional invariants can be specified for fields. These invariants will be valid only for the form involved. More information on invariants can be found in the document “Modeling content in Alfresco ECM and Citeck EcoS”ECOS”.
Templates
Each element (view, field, region) shall have a specific template (template). The template determines the appearance of the element in the interface. The template can be set explicitly in a form layout, or it can be assigned through rules by default (see Rules).
...
Parameters can be passed to templates, for example, in the template number-generate the parameter template specifies whether auto-numbering template to use:
...
| Code Block |
|---|
<region name="select" template="number-generate"> <param name="template">idocs-income-number-template</param> </region> |
Identifying elements
Most of the form elements have IDs.
A field (field) always matches any attribute (property or association). In order to set an attribute, to which the field corresponds, the following notation is used:
| Code Block |
|---|
<field prop="idocs:registrationNumber" /> <field property="idocs:registrationDate" /> <field assoc="letters:reporterOrganization" /> <field association="letters:subdivision" /> |
...
| Code Block |
|---|
<view class="letters:income"> ... </view> |
If the view is simply a set of fields within the form, it usually has no ID.
| Code Block |
|---|
<view> ... </view> |
...
| Code Block |
|---|
<view class="letters:income"> ... </view> <view class="letters:income" id="register"> ... </view> |
Form files
Forms are defined in XML files of the following structure:
| Code Block |
|---|
<?xml version="1.0" encoding="UTF-8"?> <views xmlns="http://www.citeck.ru/ecos/views/1.0"> <imports>...</imports> <!—form definition --> </views> Instead of a comment <!-- form definition -->, form definitions are situated in files as described above: <view class="letters:income> ... </view> |
...
| Code Block |
|---|
<import uri="http://www.alfresco.org/model/dictionary/1.0" prefix="d" /> <import uri="http://www.alfresco.org/model/content/1.0" prefix="cm" /> <import uri="http://www.citeck.ru/model/content/idocs/1.0" prefix="idocs" /> <import uri="http://www.citeck.ru/model/letters/1.0" prefix="letters" /> |
...
Loading forms
The form can be loaded during the server starting, using “bootstrap” procedure (similar to how models and invariants are loaded). To do this one shall specify the following strings in the file *-context.xml:
...
| Code Block |
|---|
<bean parent="nodeViewsDeployer"> <property name="location" value="alfresco/extension/views/letters-views.xml" /> </bean> |
The property Location contains the path to the XML file with forms relative to the classpath root (folder tomcat/shared/classes).
Rules
In addition to the forms in the form files, the rules can be specified.
...
For the fields, we can specify the nodetype and datatype. The key datatype is a type of a property specified in the model in the characteristic type, for example, d:text. For associations, datatype is d:noderef. In such a manner, one can specify the default templates for various types of fields, for example:
...
| Code Block |
|---|
<fields datatype="d:text"> <regions name="input" template="text" /> </fields> |
...
The order of the element attributes does not affect the meaning in the XML, so the following rules are equivalent and indicate the same thing: for all view with the mode view, there should be the kind custom and the template table:
...
| Code Block |
|---|
<views mode="view" kind="custom" template="table" /> <views kind="custom" mode="view" template="table" /> <views template="table" mode="view" kind="custom" /> |
...
| Code Block |
|---|
<view class="…"> <fields any="true" template="half-width" /> ... </view> |
Form filling procedure
Form definitions and rules described above are used to obtain the structure of the form by its identifier. Let us assume that it is necessary to draw the view form for the “Income” type. Originally, only the type of a document (letters:income) and the mode (view) are known for the form:
...
The form filling procedure continues until the form is fully completed.
Using the forms
The form procedure allows defining different forms for the same type, depending on the mode (mode) or just a few different forms with different ID (id). For example, if it is required that the form has an extra set of fields in view mode (fields for viewing only), one can write it as follows:
| Code Block |
|---|
<view class="letters:income"> <!—form definition for all regions --> </view> <view class="letters:income" mode="view"> <!-- additional fields to the view mode --> </view> |
...
| Code Block |
|---|
<view class="custom:income"> <field prop="custom:newFieldBefore" /> <view class="letters:income"> <field prop="letters:fieldToRemove" template="none" /> </view> <field prop="custom:newFieldAfter" /> </view> |
Invariants support
Invariants can be set for the fields of the form:
| Code Block |
|---|
<field name="…"> <!-- required field on the form --> <invariant on="mandatory" language="explicit">true</invariant> </field> |
...
Any other invariants can be specified for any supported characteristics (mandatory, default, protected, valid, ...) and they would work for the form. For more information on modeling, using the invariants, see the document “Simulation in Citeck EcoS”ECOS”.
Since invariants can be set not only for the form, but also for the types/aspects and properties/associations, one shall answer the following question when creating the invariant: Is this invariant valid only for this form or for the whole type in general? The answer to this question specifies which scope shall be set to the invariant.
Pages with forms
Two standard pages with forms are available in EcoSECOS: to create new objects and to edit existing ones.
...