formStructure.xml file

The structure file fcContactFormStructure.xml describes the form fields, their types and properties. The form is based upon the data from this file and therefore will not work correctly in case this file contains errors. It is not recommended to edit this file without understanding of what you are doing.

The structure of this file should coincide with the existing fields that have already been created in Flash and indexed. Adding a new item in this file will not create a new field in the form. To do this you need to add a new field in Flash as well, that is to insert it in the .fla file with the Flash Authoring Environment and generate a new .swf file from it. To get more details on how to do this please refer to this section.

This file is created in the XML structural language and should conform to all standards of this language (http://www.w3.org/XML/).  That is why we strongly recommend you to use XML editors (e.g. Altova XMLSpy and others) to work with this file. Any errors made in this file can cause to a malfunctioning contact form.

All the form items are contained in the formItems node and presented as nodes with the name item. In general the file structure should look like this:

Each of these items has both required and optional attributes. The required attributes are id and label. The optional attributes are required and type:
E.g.:


id (required attribute) is a unique item number of the form. It’s not required for the item numbers to be put in order. It’s quite possible for the item with id=2 to go first. But it is significant for them to be unique and the number of items should correspond to the highest id. That is if you have four items the ids should be from 1 to 4.

label (required attribute) is a name of the form item which is used for the validation error messages or is bound with a given field and its value on sending a message.

required (optional attribute) takes one of the two values ‘ true’ or ‘false’ and defines if the input field is required or not on submitting the form. By default required is set to false.

type (optional attribute) is a field type and can take the following values
   
    •    ‘text’ — a text field;
    •    ‘select’ — a dropdown list;
    •    ‘checkbox’ — a checkbox (multiple items selection is possible);
    •    ‘radiobutton’ — a radiobutton (allowed selection of one item only and no more);

The field type should correspond to the form item that is created in Flash. That is if you have a combobox (select) in Flash the type must be select and nothing else. By default type has got the text value.

Besides the attributes the form items can have nested nodes which are optional and provide additional functionality for your contact form on the display, validation and submission stage. We will call them properties of the items. The properties can be assigned to different types of the form items (text, select, checkbox, radiobutton). The properties are defined as additional nodes nested in a form item. For example the textToShow property indicates what text should be showing in a text field once the form is initialized. By default textToShow has got an empty string as its value. The following example will result in a new field with text “Message:”


For the items of the ‘text’ type:
    •    textToShow – the text that will be showing up on the form initialization (for the forms that do not have labels with a field name)
    •    validator — a validator type:
            o    StringValidator
            o    EmailValidator
            o    NumberValidator
            o    DateValidator

When using a validator, additional properties pertaining to a specific validator can be used.

StringValidator:
        minChars — the minimum number of characters that is allowed for this field
        regExp — regular expression the field value should match. It is used together with regExpFlags.
        regExpFlags — regular expression options. It is used only if reqExp is present. Possible options are as follows:
                        g — global, defines whether the search should match all occurrences of the given pattern. If it is omitted just the first occurrence should be matched.
                        i — caseInsensitive. If it is present the case is disregarded.
                        m — multiline
 
NumberValidator:
        minValue — the minimum value
        maxValue — the maximum value
        allowNegative — defines whether you are allowed to enter a negative number

EmailValidator:
        minLettersAfterLastPoint — the minimum number of characters before the last dot
        maxLettersAfterLastPoint — the maximum number of characters before the last dot
        minLettersBeforeAt – the minimum number of characters before “@”
        maxLettersBeforeAt –the  maximum number of characters before “@”

DateValidator:
        mask – a mask which the date should be validated with. By default it is mm/dd/yyyy. The dividers do not matter. If mm, dd or yyyy could not be found the default mask is used.
        minDateAllowed – the minimum character that can be input, should correspond to the mask
        maxDateAllowed – the maximum character that can be input, should correspond to the mask

For the items of the ‘text’ type:
    E.g.:


•    restrict — characters allowed to enter
•    maxChars — the maximum characters limit
•    password — defines if the field is a password filed (the entered characters are substituted with asterisks)

For the items of the ‘select’ type:

•    firstItem — the first item which is used frequently, for instance “Choose your country” in a list with countries
•    dataProvider — data provider. It can be specified either directly as follows:


    or with a link to an .xml file with your structure. There’s an only requirement to the structure: all its items must be wrapped in <item></item>
        E.g.:



The fields of this type can be related with the help of the attributes of the dataProvider property: dependence and depth.

    •    dependence — the ID of a select item in the fcContactFormStructure.xml file which this field depends on
    •    depth — the depth where the data will be collected from in the specified .xml file

The easiest example here is the following relation: Car Brand :: Model :: Available Colors. There are different brands. Each brand has its own models. Each model has its own colors.
For the items of the ‘checkbox’ and ‘radiobutton’ type:

    •    selected — defines if the item is selected initially

The group property is common for all the items. This property has its own attributes: minRequired, maxRequired, delimiter. It determines the group which the field pertains to. In the e-mail body this field will not stay apart but display as the group member. For example groups may be necessary when using checkboxes and radiobuttons. It’s like having one field (e.g. Interests) with a few options. The group attributes are as follows:

    •    minRequired – the required minimum number of fields to be selected
    •    maxRequired – the  required maximum number of fields to be selected
    •    delimiter — a string used for the formatting of the e-mail body on sending it and is inserted between the values. For instance in case of checkboxes a comma ( ‘, ‘) is used frequently. As a result we get: Interests: interest 1, interest 2, interest 3 and so on.
    •    shouldBeEqual – true or false, false is by default. If it is true the values of all the group fields are compared and if they are not equal an error is fired.