XML Qbit specification documentation

The XML Qbit specification allows you to make quite powerful additions to onCue. These include linking into Intranet and Internet services, sending users to specific pages based on keywords, performing some forms of simple translation or replacement.

This document describes the XML Qbit files in some technical detail. See also the online documentation for simple XML Qbit patterns and the aQtive web site for wizards to write XML for you.

It is also possible to write Qbits in Java using the onCue API. However, for simple Qbits the XML route is far easier.

Concepts

onCue operates by a combination of two types of user definable 'Qbits': recognisers and services. See onCue - how it works for a detailed explanation of how recognisers and services work together in onCue.

Recognisers

Recognisers are not visible to the user. They are simply means of converting one data type to another, i.e. a string may be "recognised" as a postcode and a postcode type is output from the recogniser.

So data on the clipboard is passed through an array of recognisers and the result is a set of data types e.g. word, name, postcode, etc.

Importantly the output from one recogniser can be fed into another e.g. string to word and word to name.

Services:

Services are visible to the user (when they are in context: i.e. upmystreet only appears when you enter a postcode).

A service watches out for a data type. The data types are those which are generated by the recognisers (see above).

Once a data type for which a service is watching appears, the service's icon appears to the user in the onCue window. Several actions based on the data that has been recognised can be suggested by means of the drop-down menus on the service icon. So together recognisers and services can watch out for types of data and present services which are in context.

Example XML Qbit definition

One XML Qbit can specify 1 recogniser and/or 1 service.

Look at the example XML Qbit showing most of the tags and tag attributes. In XML some of the attributes can be omitted and a default value is used. These are detailed in the syntax specification (described later). See also the annotated version of this file.

The example shows how a Qbit can specify a recogniser which takes a string input data type and checks to see if the string is Andy Pryke’s name. A regular expression is used to allow Andy’s name to be recognised in various formats. The syntax of regular expressions is outside the scope of this document.

Once the recogniser has successfully recognised the string as Andy Pryke it constructs an output type, in this case called “My Andy Pryke Type”. This is constructed by the “Is” element.

This is the work of the recogniser finished.

Next the service, which is defined to accept the data type “My Andy Pryke Type”, receives this type and displays its icon. The menu items which can be displayed by clicking on the icon are defined by the url and copy elements. These launch a browser and go to the url specified (url element) and copy data to the clipboard (copy element).

A service can be defined to accept any data type produced by a recogniser, not just the type from the recogniser defined in the same .xml file.

Explanation of Key Points

The <match></match> tag:

The match tag in full is
<match type=XXX ignorecase=YYY>keywords or regexpression</match>
The first of the options in the match tag determines what kind of matching to use: type="RegExp" for regular expression matching or type=keywords for a list of comma-separated keywords, e.g. <match type="Keywords">hello, find, one, of, these, keywords</match>
For the case when keywords are used, the ignorecase option says whether or not to ignore the case of letters when matching: ignorecase="Yes" or "No"

Substitution using $0, etc:

When matching a regular expression, the text matched by each set of brackets in the regular expression is available in the recogniser using substitution of $n where n is the number of left brackets in (from the beginning of the reg expression) where the match occurs;
e.g. in the example above $0

is everything (outermost) and $3 would be Mr or Dr (because the third bracket in matches either Dr or Mr).
The $n values and substitution are used for the construction of the output data type (i.e. the Is tag)
e.g. <Field Name="Passed" Expand="Yes">$0</Field>
note the use of Expand="Yes" to enable substitution of the $0.
In the service the data for substitution does not use the $n syntax because the $n referred to a location in the regular expression. In the service we have an input data type with field names. So to substitute in the service element the syntax is ${FieldName} e.g ${first bit}. The expand=”Yes” attribute must also be set or the substitute syntax will be used literally.

Syntax Definition

The following is the XML standard means for defining syntax.
Each element (e.g. <match></match>) and element attribute (e.g. <match type="User"></match>)
is defined here and the order of nested elements is also defined.
To show how nested elements are defined we look at the outer element of this syntax.
Each XML Qbit has the outer element <Qbit></Qbit> and can have a recogniser element and a service element nested inside or only one of either or even no other elements inside (not very useful).
This is defined by the line

   <!ELEMENT Qbit ( Recogniser?, Service? ) >

It says "The element Qbit can have an optional recogniser element and/or an optional service element but the order, if both, must be recogniser first then service".

If the comma between Recogniser and Service had been a space instead then the order would not have been specified. The question marks indicate an optional element (if the question marks had been "*" instead, we could have any number of the nested elements.)
So, ignoring the required attributes and nested elements inside service and recogniser, we can have:

   <Qbit>
   </Qbit>

or

   <Qbit>
   <Recogniser>
   </Recogniser>
   </Qbit>

or

   <Qbit>
   <Service>
   </Service>
   </Qbit>

or

   <Qbit>
   <Recogniser>
   </Recogniser>
   <Service>
   </Service>
   </Qbit>

An element may have one value, like the author element
e.g. <Author>Justin</Author> and defined as <!ELEMENT Author ( #PCDATA ) >

(#PCDATA means the element takes a character value)

or an element may have several attributes like

   <Copy Expand="Yes">example copy data</copy>

where we have an element value and an attribute.This is defined by

   <!ELEMENT Copy ( #PCDATA ) >
   <!ATTLIST Copy Expand (Yes | No) "No" >

The Expand attribute can take the values "Yes" or "No" and the default if the attribute is missing is "No". The attribute can be specified as required by using "#REQUIRED" instead of the default value.
Do not worry about the ENTITY lines.

The XML Qbit syntax as an XML DTD

   <!-- DTD for combined Qbits -->
   <!-- Version 0.1 -->
   <!-- Date 29/09/99 -->
   <!ENTITY lt "&lt;" >
   <!ENTITY gt "&gt;" >
   <!ENTITY apos "&apos;" >
   <!ENTITY quot "&quot;" >
   <!ENTITY amp "&amp;" >
   <!ELEMENT Author ( #PCDATA ) >
   <!ELEMENT Constructor ( Parameter* ) >
   <!ELEMENT Copy ( #PCDATA ) >
   <!ATTLIST Copy Expand (Yes | No) "No" >
   <!ELEMENT Field ( #PCDATA ) >
   <!ATTLIST Field Expand (Yes | No) "No" >
   <!ATTLIST Field Name CDATA #REQUIRED >
   <!ELEMENT For ( URL*, Copy* ) >
   <!ATTLIST For Name CDATA #REQUIRED >
   <!ATTLIST For Type (User | JavaClass) "User" >
   <!ELEMENT Help ( #PCDATA ) >
   <!ELEMENT Icon ( #PCDATA ) >
   <!ELEMENT IGNORETAG ( Qbit+ ) >
   <!ELEMENT Is ( Field+, Constructor? ) >
   <!ATTLIST Is Name CDATA #REQUIRED >
   <!ATTLIST Is Type (User | JavaClass) "User" >
   <!ELEMENT Match ( #PCDATA ) >
   <!ATTLIST Match IgnoreCase (Yes | No) "Yes" >
   <!ATTLIST Match Type (RefExp | Keywords) "Keywords" >
   <!ELEMENT Name ( #PCDATA ) >
   <!ELEMENT Parameter ( #PCDATA ) >
   <!ATTLIST Parameter Expand (Yes | No) "No" >
   <!ATTLIST Parameter Name NMTOKEN #REQUIRED >
   <!ELEMENT Qbit ( Recogniser?, Service? ) >
   <!ELEMENT Recogniser ( Name, Recognises, Is ) >
   <!ELEMENT Recognises ( Match? ) >
   <!--Recognises Name defaults to "java.lang.String" - respond to the clipboard. -->
   <!ATTLIST Recognises Name CDATA #IMPLIED >
   <!ATTLIST Recognises Type (User | JavaClass) "JavaClass" >
   <!ELEMENT Service (Name, Icon, Author, Help, For ) >
   <!ELEMENT URL ( #PCDATA ) >
   <!ATTLIST URL Expand (Yes | No) "No" >
   <!ATTLIST URL Label CDATA #REQUIRED >