Working with schemas in the Schema tab (Flash Professional only)

The Schema tab allows you to view the schema for the selected component. The schema contains a list of the component's bindable properties, their data types, their internal structure, and various special attributes. This is the information that the data binding feature needs in order to handle your data correctly.

The Schema Tree pane, the top pane of the Schema tab, displays the bindable properties of the selected component and their internal structure, represented by one or more schema fields (component properties and schema fields are also referred to as schema items). The Schema Attributes pane, the bottom pane of the Schema tab, displays detailed information about the selected schema item.

Note: All components have properties, but by default, to reduce UI clutter, the Schema tab shows only those properties that commonly contain dynamic data. These properties are referred to as bindable properties. You can bind to any property by either adding it to the schema panel yourself or using ActionScript code. See Working with bindings in the Bindings tab (Flash Professional only).

A component's schema describes the structure and type of data but is independent of how the data is actually stored. For example, the results from a WebServiceConnector component or an XMLConnector component could have identical schemas, even though the web service results are stored as ActionScript data structures (objects, arrays, strings, Boolean values, and numbers), and the XMLConnector component results are stored as XML objects. When you use data binding to access fields within a component's schema, you use the same procedure regardless of how the data are stored.

A component identifies which of its properties are bindable. These bindable properties appear in the Schema panel as top-level schema items (component properties). A component property can have its own internal structure (schema) that defines additional properties (schema fields) that can be bound to other component properties within your application. A good example of this is when you introspect a WSDL for a WebServiceConnector component. The WSDL definition describes the parameters and the results for a web service. The WebServiceConnector component contains two bindable properties (params and results). When the WebServiceConnector component introspects, the WSDL the authoring tool automatically creates the schema for the params and results properties so that it mirrors the schema defined within the WSDL.

There are several ways to create the schema for a component:

For some components, you can import an XML sample file to define a property's schema.
For some components, the schema is predefined within the component.
For some components, the schema is derived as the result of introspecting an external schema definition such as the WSDL for a web service.
For some components, you define the schema using the Schema toolbar within the Schema panel.

Importing a sample XML file to use as a schema

When you import a sample XML file to use as a schema, Flash MX Professional 2004 examines the sample document and creates a schema that represents the nesting structure of the document's XML elements and attributes, as well as the data type (number, Boolean value, or string) of the text values. Any element that occurs more than once appears in the schema as an array.

To import a sample XML file to define the schema for a component property:

Select the component property.
Do one of the following:
- Click the Import Sample Schema button in the upper right corner of the Schema tab.
- Click the options menu control in the upper right corner of the Component Inspector panel and select Import XML Schema from the menu.
In the Open File dialog box, select an XML file that is a representative sample of the data.
The schema appears in the Schema tab. You can now create a binding between your XML element and the component property within your application.

Note: Some XML documents may have a structure that Flash MX Professional 2004cannot represent—for example, elements that contain text and child elements mixed together.

Adding a schema field to a schema item

Use the following procedure to add a schema field to a schema item.

To add a schema field to a schema item:

In the Schema tab, select the schema item to which you want to add a field.
Click the Add a Field Under the Selected Field (+) button.
A new field is added as a subfield of the selected property.
In the Schema Attributes pane, enter a value for Field Name. Fill in the other attributes as appropriate.
There are three possible scenarios based on the type of schema item:
- Schema item of type Object, which may have subfields, @attributes, or both
- Schema item of type Array, which always has exactly one subfield called [n], which can be of any type (including Object, String, and so on)
- Schema item of other types (such as Boolean, String, Number), which don't have subfields but may have @attributes

Adding a component property to a schema

You can make any of your component properties bindable if you add them to the schema. The following procedure explains how to create an application that uses a CheckBox component to indicate whether a TextInput component is editable. However, in this example, the editable property of the TextInput component is not bindable, so its schema must be modified.

To add a component property to a schema:

Add an instance of a TextInput component and a CheckBox component to your application and give them instance names.
Select the TextInput component and click the Schema tab on the Component Inspector panel.
Click the Add a Component Property (+) button at the upper left of the Schema tab to add a component property.
In the Schema Attributes pane (the bottom pane of the Schema tab), enter editable for the field name value and select Boolean for the data type value.
Click the Bindings tab and click the Add Binding (+) button to add a binding.
In the Add Binding dialog box, select the editable property, and click OK.
In the Binding Attributes pane at the bottom of the Bindings tab, click the Bound To item under Name, and click the magnifying glass icon across from the Bound To item under Value.
In the Bound To dialog box, under Component Path, select the CheckBox component, and then click OK.
Select the Checkbox component on the Stage, and click the Parameters tab in the Component Inspector panel.
Select Control > Test Movie. To test the functionality, type a value into the TextInput component and then deselect the CheckBox component. You should now be unable to enter text into the TextInput component.

Schema item settings

The schema of a component shows you what properties and fields are available for data binding. For each property or field, there are settings that control validation, formatting, type conversion, and other features that affect how data binding and the data management components handle the data of a field. The Schema Attributes pane, the bottom pane of the Schema tab, presents these settings, which you can view and edit. Settings fall into five groups, according to the features they control:

Basic settings Every field or property has these basic schema settings. In many cases, these are the only settings you need to bind to a field.

Name: Every field needs a name.
Data Type: Every field has a data type, which is selected from a list of available data types. The data type of a field affects data binding in two ways: When a new value is assigned to a field through data binding, the data type determines the rules that are used to check the data for validity. When you bind between fields that have different data types, the data binding feature attempts to convert the data appropriately.
Storage Type: Every field has a storage type. Typically, it is defaulted to one of four values based on the data type of a field. The available values for storage types are simple, attribute, array, or complex.
Note: Developers will almost never have to change this setting. However, there are some cases when the storage type for an attribute contained within the schema for an XML file may be defaulted to scalar when it should be set to attribute.
Path (optional): If you are creating a virtual schema, you can use this property to identify the location of the data for this schema field.

Validation settings Validation settings are applicable to any field that is the destination of a binding. You will usually modify these settings when you want to control the validation of data that is input by the end user. To set this up, you bind from the UI component to a data component, and then select appropriate validation settings for the fields of the data component. One common example is when the user input is bound to the params property of a connector component, such as the XMLConnector component or WebServiceConnector component. Another common example is when UI components are bound to data fields of the DataSet component.

Validation operates in the following way: After any binding is executed, the new data is checked according to the validation rules of the destination field's data type. A component event is then generated to signal the results of the checking. If the data is found to be valid, then the valid event is generated; otherwise, an invalid event is generated. Both components involved in the binding emit the event. You can ignore these events. If you want anything to happen as a result of these events (such as giving feedback to the end user), you must write some ActionScript code that receives the valid and/or invalid events.

Validation Options: Validation options are additional settings that affect the validation rules for this field. The settings are presented in the Validation Options dialog box, which appears when you select this item. These settings vary according to data type. For example, the String data type has settings for the allowed minimum and maximum length of the data.
Required: This is a Boolean value that determines whether this field is required to have a non-null value. Validation fails if required=true but no value has been set.
Read-Only: This is a Boolean value that determines whether this field is allowed to receive new values through data binding. If readonly=true, then executing any binding to this field generates the invalid event, and the field is changed.

Formatter settings Formatter settings are applied when a field's value needs to be converted to a string. Most often this will be for display purposes, such as when a DataSet field is databound to the text property of a Label or TextArea component. Formatter settings on a field are ignored when that field is databound to something whose data type isn't String.

Formatter: The name of the formatter to use when converting this field to String. This is selected from a list of available formatters.
Formatter Options: these are additional settings that affect the formatter. The settings are presented in the Formatting Options dialog box, which appears when you select this item. These settings vary according to formatter. For example, the Boolean formatter has settings for the text that represents the true and false values.

Note: If you don't specify a formatter, then a default conversion is applied when a field's value is needed as a string.

For a complete list of formatters, see Schema formatters (Flash Professional only).

Kind and Encoder settings The Kind and Encoder settings are used to activate certain special features. For information, see Using kinds and encoders.

Kind: The Kind setting for this field.. This is selected from a list of available Kind settings.
Kind Options: Additional settings that affect the Kind setting. The settings are presented in the Kind Options dialog box, which appears when you select this item. These settings vary according to kind.
Encoder: The Encoder setting for this field. This is selected from a list of available Encoder settings.
Encoder Options: Additional settings that affect the encoder. The settings are presented in the Encoder Options dialog box, which appears when you select this item. These settings vary according to encoder.

Default settings These settings let you set defaults for various situations. There are two uses for these settings:

If a field's value is undefined, then the default value is used instead whenever the value of the field is used as the source of a data binding. For example, the data fields of a DataSet component, or the results property of a connector component, are allowed to have an undefined value.
When you create a new row of data in a DataSet component, the default value is used as the value of newly created records

When to edit schema item settings

When you build an application using data components and/or data binding, you need to apply schema item settings to some, but not necessarily all, fields of the components in your application. The following table summarizes the most common uses of schema item settings and will help you determine when these settings need to be edited.

Component	Property/field	Settings	When to use
Any connector	`params` (and its subfields)	Validation Options, Read-Only, Required	If validation is desired
	`results` (and its subfields)	Formatter, Formatter Options	For fields that need formatting for display as text
		Default value	For fields whose value is sometimes undefined
DataSet	Any data field	Name, Data Type	You must set these for every data set field that you define
		Validation Options, Read-Only, Required	If validation is desired
		Formatter, Formatter Options	For fields that need formatting for display as text
		Default Value	For fields whose value is sometimes undefined, or to specify the initial value for newly created data set records
UI components	UI components typically don't need any changes to their schema settings
Any component	Any property or field	Kind, Kind Options, Encoding, Encoding Options	Various purposes, as described in Using kinds and encoders
Any connector	`results` (and its subfields)	Path	To identify the location of the data for a virtual schema field

Using kinds and encoders

Kinds and encoders are drop-in modules that perform additional special processing of the data of a schema item. They are often used in conjunction with each other to accomplish common tasks. Below is a list of common uses for kinds and encoders.

Calculated DataSet Fields Calculated fields are virtual fields that do not exist in the underlying data tables. Calculated fields provide developers with the ability to create and update dynamic field values at runtime. This is especially convenient for calculating and displaying values based on calculations or concatenations performed other fields located in a record (for instance, you can create a calculated field that combines the first and last name fields together to display the full name to a user).

To set up calculated fields for the DataSet component:

Select the DataSet component and click the Schema tab of the Component Inspector.
Create a persistent field for the DataSet component using the Add a Component Property (+) button.
Using the Schema Attributes pane, give the new component property a field name and set its kind to calculated.
Use the calcFields event of the DataSet component to assign this field a value at runtime.
Note: You should assign a value to a calculated field only within the DataSet component's calcFields event.

Setting up schemas for XML documents In an XML document, all data is stored as a string. Sometimes you want the fields of an XML document to be available as data types other than String. The following example shows an application that pulls in data from an XML file.

<datapacket>
   <row id="1" billable="yes" rate="50" hours="3" />  
   <row id="2" billable="no" rate="50" hours="6" />
</datapacket>

If you use this XML file to import a schema for the XMLConnector component's results property, it generates the following:

results : XML
   datapacket : Object
      row : Array
         [n] : object
            @billable: Boolean
            @hours : Integer
            @id : Integer
            @rate : Integer

But suppose you want to treat the row node as a record within a grid, and you want the @billable attribute to be treated as a Boolean value and display a true or false value in the grid instead of a yes or no. Getting the data into the grid is simple. You can simply bind the row schema field to the dataProvider property of the grid. The following procedure explains how to get the @billable attribute to be treated as a Boolean value and display a true or false value.

To make the @billable attribute display a true or false value:

Select the XMLConnector component and click the Schema tab.
Select the @billable schema field and select the encoder property in the Schema Attributes pane.
Make sure Encoder is set to Boolean. Select Encoder Options. You now have a choice to define which strings represent a true value and which strings represent a false value.
Enter yes for strings that you want to set to true and enter no for strings that you want to set to false.
The encoder now takes the XML data in its raw form (String) and converts it into its normal form (ActionScript type of Boolean). Using the encoder options, it knows how to encode the string values correctly.
Click Formatter and select Boolean. Select Formatter Options. You now have a choice to define how a true and false value should be displayed as a string.
Enter True for strings that mean true and enter False for strings that mean false.
The formatter now takes the normal form (ActionScript type Boolean) and formats it into the String value true or false for display purposes.

Setting the schema path

The path property for a schema field is an optional setting that is used in special circumstances when the schema for your component is not appropriate. Using this setting, you can create a virtual schema field (a field that exists in one location but pulls its value from another). The value of this property is a path expression that is entered in one of the following formats:

For schemas that contain ActionScript data, the path follows the format field [.field]..., where field is equal to the name of a field (such as addresslist.street).
For schemas that contain XML data, the path follows the format XPath, where XPath is a standard XPath statement (such as addressList/street).

When data binding is performed, Flash checks to see if there is a path expression for a schema field. If there is, it uses the path expression to locate the correct value. See Virtual XML schemas.

Note: The path expression is always performed relative to the parent node of the schema field.

About editing the contents of the Schema Attributes pane

You can edit anything within the Schema Attributes pane—even schemas that came from an external source, such a web service WSDL file. You can always change any value for any field of any schema, with the following restrictions:

If you change the type, then all the other schema item attributes are reset to the default values for the new data type.
If you choose to completely reload the schema for a component property, you will lose all the edits that had previously been made within the Schema Attributes pane.
Note: There are several ways to reload the schema for a component property, including entering a new WSDL URL, choosing a different operation for a web service, or importing a new XML schema from a sample XML file.