How to Write a Preference Wizard Plug-in

David Weinkauf and Joseph Scheuhammer
Adaptive Technology Resource Centre, University of Toronto

Introduction

Third Party Preferences

Plug-in Declaration

Plug-in Information

Preference Wizard Plug-in API

public interface ThirdPartyPrefsWizard
Multiple-type Adaptive Technology
Schema Extensions

Location of Code and Data
Summary

Introduction

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 <param> element which is defined as:



<element name = "param" type = "imsacclip:paramElementType"/>

<complexType name = "paramElementType">

    <complexContent>

        <extension base =
"imsacclip:attributeOnlyBaseType">

           
<attributeGroup ref = "imsacclip:attrParam"/>

        </extension>

    </complexContent>

</complexType>

<attributeGroup name = "attrParam">

    <attribute name = "name" use = "required" type =
"string"/>

    <attribute name = "value" type = "string"/>

</attributeGroup>

The third party preferences are children of the <application> element which is defined in the AccLIP as:

<complexType name = "applicationElementType">

    <sequence>

        <element ref =
"imsacclip:param" minOccurs = "0" maxOccurs = "unbounded"/>

        <any namespace = "##other"
processContents = "strict" minOccurs = "0" maxOccurs = "unbounded"/>

    </sequence>

    <attributeGroup ref =
"imsacclip:attrApplication"/>

</complexType>

<attributeGroup name = "attrApplication">

    <attribute name = "name" use = "required" type =
"string"/>

    <attribute name = "version" type = "string"/>

    <attribute name = "priority" use = "required"
type = "imsacclip:priorityType"/>

</attributeGroup>

Plug-in Declaration

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.

Plug-in Information

See the Plug-in Information section in the Configuration Plug-in documentation.

Preference Wizard Plug-in API

`public interface ThirdPartyPrefsWizard`

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 ca.utoronto.atrc.web4all.preferences.ThirdPartyPrefsWizard. This section declares the methods of ThirdPartyPrefsWizard and describes their intent. The methods of ThirdPartyPrefsWizard 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.

doPreferences()

public int doPreferences (Document io3rdPartyDoc, Locale inLocale);

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:

Document io3rdPartyDoc: This is an XML document containing all third party preferences for the application. The root element of the document is the <application> tag corresponding to the third party application. The <application> tag's children will be the enumeration of all the third party preferences consisting of <param> tag(s) with name and value attributes as specified in the AccLIP schema.
Locale inLocale: 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.

kill()

public void kill();: This method is called to dispose of any modal dialogs doPreferences() may have launched when it was called. This method is called if a user ends his/her Web-4-All session while doPreferences() is still executing.

Schema extensions

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 potentially multiple <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 question.

Location of Code and Data

See the Location of Code and Data section in the Configuration Plug-in documentation.

Summary

This document has described the essentials of creating a preferences plug-in for the Web-4-All system. If the properties file and ThirdPartyPrefsWizard 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.