Mapping GUI Components to Mapping Rules

Before your application can communicate with a data service, you must define mappings between application objects and data elements. These mappings allow data exchange between application GUI objects and a data service. For example, a user might enter stock symbols in a text field of an application and click a button to request financial data. After receiving the request, the data service would send a response to the appropriate GUI objects, such as text fields or a Matrix, to display the financial data for the requested stocks.

Mapping GUI components to mapping rules involves two steps:

1. Create the mapping rules file. See Creating Mapping Rules Files.
2. Define mappings in the rules file to map GUI components to data elements.

There are two ways to define mappings in the XML Mapping Utility:

• Manual Mapping See Manually Mapping GUI Components and Input Mappings
  
• Automatic Mapping See Automatically Generating GUI Components and Input Mappings.

Manually Mapping GUI Components and Input Mappings

After creating the mapping rules file, you need to define mappings between GUI components and the rules in the mapping rules file.

This section uses the General Interface WSDL Mapping 2 sample located in workspace/JSXAPPS/samples/WSDL_Mapping_2. By default, this sample runs in Static Mode, rendering the results of a sample message on screen. To run against the Xignite web service in Live Mode, register for a license key at http://www.xignite.com/xhistorical.asmx?op=xRegister. Then set the project to Live Mode on the Deployment panel of the Project Settings dialog (Project > Project Settings > Deployment) and reload your browser.

To define mappings in the mappings rules file, complete these steps:

1. Expand the operation in the Rules Tree panel that you want to map to see the request and response rules. Then expand the Input (request) child rule. Double-click the rule with the blue down arrow to see the descendant rules. The blue down arrow indicates that there is more content to be mapped.
   For example, expand the GetHistoricalQuotes operation rule (not singular GetHistoricalQuote*)* in the rules tree. Expand the Input (request) child rule. Double-click the GetHistoricalQuotes rule with the blue down arrow to see its child rules.
   
   Click here to expand screenshot...
   
   
   
   
2. Arrange the Component Hierarchy palette and the Rules Tree panel so that components and elements are visible.
   
3. Drag objects from the Component Hierarchy palette and drop them onto a rule in the Rules Tree panel to bind GUI components to rules. Note that the mapped rule now displays a Mapping icon in the rules tree.
   For example, drag the symbol component from the Component Hierarchy palette to the Identifiers rule in the Rules Tree panel of the XML Mapping Utility.
   A mapping is created between the GUI component and the target rule. Note the following changes in the Settings panel on the right:
   
   • A mapping is added to the Mappings table on the right and default values are populated.
     
   • The type of mapping is displayed in the Type column of the Mappings table.
     
   • The value of the mapping is displayed in the Path/Value column of the Mappings table.
     
     
     Other types of mappings can be created by selecting a mapping type and typing a value in the Path/Value field. For example, a rule could be mapped to a value specified by a JavaScript method call or to a CDF document, record, or attribute. For information on mapping types, see Message Rules.
     A Script mapping can be used to specify JavaScript code that manipulates message structure or field data. For more information on this type of mapping, see Using Code with Data Services.
     Structured rules are typically mapped to CDF documents, records, and attributes. For more information on this type of mapping, see Mapping Response Data to CDF GUI Components.
     
4. Save the rules file as follows:
   
   1. Click the Save button at the top of the XML Mapping Utility.
      
   2. Navigate to the rules folder and type the filename with the .xml extension in the field at the bottom of the dialog. The rules folder is automatically created in your project folder. However, rules files can be stored in any location in the project directory.
      
   3. Click Save in the Save File dialog to save the file.

Now that you've defined the mappings between the GUI components and the data exposed by the service, you need to generate the JavaScript function to call the service. Then specify this event in the Execute event of a component, such as a button. To generate the JavaScript code, see Calling a Data Service.

Automatically Generating GUI Components and Input Mappings

In addition to manually mapping existing GUI components to rules in the rules tree, it's also possible to generate GUI components and map them automatically. The XML Mapping Utility creates either a Text Box or a Select component, depending on field characteristics.

Automatically mapping GUI components to mapping rules involves several steps:

1. Select a component in the Component Hierarchy palette that is of type jsx3.gui.Block for the container of the GUI components.
2. Create the mapping rules file.
3. Automatically generate GUI components and mappings.

This section uses the General Interface WSDL Mapping 2 sample located in workspace/JSXAPPS/samples/WSDL_Mapping_2. By default, this sample runs in Static Mode, rendering the results of a sample message on screen. To run against the Xignite web service in Live Mode, register for a license key at http://www.xignite.com/xhistorical.asmx?op=xRegister. Then set the project to Live Mode on the Deployment panel of the Project Settings dialog (Project > Project Settings > Deployment) and reload your browser.

Automatically Defining Mapping in Rules Files

To automatically generate and map simple GUI components and input mappings, do the following:

1. Select a component in the Component Hierarchy palette that is of type jsx3.gui.Block. This will be the container for the GUI components that will be automatically generated by the XML Mapping Utility.
2. Create the mapping rules files as described in Creating Mapping Rules Files.
3. Expand the operation rule in the Rules Tree panel that you want to map. Then expand the Input (request) child rule. Double-click the rule with the blue down arrow to see its child rules. The blue down arrow indicates that there is more content to be mapped.
   

   If you don't want to map all the child rules to GUI components, use Ctrl+click or Shift+click to select the rules you want to map.

   For example, expand the GetHistoricalQuotes operation rule (not singular GetHistoricalQuote*)* in the Rules Tree panel. Expand the Input (request) child rule. Double-click the GetHistoricalQuotes rule with the blue down arrow to see the rules.
   
   
   

4. Select Map > DOM (map and create) from the Rules Tree panel menu.
   
   
   The XML Mapping Utility generates the components and a Mapping icon in the rules tree indicates that a rule is mapped.
   
   
   
   
5. Save the mapping rules file with the .xml extension.

You can also automatically map and generate simple GUI components for the Output (response) rule.

Now that the mappings between the GUI components and the data exposed by the service are defined, you need to generate the JavaScript function to call the service. Then specify this function in the Execute event of a component, such as a button. To generate the JavaScript code, see Calling a Data Service.