How to Write a Preference Wizard Plug-in
David Weinkauf and Joseph Scheuhammer
Adaptive Technology Resource Centre, University of Toronto
Table of Contents
This document describes what a developer must do to ensure that the
Preference Wizard Manager (PWM) is able to find, load, and activate a
preferences plug-in. It also describes how to implement the function of
the preferences plug-in itself in terms of what information is passed
to it, where it can acquire other relevant information, and its
functionality. Two sources of information provide all the information
required for the plug-in to do its job. They are: a file that declares
properties of the plug-in and the plug-in code itself.
Third Party Preferences
Third party preferences are non-generic, application specific
preferences. They are represented in the AccLIP as the
element which is defined as:
The third party preferences are children of the
<element name = "param" type = "imsacclip:paramElementType"/>
<complexType name = "paramElementType">
<extension base =
<attributeGroup ref = "imsacclip:attrParam"/>
<attributeGroup name = "attrParam">
<attribute name = "name" use = "required" type =
<attribute name = "value" type = "string"/>
element which is defined in the AccLIP as:
<complexType name = "applicationElementType">
<element ref =
"imsacclip:param" minOccurs = "0" maxOccurs = "unbounded"/>
<any namespace = "##other"
processContents = "strict" minOccurs = "0" maxOccurs = "unbounded"/>
<attributeGroup ref =
<attributeGroup name = "attrApplication">
<attribute name = "name" use = "required" type =
<attribute name = "version" type = "string"/>
<attribute name = "priority" use = "required"
type = "imsacclip:priorityType"/>
A two stage process is used to load and invoke a preferences
plug-in. In the first stage, the Control Hub loads information about all
the available plug-ins. The second stage occurs when the Preference
Wizard Manager is in the process of editing a user's AccLIP preferences,
and the user wishes to change the non-generic settings for a particular
third party application.
See the Plug-in
Information section in the Configuration
Preference Wizard Plug-in API
Preferences plug-ins must implement a common API in order to qualify
as a plug-in. The API is made up of a number of JavaTM interfaces and classes. The
central API is the interface
This section declares the methods of
and describes their intent. The methods of
are described in the order that the Preference Wizard Manager (PWM)
calls them; in brief, the use case for editing third party preferences
is as follows:
- If preferences plug-in exists, PWM enables the "Edit Custom
Preferences" button for the application.
- User selects the "Edit Custom Preferences" button.
- PWM gets the third party preferences for a given application from
the user's AccLIP preferences.
- PWM launches the third party preference wizard passing the
preferences as a stand-alone XML document.
- User edits his/her third party preferences and exits the plug-in.
- PWM inserts the new third party preferences into the user's AccLIP preferences.
public int doPreferences (Document io3rdPartyDoc, Locale
- This method is called to do whatever is necessary to edit the
third party preferences. For example, this usually includes launching a
modal JDialog containing UI widgets, which encapsulate the third party
preference settings allowing the user to select their desired
preferences through their interaction with this dialog. The meaning of
the arguments are as follows:
- This is an XML document containing all third party
preferences for the application. The root element of the document is
<application> tag corresponding to the third
party application. The
<application> tag's children
will be the enumeration of all the third party preferences consisting
<param> tag(s) with
attributes as specified in the AccLIP schema.
- This indicates the user's preferred locale. Any UI displayed
should conform to this locale. Currently Web-4-All supports the
following locales: English (Canadian) and French (Canadian) - i.e.
en-CA and fr-CA.
- Return value:
- This is an integer, which indicates whether an error
occurred. If no error has occurred, the plug-in returns 0. If an error
did occur, the plug-in returns a non-zero value and no changes will be
made to user preferences.
public void kill();
- This method is called to dispose of any modal dialogs
may have launched when it was called. This method is called if a user
ends his/her Web-4-All session while
The AccLIP schema allows for "strict" extensions in the children and
attributes of most elements. One prerequisite for strict schema
extensions defined by the <any> or <anyAttribute> tag is
the inclusion of a top-level declaration for the available item.
Web-4-All does not define any extended top-level ##other namespaces or
include any extended schemas inside the AccLIP schema it validates
against, nor does it provide a mechanism to do this programmatically
for the third party plugins. Another prerequisite for strict schema
extensions is the inclusion of a xsi:type
in the item. Since the AccLIP schema used in Web-4-All does not include
top-level declarations for extended elements, the only xsi:type's allowed would be simple
types defined in a standard XML specification, such as XML Schema. This
is problematic for Web-4-All insofar as a user's set of preferences is
binded to a low-memory representation before being stored on the
smartcard. Any foreign elements pose a problem to the conversion to and
from this binding. This is done to ensure that large-sized preferences
will be able to fit on the small amount of memory present on the
smartcard. The AccLIP already provides a mechanism for defining simple
name/value types in the <param> element which we feel is equal to
extended elements defined by standard XML specification built-in types
(at least in terms of conveying information to an application).
Therefore, preference wizard plug-ins are only allowed to return XML
documents containing one root <application> element and zero or
more <param> elements. All of these must be leaf nodes containing
a name attribute and an optional value attribute. No xsi:type extended elements are
allowed in the third party preferences. Before inserting third party
preferences into the user's AccLIP preferences, a validation check is
made on the third party preferences; if the check fails, no updates are
made to the user's AccLIP preferences.
Multi-type Adaptive Technology
A third party technology is allowed only one preferences plug-in
regardless the number of adaptive technology types it may subsume. All
third party preferences for a given application are stored under one
<application> tags. In
addition, all third party preferences are passed to the third party
plug-in upon its launch regardless of the adaptive technology type in
Location of Code and Data
See the Location
of Code and Data section in the Configuration
This document has described the essentials of creating a preferences
plug-in for the Web-4-All system. If the properties file and
are implemented and located properly within the file system, then the
Preference Wizard Manager will find the plug-in and call upon it (when
requested by the user) to edit the relevant third party preferences.
Copyright © 2003-2006 Adaptive Technology Resource Centre,
University of Toronto.
All rights reserved.
Last modified: Feb 20, 2006. Joseph Scheuhammer.