TelFormFactory User Guide

Note: See www.terry-comms.com for latest documents

Screenshot of TelFormFactory from Terry Comms Ltd.

TelFormFactory produces an XML Schema from which TelForms are automatically generated. TelForms are Java data input forms for a number of platforms. XML Schema is an international standard for describing the content of information. Data is in XML format - another international standard. Systems managers need to ensure accurate data is entered into the system, but this is not always done well. The XML Schema ensures coordination between the Client and the System, and can also be passed on to third parties to be integrated into wider Systems strategies, for example in database support. Data is checked by the TelForm and confirmed at the Central Office. TelFormFactory ensures attractive, easy to use Web Forms are produced, with ease and a minimum of ambiguity for all.

• Creates valid XML Schema data models quickly and easily using Drag and Drop GUI.
• Automatically generate powerful Java Forms for Desktop, Browser and Mobiles in less than a minute.
• No Java knowledge needed.
• Re-usable data models and Open Source Java code.
• More Client Forms for more platforms to come.
• Standards based flexibility throughout for compatibility with most server systems.
• Other features and tools to support Java - XML systems.

Currently TelForms are available in these formats:-

• Java1_1 Applet for PC - this needs a Java enabled web browser. All such web browsers can download and run this TelForm.
• Java1_1 Application for PC. This can be run by any Java enabled desktop system.
• CLDC MIDP_1 Midlet for Mobiles and PDAs. This can be downloaded and run by any Java enabled handheld device. TelForm and Data are transferred over GSM or GPRS networks. Carrier access conditions vary.

The suffix 1_1 refers to the version of Java, namely Java 2 Standard Edition 1.1 generated for Applet and Application. These are fairly old releases to give wider client-base. Similarly 1 refers to Java 2 Micro Edition Connected Limited Device Configuration 1.0 (CLDC) and Mobile Information Device Profile version 1.0. (MIDP 1.0) targeted at devices with limited resources such as pagers and mobile phones. This is to provide greater device coverage even though it may mean less functionality or performance. In particular CLDC 1.0 does not allow for Floating Point processing, ie decimal calculations.

NB: It should be noted that in designing the TelForm model - no account of Colours, Founts, Sounds, Logos and the like, are made of the TelForm on the device. Future releases to TelFormFactory will shortly allow for these to be specified by the TelForm designer and/or by the TelForm user.

Note: TelFormFactory requires version 1.6 of the Java Development Kit ie JDK not JRE. TelFormFactory has only been tested with the Sun JDK. The downloaded file TelFormFactoryversion-id.zip can be unzipped into any convenient directory. Change to the programme directory and enter run at the command line:-

The command file should:-

1. Identify if the JDK is properly installed, and throw error message if not.
2. Check library jar files.
3. Set classpath and memory limit 256M (increase as available) and call TelFormFactory main class.

• Menubar with keyboard accelerators.
• Toolbar - providing alternatives to Menubar operations.
• 'TelFormFactory Types' Panel (left) - tabbed 'pages' of datatypes from which the XML Schema is built.
• 'Messages' Panel (top right) - provides help, error and status information.
• 'Model' Panel (bottom right) - in which the TelForm types are arranged to make up the structure and component datatypes which form the XML Schema and TelForm.

The TelFormFactory interface consists of 3 panels. The left panel is the Type Template Panel, top right is where messages to the TelFormFactory user are displayed, and below that is where TelForm model is arranged. The Type Template Panel has pages of datatypes or TelForm field types which are added to the TelForm model by dragging and dropping the type icons.

See Operations descriptions below.

• NEW TelForm
• XML Schema
• TelForms OUT
  • Applet 1_1
  • Application 1_1
  • Midp_1

Note: Menu selection instructions are followed by keyboard shortcuts eg [altF] indicates press Alt key and F key simultaneously to Open the File Menu options. The shortcut key is underlined on the Menu Option.

1. Press New TelForm icon or From Menu: File [altF] New TelFormFactory File [altN] to begin a new TelForm.
2. Acknowledge the TelForm name message and enter the name of the TelForm. This will form the root of the XML instance document which will be produced by the TelForm. This should start with a capital letter. Spaces and other punctuation are not allowed here. Press OK.
3. The 'Help' dialogue entry frame is then opened to enter comments to assist TelForm users and support staff. The information here will apply to the TelForm as a whole. There is no limit to text length.
4. The TelForm Model area will show an icon representing the root node, with the name of the TelForm and the type of node (tok:TelFormRootType). Icon shapes and colours may be configured in Preferences (Work in Progress).

Press OK to apply your values. Save the file (cf).

Note: Each TelForm field also has a 'Help' commentary associated with it. Effort spent in providing guidance to TelForm users can save a lot of expense in support.

The XML tree structure is built up by the Drag & Drop of datatype icons from any of the TeleFormFactory 'datatype' pages to an appropriate icon already in the model. Note the following restrictions on which type may be added to existing model types :-

Datatype rules

• Any type may be added to the root except for the tok:MultipleChoiceItemType and the tok:ExclusiveChoiceItemType.
• A tok:MultipleChoiceItemType may only be added to the tok:MultipleChoiceType and the tok:ExclusiveChoiceItemType only affixed to tok:ExclusiveChoiceType.
• Other types may only be added to the root or to a tok:GROUP_HEADER.

Drag and drop more Data types onto the root to build up the fields of the TelForm. See the 'HELP - Data-types' screen for description of each Datatype. Place the mouse over each Data-type icon for a brief Tooltip text comment describing the Datatype.

Note: Observe the TelFormFactory Messages panel for feedback and error messages. Use Scrollbars when provided (this happens dynamically) to move up and down the Messages and Model panels. Sub-trees within the TelForm Model may be folded by clicking the switches to simplify tree view.

Note: There are no Toolbar icons for these actions at this time.

From Menu: File [altF] Save TelFormFactory File [altT] brings up a file system browser dialogue to Save TelFormFactory File. The filename ends with .xml.This is not the XML Schema, nor does it represent the data produced by the TelForm - it is a means of storing the TelForm model and meta-information so that it can be retrieved, modified and maintained with TelFormFactory. The file browser initially opens in the user home directory, subsequently this location is saved in User Preferences. The format and content design of the TelFormFactory file is a Work in Progress and XML Schema will of course be produced for this.

From Menu: File [altF] Open TelFormFactory File [altO] brings up a file system browser dialogue to Open TelFormFactory xml file. Again, by default this opens in the user home directory. New Fields can be added to the TelForm. Also in Edit Mode (see section) fields may be deleted or re-positioned within the TelForm. The TelFormFactory file should be saved after alteration.

Once a TelForm has been built or loaded - Press XML Schema icon or From Menu: File [altF] Save XML Schema File [altS] to bring up a file system browser dialogue to Save XML Schema File. The XML schema filename ends with .xsd. This will generate the XML Schema in the file specified. The resulting Schema will be verified by the validating software selected in User Preferences. It may be wise to save the TelFormFactory file before generating the XML Schema.

Select the Radio Button on the Toolbar according to the TelForm package required - namely Applet1_1, Application1_1, Midp_1. The icon shows a latched appearance and can be deselected by pressing again. All 3 packages can be selected at once with little difference in processing time, depending on system.

Press TelForms OUT icon or From Menu: Actions [altA] Generate TelForms from XML Schema File [altG] to start processing.

The TelForm output will be seen in a directory named out local to the TelFormFactory jar file. Below the out directory there are Applet, Application (also called main), and Midlet sub-directories which contain the TelFormFactory products. There may be 3 subdirectories for each TelForm package:-

• build - this contains the class files containing the code and other intermediate products. This may be deleted by TelFormFactory.
• pub - this contains the final TelForm files for publication. See below.
• src - This contains the Java source files generated from the XML Schema. This may be deleted by TelFormFactory.

Applet 1_1

TelFormFactory generates the following files in directory out/applet1_1/pub:-

• TelForm_NameTelForm.jar - the jar file containing the TelForm Applet.
• index.html - HTML web page referring to the Applet.
• token.css - a sample CSS Stylesheet to define colour and fount preferences.
• js2.js - a file containing some Javascript code. Javascript can enhance Applet performance for some platforms.

The HTML, CSS and Javascript files may be edited or replaced to customise the Applet for your organisation. It is assumed all files will be in the same directory on the web server unless these files are modified.

Application 1_1

Only the TelForm_NameTelForm.jar is generated in out/main1_1/pub. Standalone applications have a 'main' method which means it can be launched from the command line with the command 'java -jar TelForm_NameTelForm.jar. On some platforms it may also be launched by clicking on the jar-file icon.

Midp1

The TelFormFactory out/midp1/pub directory contains TelForm_NameTelForm.jar which has the midlet code and the jad file TelForm_NameTelForm.jad which conforms to Java Archive Descriptor standard. This gives information about the programme in a format understood by devices. Devices may therefore decline to download the jar file if the JAD indicates it is incompatible. It also has other information such as download location of the jar file and costs.

Signing TelForms

Root Properties

Editing TelForm root node properties

Left Click on the TelForm Root icon to see the following properties and edit them for your TelFormHost:

• Server URL: This is the path to the server application. You need to register to use the default TelFormHost, else enter your own.
• Request URL:http request parameters to the server are entered here. Note the 'placeholders' for ${schemaURI} and ${telformName}. These will be updated when 'OK' is pressed. TelFormFactory also adds two more request parameters and values: &t=System.currentTimeMillis() generated at time of Client sending and &u=Random.nextLong() also generated by client. These provide a degree of uniqueness of the Client for the Server.
• Schema NameSpace: Enter the namespace of your schema, or leave if only using datatypes from the TelFormFactory pages.
• Schema URI: In order to be able to validate the Client data against the generated XML Schema, the validator Servlet must be able to access the XML Schema document(s). Enter the (web) location of the Schema here. This will also be inserted in the Request parameters (see above).
• include Schema URI: The XML Schema generated by TelFormFactory includes a further XML Schema which specifies some TelFormFactory types. This document may be seen in the 'docs' folder in the downloaded package 'telform.types.xsd'. The validating schema also needs access to this document.
• TelForm Version: Enter any value to assist in your XML Schema and TelFormFactory configuration file document control.
• TelForm Date: Enter any value to assist in your XML Schema and TelFormFactory configuration file document control.
• TelForm Author: Enter any value to assist in your XML Schema and TelFormFactory configuration file document control.

Node Properties

Click on any TelForm node icon in the TelForm tree (other than the Root) to see the following properties and edit them:

• nodeName This is the name given on creation. Use with care at this time.
• xsdType This is the node datatype. Use with care at this time.
• userHelp The Customer help text entered on creation may be amended here.
• minOccurs The XML Schema validator ensures this field-value appears in the TelForm data at least this number of times. See section.
• maxOccurs The XML Schema validator ensures this field-value appears in the TelForm data at most this number of times. See section.
• Regular Expression This is a grammar which is tested on the data to filter the allowable values. See section.

Editing the TelForm Tree

Right-Click on a TelForm icon to delete it from the model tree. A confirm dialogue must be passed before processing.

Optional and Recurring fields.

By default, when an element is seen in the XML Schema, which equates to a field in the TelForm, the corresponding data value must appear once. It is as if two default parameters were missing from the XML Schema, namely minOccurs="1" and maxOccurs="1". For an optional element the TelForm designer would click on the icon in the Model area, and change the minOccurs value to 0. This indicates the field does not need to be completed.

It may be that some fields should be allowed to appear several times, eg alternative Telephone Numbers or addresses. In this case the maxOccurs value would be changed to the maximum allowable value. To edit the minOccurs and maxOccurs values click on the TelForm field icon.

Regular Expressions

An XML Schema validator checks data by comparing it to its Datatype specified in the XML Schema. The data entered in the form is compared with its datatype and is accepted or rejected on the result. Datatype comparison alone is still a fairly primitive means of detecting data errors but XML Schema also incorporates data testing against Perl-like Regular Expressions. Perl is a scripting language which incorporates a syntax for further definition of permissable values in a data object. This syntax forms Regular Expressions, though there are differences between Perl Regular Expressions and XML Schema Regular Expressions. The next version of TelFormFactory will include Regular Expression Builder to facilitate the use of Reg. Ex.

A number of Open Source and Commercial XML Schema validators are provided with this release of TelFormFactory. They may have different characteristics. These may be switched in or out of the validating process in User Preferences. The commercial products will be provided in a future licensed version of TelFormFactory. Internet access may be required for the validator to load referenced Schema components.

Schema validation is where an XML Document is tested against an XML Schema and found to comply. This validates a Schema file against the W3C reference Schema for Schema.

From Menu: Actions [altA] Validate Schema [altS] brings up a File system browser. Select the Schema File, and OK. Observe the Messages area which will give the results of validation according to the selected validators.

This validates a local XML data file against a local Schema file.

From Menu: Actions [altA] Validate XML [altX] brings up a File system browser. Select the Schema xsd file, and press OK. Another File system browser will come up for you to select the xml data file. Press OK and observe the Messages area which will give the results of validation according to the selected validators.

DTD was a previous technology in the sphere of XML document validation. It has weaknesses and limitations but some documentation and software are still around which assume that DTD is the only method of validation so it pays to be aware. TelFormFactory will soon provide a facility to translate a given DTD to XML Schema.

From Menu: Options [altO] This shows the sub-menu for following groups of options:-

• [altC] Colours and other preferences. [altC]. Most colours of the TelFormFactory application may be edited by selecting the field in the Preferences table, clicking on the Colours icon to open up the Colour Browser and selecting value of choice. Preferences are still under development.
• [altD] Data-types. Favourite Datatypes will be stored here.
• [altX] XML Options. XML Schema validators may be selected and de-selected here. More validators will be integrated with TelFormFactory.
• Clear Settings

• A TelFormFactory file incorporating all TelForm types may be found in the TelFormFactory docs directory - AllTypesTelForm.xml. Open this up, generate AllTypesTelForm.xsd schema and generate the clients. Test these on your platforms.
• The RUN file execution command has by default the argument -autorun true. This causes the clients to feature an autodata control which will enter legitimate data in each field for testing. Edit this data before pressing Apply to test its reaction to non-legitimate data.
• Some Operating Systems cache jar files. In case of problems Use Java Control Panel to clear the cache to ensure latest versions are being loaded.
• Examine the TelFormFactory log file in case of errors.
• To get further debugging information edit the RUN file by appending -debug true to the execution command line.