What are Dynamic XML Forms? (DXF)

DXF is a method for quickly creating user interface pages for editing metadata. It's called "dynamic" because the HTML editing form is generated dynamically in JavaScript based on XML specification (a template) which identifies how the editing page is generated.

Each DXF Template specifies:

• Every GUI element to be displayed on the page, including:
  • The type of GUI element (string, boolean, textarea, multiple, etc.)
  • The user-friendly label for the element (the @display) attribute)
  • The order of elements
    • The order in the template is the same as the order they are displayed on the user interface page.
  • Help text for the element for pop-up help for the user (the <dxf:help> tag)
  • How elements are grouped together into sets
    • For example, a number of nested elements which all pertain to the same object.
  • Other GUI Element attributes, like the number of columns / size of a textarea, etc.
  • Some elements can be simply for display, like headers and embedded text.
• The XML tags which are to be generated to represent the data entered by the user.

Who Needs to Use DXF?

You will need to use DXF if you are:

1.   Creating an App Bundle which requires property settings.
   • For example, suppose you create an App Bundle which needs to talk to a database. You may want to let the user specify the JDBC URL of the database. You would specify this as a property setting specified with ${property} in your configuration file.
   • Now suppose you want to use the Aspire Admin interface to load the app bundle? You will need to specify a DXF template so that the Admin UI can present an HTML form for editing the properties of your App Bundle.
2.   Creating a connector for the Aspire connector framework which requires properties for content sources that it processes.
   • Connectors in Aspire receive their data from content sources which are configured by the Aspire Admin GUI (version 0.5 Aspire). These connectors will use DXF templates so that the user can specify properties for the content source which is to be processed, such as the source URL, whether or not to scan sub directories, file patterns to allow, file patterns to exclude, etc.
3.   (Future Release) Creating a new component with configuration properties which need to be edited in the Aspire configuration user interface.
   • At some point, components will be configurable through the Admin GUI. When this happens, every component will require a dxf.xml template so that the Admin GUI can present a nice user interface for editing the component's configuration to the user.

DFX End to End Example

Why do you need DXF?

Determine exactly why you need to use DXF. This will determine what file you will need to create or edit.

1. I am Creating an Application Bundle - If you want to specify properties to be edited by the administrator when your application is installed, you will need to edit the DXF Template stored in config/application-dxf.xml.
2. I am Creating a Connector - If you are creating a connector which will be working with the Aspire Corporate Wide Search connector framework, you will likely need to create a DXF template stored in web/components/{component-path}/dxf.xml.
   • This file will be used to specify the properties that are required for every content source which is submitted to your connector.
   • If you bundle your connector as an AppBundle (which is typical, so it can be shared through Maven Repositories), then you'll also need to create the same config/application-dxf.xml file described above.
3. I am Creating a New Component - [Anticipated for Future Release]. At some point, every component will also have a dxf.xml file for editing the configuration properties for that component. This DXF template will be stored in your component JAR file, under resources/{implementation-class}/dxf.xml.
4. I want to use DXF for something else - This is certainly possible, but not well documented at this stage. The entry point will be the DXFMain class (found in aspire-framework), which takes the dxf.xml template plus an XML of your initialization data and produces two JSON objects: one for the template and one for the initialization data. This can then be used by a JavaScript program, dxf.js, found inside aspire-application to display the form to the end user and gather up the resulting XML form data.

The Template

In the template, tags strictly for DXF purposes are prefixed with "dxf:". All other tags are copied to output when the form is submitted.

In the example below, all tags which start with <dxf:...> are special tags which control how the user interface is displayed. The tags <properties> and <managerExternalRDB> and similar are application-specific tags which are used to structure the metadata when the resulting XML data is produced.

Example DXF Template:

 <dxf:template version="1.0" xmlns:dxf="http://www.searchtechnologies.com/DXF/2011">
   <properties>	
     <managerExternalRDB display="Use external RDB?" type="boolean">
       <dxf:help>Check this box if the CS Manager should be using an external relational database to hold data for the CS administration user interface. Otherwise, it will use an embedded Apache Derby database inside the CS Manager itself.</dxf:help>
     </managerExternalRDB>
     <managerRDB display="Internal RDB Component Name" type="String">
       <dxf:help>The name of the Aspire component to use for the internal database. Should always be CSRDB when using the internal RDB, or CSExternalRDBConnector when using the external RDB.</dxf:help>
     </managerRDB>
     <managerExternalJDBCUrl display="JDBC URL" type="string">
       <dxf:help>If using an external RDB to hold admin UI information, this is the JDBC URL which identifies the server and database of the server to use. Something like "jdbc:oracle:thin:neptune.acme.com:1521:T10A" for Oracle, "jdbc:mysql://localhost/test" for My SQL, or "jdbc:sqlserver://localhost\SQLEXPRESS:1433" for SQL Server.</dxf:help>
     </managerExternalJDBCUrl>
     <managerExternalJDBCDriverJar display="JDBC driver" type="string">
       <dxf:help>The jar file inside the Aspire distribution which contains the JDBC driver for your external database. This will typically be a file in the lib directory, such as "lib/ojdbc6.jar" (Oracle), "lib/mysql-connector-java.jar" (My SQL), or "lib/sqljdbc4.jar" (SQL Server).</dxf:help>
     </managerExternalJDBCDriverJar>
     <managerExternalJDBCUser display="JDBC user" type="string">
       <dxf:help>The user name that will be used to log into the external database, if one is configured.</dxf:help>
     </managerExternalJDBCUser>
     <managerExternalJDBCPassword display="JDBC password" type="string">
       <dxf:help>The password that will be used to log into the external database, if one is configured.</dxf:help>
     </managerExternalJDBCPassword>
     <debug display="Debug" type="boolean">
       <dxf:help>Turn on debugging. Debug messages will be written to the log files.</dxf:help>
     </debug>
   </properties>
 </dxf:template>

User Interface Form

When shown in a browser, the user interface for the dxf.xml template shown above will look like this:

Image Modified

Note that each ? icon is a mouse-over pop-up help page which will display the contents of the <dxf:help> tag for each input element (admittedly, the help expressed above is not wonderful, it is left as an exercise for the reader to come up with better help text).

XML Output

Once the user has filled out the information in the form and has clicked on "Submit" (or "Save"), DXF will produce the following XML as output:

   <properties>	
     <managerExternalRDB>true</managerExternalRDB>
     <managerRDB></managerRDB>
     <managerExternalJDBCUr>jdbc:sqlserver://localhost\SQLEXPRESS:1433</managerExternalJDBCUrl>
     <managerExternalJDBCDriverJar>lib/sqljdbc4.jar</managerExternalJDBCDriverJar>
     <managerExternalJDBCUser>test</managerExternalJDBCUser>
     <managerExternalJDBCPassword>test</managerExternalJDBCPassword>
     <debug>true</debug>
   </properties>

Then What Happens?

What happens next depends on the application. If installing a new application, the admin UI will take the XML and write it as properties along with the application to the admin RESTful interface. The properties are then stored in the settings.xml file as part of the application's auto-start properties.

If the DXF is used to configure a content source for a particular connector, the XML is written to a database BLOB. When the content source is then crawled, the XML will be provided to the connector so that it knows what to crawl and has all of the other information (user name, password, include patterns, exclude patterns, etc.) it needs to execute the crawl.

Finally, if the DXF is used to configure an individual Aspire component (anticipated for a future release), then the resulting XML will be sent to the component's component factory, will will shut down the old version of the component and then restart the component with the new configuration.

User Interface Control Reference

See User Interface Control

References

Development Tool

See DXF Development Tool