Advanced Lesson 2: Binding XFT Forms to XML content
Before you Begin
Before creating a form to bind to your underlying schema or DTD, you must first have a good knowledge of the structure of your schema or DTD. In particular, you must know:
  1. The elements and attributes to which you are going to bind your form.
  2. The hierarchical placement of these elements and attributes in the schema or DTD.
Knowing this, you can proceed with the creation of the form.
In this tutorial, you will create a form bound to the Author element in the Journalist DTD. The Author element becomes the "anchor" element for the form.
This lesson will take about 25 minutes to complete.
Create a Form
Using the skills you learned in the last tutorial, create an XFT form:
  1. Start the XMetaL Form Layout Editor.
  2. Create a new form, specifying the scripting language of your choice.
  3. Create a form that looks like the sample below by dragging and dropping four text box objects from the Object Bar and giving them the names shown:
  4. Save the form.
Bind the Form to XML Elements or Attributes
Now that you have built a simple form, you will want to bind it to an element or attribute defined in your customization DTD or Schema.
In order to do this you must tell XMetaL which element and attribute to bind to your controls to by entering an expression for the XPath property of each bound control. For the form created above, you will enter these XPath values for the objects in the form you are creating:
Object XPath expression
First name ./FirstName
Surname ./Surname
City ./Address/City
Author Id attribute ./@Id
For more information on the XFT's use of the XPath expression, see XPath functionalities in the XFT reference section of the XMetaL Customization Guide. For more information on XPath in general, see http://www.w3.org/TR/xpath.
To bind the XFT Form controls to XML data:
  1. Display the property sheet for the form you just created. In the example below, the property sheet for a text box is shown:
  2. Click the First Name text box object in your form. The property sheet displays the properties for this object.
  3. Look for the property called XPath (circled in the example above).
    Type ./FirstName in the text box beside the XPath property. FirstName is a child element of the anchor element Author.
  4. Click the Surname text box object in your form.
  5. Type ./Surname in the text box beside the XPath property. Surname is a child element of the anchor element Author.
  6. Click the City text box object in your form.
  7. Type ./Address/City in the text box beside the XPath property.
    Address is a child element of the anchor element Author, and City is a child element of the Address element.
  8. Click the Author ID text box object in your form.
  9. Type ./@ID in the text box beside the XPath property.
    ID is an attribute (as indicated by the "@" sign) of the anchor element Author.
  10. Now we are going to save the form so that we can eventually look at it in XMetaL. First, find the file Author.xft in the \{install path}\Blast Radius\XMetaL 4.5\Author\Forms folder. Change its name to Author_backup.xft (or some other name different from the original filename).
  11. Save the form you have just created as Author.xft in the same folder as in the above step.
You have now bound data from your underlying schema or DTD to objects on your form.
Documents Without Mapped Content
If the form contains any element nodes that do not exist in the base XML document, the XFT system displays the form with the element and allows the content to be entered; however, your document is not populated with the data.
For example, if the XML document that contains the form you created in the above example does not contain a City element tag, the City field is shown on the form, and users can enter data into the field. But the City tag is not automatically created in, or saved with, the document, and the content of your form is not updated.
For more information about creating elements in documents, see the XMetaL Programmer's Guide section on XMetaL APIs.
Interlude: The Data Source Object
Before we move on to looking at ways to test and, finally, run the form from XMetaL, let's stop a moment and take a look at the Data Source Object on the Object Bar.
The Data Source Object is an important and very useful object. This object must be added to any form that uses external data sources. When dragged onto the form, it is visible during design time, but invisible at run time. For this tutorial, we will not be using this object, but you should be aware of it, since it will definitely come in handy in the future for more complicated and more functional forms.
When you add a data source object to a form, external data can be connected to these four types of objects:
  1. Text boxes
  2. Edit boxes
  3. List boxes
  4. Combo boxes
In order to have a way to move to from row to row in the data source, XFT must have at least one drop down or list box added to the form.
To connect to an external data source:
  1. Drag the Data Source Object onto your form.
  2. If the property sheet is not visible, right-click the data source object, and then click Object Properties on the menu that appears.
  3. In the data source property sheet, click in the text area to the right of the Source property to start the Data Source Selection Wizard.
  4. In the Select DSN list, locate and click the data source.
  5. Enter the User ID and Password for the data source if necessary. You may not be able to proceed until you have entered a valid name and password.
  6. Click Next. The data for the field you selected is displayed on this page of the wizard.
  7. Click Finish. Or, if you want to select a different data source, click Back and repeat the previous two steps.
    When you click Finish, the XFT Datasource Selection Wizard closes.
  8. In the XMetaL Form Layout Editor, click the control for which you want to select a data source field.
    If this is a valid data-aware control, the property sheet for this control includes the properties DataField and DataSource.
  9. From the list to the right of the DataSource property, select the data source you added to this form.
  10. From the list to the right of the DataField property, select the data source field to which to connect your control.
You have now connected a control to an external data source.
Test a form in the XFT Form Layout Editor
You can test the forms you have created directly from the Forms Layout Editor:
  1. Click View > Execute Form. Your form appears the way it will when it is called from XMetaL.
  2. Test the controls to make sure they work the way you intended.
  3. Click the close button in the upper right-hand corner to close the test form.
At this point, you have created a form and mapped its controls to XML content. The next step is to customize XMetaL to call the form in the appropriate manner, and the appropriate time.
Continue with the next lesson: Opening XFT Forms in XMetaL...
Last modified: Friday, May 21, 2004 3:22:32 PM