Definitions Folder

The Definitions folder, residing in the Administration cabinet, contains definitions that define Astoria webform fields and layout.

Document, Repeat Group, and Field definitions

The Definitions folder contains two folders:

System
User

The folders within the System folder contain all default definition documents that come with Astoria.

Each of these folders contain five subfolders:

Documents
Fields
Folders
HTML Templates
Repeat Groups

Important: Do not modify files in the System folder. You may lose your changes during the next system upgrade. Instead, create documents in the User folder. You can create new definitions or override existing System definitions by creating documents in this folder. If you create a definition document with the same name as the one in the System folder, your definition overrides the Astoria-supplied definition.

A document definition defines the set of fields that make up a form of that document type. When a user creates a form of this type, the system enforces the set of fields that make up the document. Administrators can define custom document definitions.

A field is a low-level component of a form document. A field definition is a document that defines the attributes of a field, one of the most important of which is the type. The type of the field indicates how it stores its value.

CAUTION:

Do not include a field definition multiple times in a repeat group or document definition. It results in data loss under some editing operations.

Examples of field types include:

Text
Choice (a list of possible values)
Check box (on or off)

Other attributes describe how the field is displayed to the user.

A repeat group is a collection of fields that may occur multiple times in a document. As with document and field definitions, a repeat group definition is a itself a form document. When you edit a form document that contains a repeat group, you can specify multiple sets of values for the fields in the repeat group. For example, you may have a set of fields that specifies an address (Name, Address, City, State, Zip). By putting these fields into a repeat group, and putting the repeat group into a document definition, the user is able to add multiple addresses to instances of that document.

For example, if you want to create a document type that describes the contact information of a person, you can store the following about the person: Name, Job Title, and Phone Numbers.

You need a field to hold the name of the person, so you create a Name field that is of type "small" (which is a one-line text field). Job Title is similar, with another "small" field called JobTitle. For the Phone numbers field, you may want to allow multiple values. So it is considered a repeat group. You may want two pieces of information for each number: the number itself, and what type of device it represents (office phone, mobile, fax, and so on), therefore, the repeat group consists of two fields. The PhoneType field should be of type "choice", and the list of choices could be "office, fax, mobile, home". The Number field is just a "text" field, perhaps with a field validation to verify that it is a well-formed phone number. The PhoneNumber repeat group contains these two fields.

If you want to use a field multiple times, create a similar field definition with a distinct name.

For example, instead of the following:

headerBlock

imageTag

CopyBlock

imageTag

Use fields such as:

headerBlock

imageTag1

CopyBlock

imageTag2

Document definition contains the following:

Form Type. Type of the form. Form types include:
- Document. Enables users to create, view, and edit information using forms. The information is stored in a persistent document in the repository.
- Persistent form. Uses forms to capture input from users, usually just before processing. A default form can be saved to the repository, users can modify the defaults when the form is submitted. It also allows the form designer to disable or hide certain fields from the user.
- Transient form. Similar to persistent form, but the data is only transient (for example, branch document).
Fields. A series or Repeat Groups and/or Fields.
Properties. The properties of this definition. See below for details.
Property Overrides. Property overrides for specific fields and/or repeat groups. See below for details.
javaScript. The value is javaScript to be inserted into the HTML when the document/form is viewed, edited, or created.
Repeat Group Definition. Consists of the following:
- Label. Short label that is displayed to the user when editing the repeat group.
- Tip. Hover text.
- Class. The CSS class that governs how this repeat group is displayed (optional).
- Fields. A list of field definition documents representing the fields that make up this repeat group.
- Properties. The properties of this definition. See below for details.
Field Definition. Consists of the following:
- Type. Type of the field. Possible types are:
  - caption. Unboxed small text that cannot be modified.
  - check box. A box that can be selected or not selected.
  - choice. One of a list of possible values.
  - date. A date and time field.
  - dynamic. The actual type is determined at runtime.
  - file. A field that allows selection of a repository document object.
  - fixed. Small text field that cannot be modified.
  - hyperlink. A button that when clicked loads a web page in a browser.
  - membership. Zero or more of a list of possible values.
  - small. One-line text field.
  - large. Multiple-line text field.
  - password. Small text field that hides the text that is typed.
  - check box. Boolean check box.
  - image. Reference to a image file in the repository.
  - imagemap. Reference to an imagemap file in the repository.
  - imageSimple. A static image rendered as a background.
  - textRef. Reference to a structured document in the repository.
  - fragRef. Reference to a structured document or element in the repository.
  - reference. Reference to any object in the repository.
- Label. Short label that is displayed to the user when editing the field. Specify a message key whose value contains the label text.
- Default. Default value of the field when creating a new document (optional).
- Tip. Hover text. Specify a message key whose value contains the label text.
- Class. CSS class that governs how this field is displayed during editing (optional).
- Properties. The properties of this definition. See below for details.

About Properties

Properties consist of name/value pairs. The valid property names are listed below. After each property there is a description of what the value field should contain:

afterFieldDefinitions. Specifies extra javaScript to be executed after the fields in the resulting form are defined. Valid only for documents.
alternateLoad. Defines a python alternateLoadScriptlet that returns the string value of the field.
Note: !py: prefix must NOT be included.
For information on scriplets, search for Function Help.
alternateSave. Defines a python alternateSaveScriptlet that persists the value of the field.
Note: !py: prefix must NOT be included.
For information on scriplets, search for Function Help.
canCollapse. Set to 'false' if the field should not be collapsible.
captionPlacement. Position of caption. Values are "north", "south", "east", "west".
choices. List of choices of the form "(choice1|choice2|choice3)".
choiceValues. List of values to store in the repository, corresponding to the list in the "choices" property. "choices" are displayed to the user, "choiceValues" are stored in the repository. If the choiceValues property is not defined, the selected "choices" values are stored. Property values can be computed dynamically as described in Specifying calculated field properties.
class. Cascading Style Sheet class to use for layout of this field.
collapse. Set to 'true' if field should be initially collapsed.
dummyImage. Image to display if the user has not specified a value. Valid only for image and imagemap types.
editable. Set to 'false' to disable editing of the field.
extraOnLoad. Specifies extra javaScript to be executed when the resulting form loads. Valid only for documents.
extraOnReset. Specifies extra javaScript to be executed when the resulting form is reset. Valid only for documents.
groupDisplay. If the field is part of a repeat group, this specifies how many characters to extract from this field to include as part of the displayed value of this instance of the repeat group values.
height. Height of field in lines. Used only for large, image, and imagemap types.
max. Maximum number of characters for small and password fields.
mailSender. Specifies the email address of an optional mail sender to be used for all job-ticket-related emails. The default email address is the one specified during ACS installation. The value of this property can be either a string or scriptlet. Valid only for Job_definition documents.
multiple. If field type is choice, set this to 'true' to enable multiple selection.
onSubmit. Provides the name of the javascript function to be called during form submit. The function has a standard signature: bool functionName(HTMLElement formName, String operation). A true return allows the operation to proceed. The function is called only after all individual field validation checks have succeeded. This property is useful for both multi-field validation (for example, checking to see if password fields one and two match), as well as for posting of message and/or for disabling buttons when a lengthy operation is submitted. Note that application specific javascript functions should be placed in <appName>.js, which is located in the Application cabinet.
ordered. 'true' or 'false' if a membership list is ordered.
PostCreateKey. A message key that defines the message to be displayed when a document of this definition is created. If not specified, a message such as "<ticket name> was created" is displayed.
PostEditKey. A message key that defines the message to be displayed when a document of this definition is revised through editing. If not specified, a message such as "<ticket name> was saved" is displayed.
PostPropsKey. A message key that defines the message to be displayed when the properties of a document of this definition has been modified. If not specified, a message such as "<ticket name> properties were modified" is displayed.
raw. Set to 'true' if the fixed field may contain HTML to display. For example, if the field value were: Click <a target="_blank" href="http://foo.com">here</a> to display stuff, the Web page displays a sentence with a hyperlink: Click here to display stuff.
referentName. The display name of the referenced document or file.
sendLabel. Controls the inclusion of the field label to the postOperation. A value of "true" causes the current locale display label property of the field to be sent as an http parameter to the operation invoked through form submission. The http parameter name is the id name of the field with a "_label" suffix. If the field definition does not specify a value for the sendLabel property, the sendLabel property value of the document definition is used. If the document definition does not specify a value for the sendLabel property, a value of false is assumed. An example of when this property might be used is when a change log of edits is desired to be computed at checkin time. Using both this property and the <a>sendOldValue</a> property, a doPostUpdate function could determine which fields values have changed and log messages such as "Assigned To changed from John Smith to Jane Doe" can be generated.
sendOldValue. Controls the inclusion of the original simple field value to the postOperation. A value of "true" causes the prior value of the field to be sent as an http parameter to the operation invoked through form submission. The http parameter name is the id name of the field with an "old_" prefix. If the field definition does not specify a value for the sendOldValue property, the sendOldValue property value of the document definition is used. If the document definition does not specify a value for the sendOldValue property, a value of false is assumed. For an example of when this property may be used, see the sendLabel property.
size. Size of choice or membership type. Defaults are 1 for choice and 8 for membership.
validateRegEx. The javascript regular expression that the field must match. See Setting up field validation for details.
Validate Message. The error message to display if the field value does not match the pattern.
validTypes. A comma-separated list of object types that are valid for this field.
validTypesErrMsg. A message is displayed if the tagged object is not in the list of validTypes.
veTrailer. Javascript fragment to display after field HTML is specified.
visible. Set to 'false' to hide field.
width. Width of field in characters. Used only for small, large, password, image, and imagemap types.

About Overrides

Overrides consists of triplets of information:

The name of a field or repeat group
The name of a property of that field or repeat group
The value of this property

Specifying an override causes the specified property of the field (or repeat group) to have the specified value. This allows a document definition override field and repeat group properties, and for a repeat group definition to override field properties. For example, the field definition "foo" may have a property name/value, but the document definition "bar", that includes that field definition, may wish to specify a different value for that property. (Without this technique, you have to create a new field definition, identical to the original field definition except for the property of interest, and reference the new field definition in your document definition.)