Download telformfactory_userguide.pdf

TelFormFactory User Guide

Guide to using TelFormFactory to generate XML Schema and conforming Client Java Forms.

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

Screenshot of TelFormFactory from Terry Comms Ltd.

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.

TelFormFactory Features

TelForm Client Platforms

Currently TelForms are available in these formats:-

Java Software Standards

TelFormFactory now assumes the latest stable Java release. For mobiles midp1 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.

Client Form design

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.

TelFormFactory Installation

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. It is not a permanent installation, is not registered and may be deleted at any time.

To run TelFormFactory double-click on the command file according to your system:

Unix systems: - Shell file run
Windows systems: - Batch file run.bat

In case of problems, open a console screen, change to the programme directory and enter run at the command line:-

Unix systems: - calls shell file run
Windows systems: - calls batch file run.bat

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.

TelFormFactory Operation

Screen Layout

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.

Icon Menu

See Operations descriptions below.

TelFormFactory Datatypes

The XML Schema validates data by comparing against its datatype definition which is given in the World Wide Web ConsortiumW3C XML Schema specification. Place cursor over each Datatype icon for tooltip text. TelFormFactory provides 4 'pages' of Datatypes from which you choose the type of field to be added to the TelForm. Two pages of these are extracted directly from the W3C Recommendation part 2 (2 May 2001). These are indicated by the prefix 'xsd:' indicating membership of the XML Schema namespace or grammar. Datatypes and pseudo-datatypes belonging to http://telform.co/ns/2009/telform namespace are seen with the colon prefix tok. See Datatypes for details.

  • Inbuilt Schema Types ie integral to the Recommendation.
  • Derived Schema Types are Recommendation datatypes adapted from the Inbuilt types but are considered important enough to identify independently.
  • The first page Basic TelForm Types includes 3 types removed from the Inbuilt Types, these are the most basic fields, with minimum checking. -
    • string - use when no other datatype is available.
    • integer - whole numbers, but see definitions.
    • decimal - compare with other floating point numbers.
    Other types on the TelForm Types page are:-
    • EmailFieldType
    • PhoneFieldType
    • MultipleChoiceType made up of MultipleChoiceItemTypes
    • ExclusiveChoiceType made up of ExclusiveChoiceItemTypes
    • GROUP_HEADER is a pseudo-type which serves to group together related form fields and a corresponding branch in the XML data generated by the TelForm.
  • The fourth Datatype page is Favourites which the TelFormFactory user can use to store customised Datatypes. This is not yet complete in this version of TelFormFactory.

New TelForm

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.

Adding Data types to the TelForm

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.

Saving TelFormFactory file

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 be published.

Opening TelFormFactory file

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.

Generating XML Schema

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.

Generating TelForms

Select the Radio Button on the Toolbar according to the TelForm package required - namely Applet, Application, 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:-

Output Packages

Applet

TelFormFactory generates the following files in directory out/applet/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

Only the TelForm_NameTelForm.jar is generated in out/main/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.

Publishing TelForms.

Signing TelForms

Applets are normally restricted in capability such as File system or Network access unless security requirements are met such as having been signed with your digital signature. Midlets are similarly restricted, though user permission can over-ride this. Applications are not normally restricted but it is in the security interests of the TelForm producer and the user for TelForm packages to be signed. Edit the appropriate batch file with your details to use the Java Development Kit jarsigner tool. From the command line enter signer. For more information on digital certificates and security see Telform Security

Unix systems: - calls shell file signer
Windows systems: - calls batch file signer.bat

Delivery

  • To run an applet, a Web Browser is used to parse the corresponding Web page and, if properly configured, activates the Java Virtual Machine. The JVM which runs the Java Applet may be integral to the Web Browser or may use a JVM on the platform. This is often configurable within the Web Browser.
  • An application does not need a Web browser and can be delivered by any File or Network transfer method.
  • A midlet may be delivered by embedding the JAD file in a web page, in a similar manner to the applet. It is important that the web server is configured with the correct MIME type so that the device knows how to handle the file when browsing the internet. This may be acheived with the (hidden) .htaccess in the midp1/pub directory - just upload ith with the JAD and JAR files. The JAD file may also be sent direct to a Customer device by SMS, Email, Bluetooth Infra-Red or any other method. This is known as Over The Air or OTA application where for example a Central Office can push the jad file for a TelForm timesheet or invoice to an employee's cellphone. The employee downloads the jar file, fills in the TelForm, and returns it by GPRS or other Network method.

Advanced Features of XML Schema and TelFormFactory

Editing the TelForm Model

Root Properties

Screenshot of TelForm root node properties edit dialogue.

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.

Validating Schema and XML data

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.

Validating Schema

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.

Validating XML

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.

Document Type Definition and XML Schema

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. Tools are available to translate a given DTD to XML Schema.

TelFormFactory Options

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

Testing and Trouble-shooting TelFormFactory

OverviewTelFormFactoryTelForm HostTelForm ClientsTelForm Security
WindowsTelForms on PCsTelForms on MobilesDownload PDFSDownload TelFormFactory

To TOP