| Revision History | ||
|---|---|---|
| Revision 1.00 | 2003/11/03 | DR |
| first draft from discussions with PS | ||
Abstract
This document lays out a proposal for redesigning how automated text (e.g., help files, widget documentation, etc.) is supported in Chameleon.
Last Updated: 2003/11/03
Table of Contents
In the past, automated text generation for Chameleon widgets has been handled in a variety of ways, including:
Help file text was contained in a separate help file named WidgetName.help.html.
Information to go in the auto-generated widget document was embedded in various places throughout the PHP source code and automatically extracted when the widget documentation was created.
While this system worked, it had a number of drawbacks, including:
Because information was dispersed in a variety of different location, and in a variety of different formats, it was hard to learn the system and maintain the information.
Much of the structure did not lend itself well to support for multiple languages.
The structure did not allow for adding structure to the information which would allow, among other things, easier auto-generation and grouping of widgets into logical subsets.
To overcome these short-comings, it was decide to propose a completely new structure that would be easier to learn, easier to track, easier to maintain, and easier to expand (as needed) in the future.
In order to best support the adding of new widgets by external developers, it was decided to stick with a one widget, one file system for widget documentation. This means that for each widget, a single documentation file is to be created. All necessary documentation-related information for that widget goes in that one file.
Since this single file for a widget is going to contain a lot of diverse bits of information, it was agreed that it should be written in the structured markup language XML. That way, not only can individual documentation elements be well-defined, there is also the capability to add new tags and tag sets as the design expands over time.
The name of the single documentation file for a widget will be WidgetName.doc.xml and the file will reside in a directory called htdocs/xml. The htdocs/xml directory will contain only the XML files necessary to create the automated documentation for all widgets.
Automatic processes will be created to transform these XML widget files into the end documentation for Chameleon widgets. This end documentation will be generated "on-the-fly", so that when new widgets are added to a Chameleon installation, the widget documentation will be instantly updated.
Because these widget files are all going to be transformed by automated processes before any end-user ever sees the information, the actual XML-based source code can be fairly straight-forward. For each widget installed, there is one documentation file called WidgetName.doc.xml, which has the basic overall structure of:
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
...
</widgetdoc>
The <widgetdoc> tag must be the outward most tag in your file. The name value must match that of your widget, exactly as it is seen in the source file name and the name of this XML documentation file. The group attribute is optional and, if present, lists the subset of widgets that this particular widget belongs to. (See the Widget Groups section for more details.) The optional parentclass attribute lists the class from which this widget inherits functionality and state.
Some widgets include (in the programming sense of the word) common attributes, JavaScript, and/or HTML from a separate source. This relationship can be documented by using <includes> tags.
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
<includes target="Icon"/>
<includes target="Button"/>
...
</widgetdoc>
The included elements in the example above would be documented in the Icon.doc.xml and Button.doc.xml files.
The attributes from the included file are listed in the sample widget tag. However, the rest of the included elements (including the attribute descriptions themselves) are not listed in the widget description. Instead, a hyperlink is provided to the widget from which the elements are included.
Note: There is no way to alter the behavior (e.g., default values) of included functionality within the receiving widget.
One area where this new design is extremely important is in its ability to support multiple languages. In order to facilitate easier translations from language to language, all the textual information is grouped first by language. For example, the ongoing example supporting Canadian English (default) and Canadian French would look like:
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
<includes target="Icon"/>
<includes target="Button"/>
<language name="en-CA">
...
</language>
<language name="fr-CA">
...
</language>
</widgetdoc>
The name values are in standard language code: the first two lowercase letters represent the language (e.g., en is English), while the last two capital letters represent the country (e.g., CA is Canada).
For the next several sections, only the English part of the information is updated. The French part of the example would use exactly the same "English" tag names - but the data within the tags would be in French.
The <description> tag simply holds the overview description of the widget's purpose and working. This is the first tag that actually has "content" within it. For example, assuming the ZoomIn widget was part of a larger BasicWidgets group, its file would look like:
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
<includes target="Icon"/>
<includes target="Button"/>
<language name="en-CA">
<description>
The ZoomIn widget is a navigation tool that allows the user to zoom in
on the map image using either a single point click or by dragging a zooming
box on the map.
</description>
...
</language>
<language name="fr-CA">
...
</language>
</widgetdoc>
The next piece of documentation to deal with is the online help information (previously contained in the WidgetName.help.html files), which is displayed when the user clicks on a help widget in an application. While in many cases, the online help information and the description will be the same, they are not required to be. Use the <onlinehelp> tag to enter this information:
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
<includes target="Icon"/>
<includes target="Button"/>
<language name="en-CA">
<description>
The ZoomIn widget is a navigation tool that allows the user to zoom in
on the map image using either a single point click or by dragging a zooming
box on the map.
</description>
<onlinehelp>
This button provides the capability to zoom in on the current map. To use it,
select the Zoom In tool and then either click the map or click and drag a rectangle.
If the map is clicked, then the view will be recentered at the clicked location
and zoomed in by the user-defined Zoom Factor (provided by the ZoomFactor window).
If a rectangle is dragged, the map view will be zoomed to fit the rectangle.
If the rectangle does not have the same aspect ratio (width/height) as the map
view window then the view will display more of the map than was contained in
the rectangle.
</onlinehelp>
...
</language>
<language name="fr-CA">
...
</language>
</widgetdoc>
One of the most important elements of a Chameleon widget are its attributes. Attributes set the basic rules for how a widget operates when added to an application. Many of the attributes for a widget are likely either inherited from other classes (see Overall Structure) or included from other files (see Includes). In both cases, the adopted attributes are listed in the sample widget tag without you having to explicitly document them within your widget documentation file.
However, there is one small exception. If you wish to alter the behavior of an inherited attribute, you can do so within your source code. To document this alteration, you just have to included an <attribute> tag for it that will override the default inherited one.
The following example includes descriptions of all of the attributes in the ZoomIn widget. Also included is an overriding <VISIBLE> attribute description - to set the default behavior to <false>. The tags below would go within the <language> tag - a complete file is given at the end of this section. [Note: Included attributes cannot have their behavior altered and therefore never need to be documented within the receiving widget's documentation file.]
<attributes>
<attribute name="VISIBLE" type="boolean" required="false">
<possvalues>
<possvalue value="true" default="false"/>
<possvalue value="false" default="true"/>
</possvalues>
<description>
Make the widget visible or not in the page, by default this is true for all widgets.
</description>
</attribute>
<attribute name="DEFAULT" type="boolean" required="false">
<possvalues>
<possvalue value="true" default="false"/>
<possvalue value="false" default="true"/>
</possvalues>
<description>
Controls whether this widget is the default selected navigation tool.
</description>
</attribute>
<attribute name="WIDGETSTYLE" type="string" required="false">
<possvalues>
<possvalue value="[string]"/>
</possvalues>
<description>
From NavTool, this is the CSS class to control the style of this widget. Default is none.
</description>
</attribute>
<attribute name="MINIMUMZOOMRECTANGLE" type="integer" required="false">
<possvalues>
<possvalue value="[integer, > 0]"/>
</possvalues>
<description>
The minimum zooming rectangle that will still be considered a rectangle.
Rectangles smaller than this will be considered a point zoom. The default is 5.
</description>
</attribute>
</attributes>
The following are the descriptions of the tags used to describe widget attributes:
<attributes> tag - A wrapper for all the widget attributes.
<attribute> tag - Contains the name attribute, which specifies what the widget attribute is called; the type attribute, which specifies which type of value is expected; and the required attribute (optional, default = false), which specifies whether the widget attribute must be present or not.
<possvalues> tag - A wrapper for all the possible values for a widget attribute.
<possvalue> tag - Each tag contains one of the possible values accepted for this widget attribute. The value attribute specifies the valid value or a valid type and possibly range (in square brackets); the default (optional, default = false) attribute specifies whether that particular value is the default selection. (Defaults values that lie within stated ranges must be described in the <description> tag.)
<description> tag - Specifies the descriptive text for this widget attribute.
Another aspect of a Chameleon widget is its form elements. [Paul - add some descriptive text here, please.]
The following example includes descriptions of all of the form elements supported by the ZoomIn widget. The tags below would go within the <language> tag - a complete file is given at the end of this section.
<formelements>
<formelement name="NAV_CMD">
<description>
The last command that was used to interact with the map.
</description>
</formelement>
<formelement name="NAV_ALLOW_RECTANGLE">
<description>
Tracks whether the current navigation tool uses a rubber-banding box or not.
</description>
</formelement>
</formelements>
The following are the descriptions of the tags used to describe widget form elements:
<formelements> tag - A wrapper for all the form elements.
<formelement> tag - Contains the name attribute, which specifies what the widget form element is called.
<description> tag - Specifies the descriptive text for this widget form element.
Another aspect of a Chameleon widget is its JavaScript functions. [Paul - add some descriptive text here, please.]
The following example includes descriptions of some (but not all) of the JavaScript functions supported by the ZoomIn widget. The tags below would go within the <language> tag - a complete file is given at the end of this section.
<jsfunctions>
<jsfunction name="setCurrentTool">
<description>
Set the currently active tool from a group of tools.
</description>
</jsfunction>
<jsfunction name="flipToolState">
<description>
Toggle the state of a tool button.
</description>
</jsfunction>
<jsfunction name="registerTool">
<parameters>
<parameter name="n" type="[int]">
This integer value is a number.
</parameter>
<parameter name="title" type="[string]">
This string is a title.
</parameter>
</parameters>
<description>
Register a tool in the page.
</description>
</jsfunction>
</jsfunctions>
The following are the descriptions of the tags used to describe widget JavaScript functions:
<jsfunctions> tag - A wrapper for all the JavaScript functions.
<jsfunction> tag - Contains the name attribute, which specifies what the widget JavaScript function is called.
<parameters> tag - A wrapper for all the parameters for a JavaScript function.
<parameter> tag - Specifies a parameter for this widget JavaScript function, along with a description of the parameter. Parameters should be included in the order that they must be in the function itself.
<description> tag - Specifies the descriptive text for this widget JavaScript function.
Another aspect of a Chameleon widget is its JavaScript variables. [Paul - add some descriptive text here, please.]
The following example includes descriptions of all of the JavaScript variables supported by the ZoomIn widget. The tags below would go within the <language> tag - a complete file is given at the end of this section.
<jsvariables>
<jsvariable name="aToolGroups">
<description>
Array used to manage groups of tools on the page.
</description>
</jsvariable>
<jsvariable name="aTools">
<description>
Array of tools on the page.
</description>
</jsvariable>
<jsvariables>
The following are the descriptions of the tags used to describe widget JavaScript variables:
<jsvariables> tag - A wrapper for all the JavaScript variables.
<jsvariable> tag - Contains the name attribute, which specifies what the widget JavaScript variable is called.
<description> tag - Specifies the descriptive text for this widget JavaScript variable.
Another aspect of some Chameleon widgets is their events. Chameleon's event system gives you the ability to make choices in some circumstances. For example, the SQLQuery widget tries to connect to a database before doing its query. If the connection to the database fails, you might want to display a simple error message, or redirect to another template, or do something completely different. With events, you can specify which action to take.
The following example includes descriptions of a fictitious event supported by the ZoomIn widget. The tags below would go within the <language> tag - a complete file is given at the end of this section.
<events>
<event name="SomeEvent1">
<description>
This is not a particular event. Just an example.
</description>
</event>
<event name="SomeEvent2">
<parameters>
<parameter name="n" type="[int]">
This integer value is a number.
</parameter>
<parameter name="title" type="[string]">
This string is a title.
</parameter>
</parameters>
<description>
This is not a particular event. Just another example.
</description>
</event>
<events>
The following are the descriptions of the tags used to describe widget events:
<events> tag - A wrapper for all the widget's events.
<event> tag - Contains the name attribute, which specifies what the widget event is called.
<parameters> tag - A wrapper for all the parameters for an event.
<parameter> tag - Specifies a parameter for this widget event, along with a description of the parameter. Parameters should be included in the order that they must be in the event itself.
<description> tag - Specifies the descriptive text for this widget event.
Any widget can be designed to support valid XML subtags. Each subtag can have its own attributes and subtags.
The following example includes description of a fictitious subtag supported by the ZoomIn widget. The <zoom> subtag allows the ZoomIn button to zoom in to different magnification levels. The <children> tag is a wrapper for all the subtags supported by the widget, while the <child> tag contains the actual subtag description.
<children>
<child name="zoom">
<description>
The zoom subtag allows the user to specify specific magnification levels to zoom in to.
</description>
<attributes>
<attribute name="LEVEL" required="true">
<possvalue value="[int, > 1]"/>
<description>
The value for a possible magnification level.
</description>
</attribute>
</attributes>
<children>
...
</children>
</child>
...
</children>
The above example lists all of the valid elements for a subtag description. Some things to keep in mind.
You may note that there are no <language> tags within the subtag description. Subtags take on the language defined by the enclosing <widgetdoc>.
The following is the complete XML file (called ZoomIn.doc.xml) for the English-only automated documentation for the ZoomIn widget:
<widgetdoc name="WidgetName" group="WidgetGroup" parentclass="ClassName">
<includes target="Icon"/>
<includes target="Button"/>
<language name="en-CA">
<description>
The ZoomIn widget is a navigation tool that allows the user to zoom in
on the map image using either a single point click or by dragging a zooming
box on the map.
</description>
<onlinehelp>
This button provides the capability to zoom in on the current map. To use it,
select the Zoom In tool and then either click the map or click and drag a rectangle.
If the map is clicked, then the view will be recentered at the clicked location
and zoomed in by the user-defined Zoom Factor (provided by the ZoomFactor window).
If a rectangle is dragged, the map view will be zoomed to fit the rectangle.
If the rectangle does not have the same aspect ratio (width/height) as the map
view window then the view will display more of the map than was contained in
the rectangle.
</onlinehelp>
<attributes>
<attribute name="VISIBLE" type="boolean" required="false">
<possvalues>
<possvalue value="true" default="false"/>
<possvalue value="false" default="true"/>
</possvalues>
<description>
Make the widget visible or not in the page, by default this is true for all widgets.
</description>
</attribute>
<attribute name="DEFAULT" type="boolean" required="false">
<possvalues>
<possvalue value="true" default="false"/>
<possvalue value="false" default="true"/>
</possvalues>
<description>
Controls whether this widget is the default selected navigation tool.
</description>
</attribute>
<attribute name="WIDGETSTYLE" type="string" required="false">
<possvalues>
<possvalue value="[string]"/>
</possvalues>
<description>
From NavTool, this is the CSS class to control the style of this widget. Default is none.
</description>
</attribute>
<attribute name="MINIMUMZOOMRECTANGLE" type="integer" required="false">
<possvalues>
<possvalue value="[integer, > 0]"/>
</possvalues>
<description>
The minimum zooming rectangle that will still be considered a rectangle.
Rectangles smaller than this will be considered a point zoom. The default is 5.
</description>
</attribute>
</attributes>
<formelements>
<formelement name="NAV_CMD">
<description>
The last command that was used to interact with the map.
</description>
</formelement>
<formelement name="NAV_ALLOW_RECTANGLE">
<description>
Tracks whether the current navigation tool uses a rubber-banding box or not.
</description>
</formelement>
</formelements>
<jsfunctions>
<jsfunction name="setCurrentTool">
<description>
Set the currently active tool from a group of tools.
</description>
</jsfunction>
<jsfunction name="flipToolState">
<description>
Toggle the state of a tool button.
</description>
</jsfunction>
<jsfunction name="registerTool">
<parameter name="n" type="[int]">
This integer value is a number.
</parameter>
<parameter name="title" type="[string]">
This string is a title.
</parameter>
<description>
Register a tool in the page.
</description>
</jsfunction>
<jsfunction name="onButtonOver">
<description>
Callback when the mouse moves over a button.
</description>
</jsfunction>
<jsfunction name="onButtonOut">
<description>
Callback when the mouse leaves a button.
</description>
</jsfunction>
<jsfunction name="onButtonClick">
<description>
Callback when a button is clicked.
</description>
</jsfunction>
<jsfunction name="NavSetActiveTool">
<description>
Set the active navigation tool for a particular group of tools.
</description>
</jsfunction>
<jsfunctions>
<jsvariables>
<jsvariable name="aToolGroups">
<description>
Array used to manage groups of tools on the page.
</description>
</jsvariable>
<jsvariable name="aTools">
<description>
Array of tools on the page.
</description>
</jsvariable>
<jsvariables>
<events>
<event name="SomeEvent1">
<description>
This is not a particular event. Just an example.
</description>
</event>
<event name="SomeEvent2">
<parameters>
<parameter name="n" type="[int]">
This integer value is a number.
</parameter>
<parameter name="title" type="[string]">
This string is a title.
</parameter>
</parameters>
<description>
This is not a particular event. Just another example.
</description>
</event>
<events>
<children>
<child name="zoom">
<description>
The zoom subtag allows the user to specify specific magnification levels to zoom in to.
</description>
<attributes>
<attribute name="LEVEL" required="true">
<possvalue value="[int, > 1]"/>
<description>
The value for a possible magnification level.
</description>
</attribute>
</attributes>
</child>
</children>
</language>
</widgetdoc>
The quickest way to add a second language to the above file would be to copy the entire English <language>...</language> section and paste it directly below itself. Then, translate only the parts that are not directly part of tags (i.e., that do not fall between a < and a >) into the second language. Don't forget to alter the name attribute in the new <language> tag as well.
As mentioned in the Overall Structure section, individual widgets can be lumped together into widget groups. While typically these groups are based on related functionality, there can be other, less functional reasons for creating groups as well. The result of creating a group of widgets is that the documentation elements for the grouped widgets are presented together under the group's heading.
To specify that a widget belongs to a group, simply place the group attribute in the widgetdoc tag. The value given to the group attribute corresponds directly to the name of the group.
Each widget group also has a single XML file, named GroupName.group.xml, placed in the htdocs/xml directory, that contains information about the group. An example of the English-only XML file for the BasicWidgets group, BasicWidgets.group.xml, follows:
<widgetgroup name="BaWidgets">
<language name="en-CA">
<description>
The BasicWidgets group contains the standard set of everyday widgets that
are used by most Chameleon applications, including such things as map
rendering, navigation, scale, etc.
</description>
<onlinehelp>
The BasicWidgets group contains the standard set of everyday widgets that
are used by most Chameleon applications, including such things as map
rendering, navigation, scale, etc.
</onlinehelp>
</language>
</widgetgroup>
As you can see, the widgetgroup can contain language and description tags, just like the widgetdoc tag. Things to note:
The widget group description will appear at the top of any listing of the group's widget descriptions.
Multiple languages can be added simply by adding additional language tag sections.
The individual widgets in the widget group are not listed within the widgetgroup tag - they are automatically generated based on the group attributes in their widgetdoc tags.
Copyright (c) 2003, Darren Redfern, DM Solutions Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.