| 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">
...
</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.)
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">
<language name="en-CA", default="true">
...
</language>
<language name="fr-CA", default="false">
...
</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). The default attribute is optional and refers to which language is used if no language is explicitly chosen (or if the chosen language is not supported in this documentation file). However, if a supported language is chosen within a Chameleon interface, the automated documentation is compiled accordingly.
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="ZoomIn" group="BasicWidgets">
<language name="en-CA" default="true">
<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", default="false">
...
</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="ZoomIn" group="BasicWidgets">
<language name="en-CA" default="true">
<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", default="false">
...
</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. Some attributes are shared across widgets and these can be marked with the optional type attribute. The automatic generator scripts will then determine where and whether to include these attributes in the widget documentation. [Need to determine whether these attributes need to be detailed in each widget they are in. I'm leaning towards yes - makes things more separable.]
The following example includes descriptions of some (but not all) of the attributes in the ZoomIn widget. The tags below would go within the <language> tag - a complete file is given at the end of this section.
<attribute name="TYPE" type="base" required="true">
<attvalue value="zoomin" default="true"/>
<attdesc>
The type of the widget indicates the actual widget object to create for this tag.
</attdesc>
</attribute>
<attribute name="VISIBLE" type="base" required="false">
<attvalue value="true" default="true"/>
<attvalue value="false" default="false"/>
<attdesc>
Make the widget visible or not in the page, by default this is true for all widgets.
</attdesc>
</attribute>
<attribute name="IMAGE" type="image" required="true">
<attvalue value="[string]"/>
<attdesc>
The image to display for this icon.
</attdesc>
</attribute>
<attribute name="DEFAULT" required="false">
<attvalue value="true" default="false"/>
<attvalue value="false" default="true"/>
<attdesc>
Controls whether this widget is the default selected navigation tool.
</attdesc>
</attribute>
<attribute name="WIDGETSTYLE" required="false">
<attvalue value="[string]"/>
<attdesc>
From NavTool, this is the CSS class to control the style of this widget. Default is none.
</attdesc>
</attribute>
<attribute name="MINIMUMZOOMRECTANGLE" required="false">
<attvalue value="[integer, > 0]"/>
<attdesc>
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.
</attdesc>
</attribute>
The following are the descriptions of the tags used to describe widget attributes:
<attribute> tag - Contains the name attribute, which specifies what the widget attribute is called; the type attribute (optional, default = None), which specifies which (if any) shared type the widget attribute belongs to; and the required attribute (optional, default = false), which specifies whether the widget attribute must be present or not.
<attvalue> 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 <attdesc> tag.)
<attdesc> 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.
<formelement name="NAV_CMD">
<formdesc>
The last command that was used to interact with the map.
</formdesc>
</formelement>
<formelement name="NAV_ALLOW_RECTANGLE">
<formdesc>
Tracks whether the current navigation tool uses a rubber-banding box or not.
</formdesc>
</formelement>
The following are the descriptions of the tags used to describe widget form elements:
<formelement> tag - Contains the name attribute, which specifies what the widget form element is called.
<formdesc> 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.
<jsfunction name="setCurrentTool()">
<jsfuncdesc>
Set the currently active tool from a group of tools.
</jsfuncdesc>
</jsfunction>
<jsfunction name="flipToolState()">
<jsfuncdesc>
Toggle the state of a tool button.
</jsfuncdesc>
</jsfunction>
<jsfunction name="registerTool()">
<jsfuncdesc>
Register a tool in the page.
</jsfuncdesc>
</jsfunction>
The following are the descriptions of the tags used to describe widget JavaScript functions:
<jsfunction> tag - Contains the name attribute, which specifies what the widget JavaScript function is called.
<jsfuncdesc> 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.
<jsvariable name="aToolGroups">
<jsvardesc>
Array used to manage groups of tools on the page.
</jsfuncdesc>
</jsfunction>
<jsvariable name="aTools">
<jsvardesc>
Array of tools on the page.
</jsfuncdesc>
</jsfunction>
The following are the descriptions of the tags used to describe widget JavaScript variables:
<jsvariable> tag - Contains the name attribute, which specifies what the widget JavaScript variable is called.
<jsvardesc> tag - Specifies the descriptive text for this widget JavaScript variable.
The following is the complete XML file (called ZoomIn.doc.xml) for the English-only automated documentation for the ZoomIn widget:
<widgetdoc name="ZoomIn" group="BasicWidgets">
<language name="en-CA" default="true">
<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>
<attribute name="TYPE" type="base" required="true">
<attvalue value="zoomin" default="true"/>
<attdesc>
The type of the widget indicates the actual widget object to create for this tag.
</attdesc>
</attribute>
<attribute name="VISIBLE" type="base" required="false">
<attvalue value="true" default="true"/>
<attvalue value="false" default="false"/>
<attdesc>
Make the widget visible or not in the page, by default this is true for all widgets.
</attdesc>
</attribute>
<attribute name="ENABLED" type="base" required="false">
<attvalue value="true" default="true"/>
<attvalue value="false" default="false"/>
<attdesc>
Enable or disable the widget in the interface. (Not currently supported, always true.)
</attdesc>
</attribute>
<attribute name="IMAGE" type="image" required="true">
<attvalue value="[string]"/>
<attdesc>
The image to display for this icon.
</attdesc>
</attribute>
<attribute name="IMAGEWIDTH" type="image" required="false">
<attvalue value="[string]"/>
<attdesc>
The width in pixels of this image.
</attdesc>
</attribute>
<attribute name="IMAGEHEIGHT" type="image" required="false">
<attvalue value="[string]"/>
<attdesc>
The height in pixels of this image.
</attdesc>
</attribute>
<attribute name="IMAGETIP" type="image" required="false">
<attvalue value="[string]"/>
<attdesc>
The alternate or tooltip text to display for this image.
</attdesc>
</attribute>
<attribute name="IMAGECLASS" type="image" required="false">
<attvalue value="[string]"/>
<attdesc>
The CSS class to control the rendering of this image. The default is no class.
</attdesc>
</attribute>
<attribute name="IMAGESTYLE" type="image" required="false">
<attvalue value="[string]"/>
<attdesc>
A CSS style to apply to this image tag. The default is no style.
</attdesc>
</attribute>
<attribute name="TOOLSET" type="button" required="false">
<attvalue value="[string]"/>
<attdesc>
A name indicating a logical group of tools of which only one can be selected.
</attdesc>
</attribute>
<attribute name="IMAGESELECTED" type="button" required="false">
<attvalue value="[string]"/>
<attdesc>
The image to display when this button is selected.
</attdesc>
</attribute>
<attribute name="IMAGEHOVER" type="button" required="false">
<attvalue value="[string]"/>
<attdesc>
The image to display when the mouse hovers over this button.
</attdesc>
</attribute>
<attribute name="DEFAULT" required="false">
<attvalue value="true" default="false"/>
<attvalue value="false" default="true"/>
<attdesc>
Controls whether this widget is the default selected navigation tool.
</attdesc>
</attribute>
<attribute name="WIDGETSTYLE" required="false">
<attvalue value="[string]"/>
<attdesc>
From NavTool, this is the CSS class to control the style of this widget. Default is none.
</attdesc>
</attribute>
<attribute name="MINIMUMZOOMRECTANGLE" required="false">
<attvalue value="[integer, > 0]"/>
<attdesc>
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.
</attdesc>
</attribute>
<formelement name="NAV_CMD">
<formdesc>
The last command that was used to interact with the map.
</formdesc>
</formelement>
<formelement name="NAV_ALLOW_RECTANGLE">
<formdesc>
Tracks whether the current navigation tool uses a rubber-banding box or not.
</formdesc>
</formelement>
<jsfunction name="setCurrentTool()">
<jsfuncdesc>
Set the currently active tool from a group of tools.
</jsfuncdesc>
</jsfunction>
<jsfunction name="flipToolState()">
<jsfuncdesc>
Toggle the state of a tool button.
</jsfuncdesc>
</jsfunction>
<jsfunction name="registerTool()">
<jsfuncdesc>
Register a tool in the page.
</jsfuncdesc>
</jsfunction>
<jsfunction name="onButtonOver()">
<jsfuncdesc>
Callback when the mouse moves over a button.
</jsfuncdesc>
</jsfunction>
<jsfunction name="onButtonOut()">
<jsfuncdesc>
Callback when the mouse leaves a button.
</jsfuncdesc>
</jsfunction>
<jsfunction name="onButtonClick()">
<jsfuncdesc>
Callback when a button is clicked.
</jsfuncdesc>
</jsfunction>
<jsfunction name="NavSetActiveTool()">
<jsfuncdesc>
Set the active navigation tool for a particular group of tools.
</jsfuncdesc>
</jsfunction>
<jsvariable name="aToolGroups">
<jsvardesc>
Array used to manage groups of tools on the page.
</jsfuncdesc>
</jsfunction>
<jsvariable name="aTools">
<jsvardesc>
Array of tools on the page.
</jsfuncdesc>
</jsfunction>
</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="BacisWidgets">
<language name="en-CA" default="true">
<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.