Types of data models for Guides

Guides based on XDP or PDF forms
- Scripting in form designs

You create a Guide based on an existing data model. The data model can be an data model (FML file) created in the Data Model perspective in Workbench, or it can be the Adobe® XML Form Object Model in an XDP or PDF form. The XDP and PDF forms can be created in Designer.

Data models (FML)

Data models (FML) are created in the Data Model perspective in Workbench. The model defines the data shape, constraints, and validation logic. In the Data Model perspective, you can add constraints and validation logic to the model, without the need to write script.

Forms created in Designer can also use the data model (FML) as a data connection. However, the resulting XDP form can be rendered only as a non-interactive PDF form, through Adobe LiveCycle ES4 - Output 11. The data from the underlying model cannot be shared in the browser with an interactive PDF form.

XDP and PDF forms

XDP and PDF forms can be created in Designer. A form can be bound to an XML schema definition, and can submit data that is validated against that schema.

Guides based on an XDP or PDF form can also exchange data inside the browser with an interactive PDF form, to provide a dual data entry mechanism.

Guides based on XDP or PDF forms

When a Guide is based on an XDP or PDF form, the model that you see in the Data Model view corresponds to the model in the form. If the form was created with an XML schema, then the submission conforms to that specific XML schema.

You can bind all the form objects to items in a Guide.

Note: Do not use a form that contains broken fragments. Resolve any broken fragments in Designer before using the form to create a Guide.

Guides support a subset of the scripting events, objects, properties, and methods in the XML Form Object Model that is used in form designs in Designer. For information about the scripting subset, see Scripting Support for HTML Forms and Guides.

Migrate form guides created in Designer ES (version 8.x)

In Designer ES (version 8.x), you could create one or more form guides for a form. If the form that a Guide is based on includes a form guide created in Designer ES (version 8.x), you can migrate the form guide to the Guide format in Workbench. The form and the original form guide are unchanged and you can continue to use them in Designer ES (version 8.x).

Note: You cannot preview a migrated Guide that includes the following characters in the Guide Title: \ / : * ? “ < > |

For more information about migrating Guides created in Designer ES (version 8.x), see Upgrade a form guide created with Designer ES (version 8.x).

Forms represented in the Data Model view

When a Guide is based on an XDP or PDF form, the form is represented in the Data Model view in the Guide Design perspective. An entity is generated for each subform, and a property is generated for each nested subform, draw, or field. The property name corresponds to the object name in the form.

Note: When a Guide is based on an XDP or PDF form, do not use the ID property that appears in the Data Model view.

The following table describes how forms are represented in the Data Model view:

Form object	In Data Model view	Description
Subform	Entity	An entity is generated for each subform. The root entity is identified with the attribute `persistent = "true"`.
Dynamic subform	Collection	If the `subform.occur.max` value is `"-1"` or if the `max` value is greater than the `min` value, the subform is represented as a collection.
Nested subform	Property	The property `name` corresponds to the subform name in the form. The property `type` corresponds to the name of the entity generated for the parent subform.
Numeric field	Property	Generated as a `float` property.
Date field	Property	Generated as a `date` property.
Text field	Property	Generated as a `string` property.
Check boxes or radio buttons	Property	Each check box or radio button is generated as a `Boolean` property. You can bind each check box or radio button to an item in the editor or the Guide Tree view. Check boxes do not behave like true boolean objects and do not evaluate to true or false. To use a check box in the evaluation of a rule, set the condition to test for the value of the check box as defined in the XDP form. Open the form in Designer and select the check box. In the Object palette, select the Binding tab. By default, the On/Off values are 1/0. In the Guide, set the condition to be triggered When {Checkbox} = 1.
Draw	Property	Generated as a `string` property.
Variable	Property	Generated as a `string` property.
Script object	None	Script objects are executed in the Guide at runtime.

Designing forms for Guides

In Designer, follow these guidelines to simplify the Guide creation process:

Group form sections into subforms.
Do not use nested subforms in repeating subforms. Guides assume that all repeating form objects are immediate children of the repeating subform.
Avoid using form fields on master pages.
Use field captions instead of static text. Using field captions in the form design saves a step when you create a Guide. The captions appear automatically when you add the field to your Guide. However, when you use static text, you have to manually link the text to an item in your Guide.

Unsupported form design features

Guides do not support the following form design features:

setting the locale for the form or form objects to use the viewer’s system locale
using global bindings for form objects
signature fields
email submit buttons

Scripting in form designs

Guides support a subset of the scripting events, objects, properties, and methods in the XML Form Object Model that is used in form designs in Designer. Any scripting that falls outside the subset does not compile.

For information about the scripting events, objects, properties, and methods that Guides support, see Scripting Support for HTML Forms and Guides.

General scripting guidelines

Follow these guidelines when developing script on a form design that will be executed in a Guide:

When a script is set to run on the client, Guides support only JavaScript. Server-side scripts can use either Javascript or FormCalc.
Guides do not support nested functions in JavaScript.
Maintain a library of common Guide functions in a script object that you can reuse.
For message boxes, use xfa.host.messageBox. Message boxes appear as default Flex Alert controls in a Guide. To match the Alert control style to the rest of your application, use a custom style (SWF). For information about using custom styles with a Guide, see Customizing Guides Using Flash Builder.
Guides are unable to wait for the user response from a message box. To add that behavior, build custom Flex components.
When adding script to your form, you can limit execution to Guides, or provide alternate execution paths depending on the host environment. To achieve this behavior, query the xfa.host.name property:
```
if (xfa.host.name == "Flash") 
{ 
    //script will execute in Guide 
} else { 
    //script will execute in Acrobat/Reader 
}
```
Do not use alternative display or edit patterns, such as date{DD-MM-YYYY}|date{DD/MM/YYYY}. However, you can use alternative validation patterns, such as this validation pattern for the US ZIP code text{99999-9999}|text{99999}.
When using a display or edit pattern for any field, include a validation pattern for the field. The display or edit pattern ensures that the field receives proper input, and the validation pattern ensures that the data is valid.
When a subform is included in a repeating panel layout, and the value of the occur.min property is “0”, a subform instance is created when the Guide is rendered.

Guidelines for events

When developing script on a form design that will be executed in a Guide, follow these guidelines for events:

The formReady event fires only once each when the PDF form and Guide load.
The calculate event fires when referenced field values change and when switching between the Guide and the PDF form.
Do not use xfa.event.change, because Guides do not support it.

Guidelines for working with values

When developing script on a form design that will be executed in a Guide, follow these guidelines for working with values:

Express a script that assigns a value as:
```
this.rawValue= price.rawValue * quantity.rawValue.
```
Do not express a script that assigns a value as:
```
price.rawValue * quantity.rawValue. 
```
Scripts expressed this way do not work in a Guide. The XML Form Object Model automatically assigns the result of the calculation to the value of the field.
When checking for empty field values look for null and zero-length values.