Settings Handler

From wiki.gpii
Jump to: navigation, search

Description

Settings Handlers are a type of Lifecycle Handler that are responsible for configuring the settings of an application, access feature, or assistive technology. They are often, but not always, specific to a particular platform. Platform-specific Settings Handlers typically interface with the operating system's built in APIs for storing settings (such as the Registry on Windows and GSettings on Linux). Others are capable of configuring standard formats such as XML and JSON files.

Settings Handlers are configured declaratively, and assistive technology developers will typically use the ones that are built in to the system. In cases where the default Settings Handlers aren't sufficient, developers can choose to write their own Settings Handlers and hook them into the GPII Personalization Framework.

Out of the box, the Cloud4all/GPII architecture ships with the following Settings Handlers:

Using Setting Handlers

Configuring Settings Handlers

Like the regular Lifecycle Handlers, the configuration of Settings Handlers for a solution happens in the Solution Registry where each solution is described. Most solutions will use one or more Settings Handlers is declared in an array indexed with "settingsHandlers" as follows:

<syntaxhighlight lang="javascript">

      "settingsHandlers": [
           {
               "type": "settings.handler.type",
               "options": {
                   (.. settingsHandler specific options here ..)
               },
               "capabilities": [
                   (.. array of what needs and preferences this solution can handle ..)
               ],
               "capabilitiesTransformations": {
                   (.. description of how application settings are transformed into common terms and vice versa ..)
               }
           }
       ],...

</syntaxhighlight>

As can be seen from the above structure, the "settingsHandlers" is an array, allowing several settingsHandlers to be declared. When the solution is launched, the Settings Handlers will be run in the order declared in the array. Each Settings Handler is configured declaratively by an object containing four key-value pairs, each of which are explained below:

  • "type": This declares what Settings Handler to be used. This is a unique and has to match the type of one of the implemented Settings Handlers. For example, to use the Windows Registry Settings Handler, the type would be "gpii.windows.registrySettingsHandler". For the other settings Handlers, please refer to their individual documentation, linked above.
  • "options": The content on this block depend entirely on the Settings Handler and amongst other typically contains information about how and where to locate the settings, by declaring a filename, a registry location, etc.. Each Settings Handler requires certain options to be set (in no way limited only to filenames, etc), again we refer to the documentation for each individual Settings Handler.
  • "capabilities" (required): This array tells what ontology terms the solution matches. Along with the capabilitiesTransformations block below, this information is used to help classify the solution in terms of it's capabilities and helps guide the matchmaker when scoring relevant solutions.
  • "capabilityTransformations" (optional): this blocks describes how common terms (from the Common Terms Registry) translates into settings understandable by the application. The structure of this object depends on the settingsHandler, but common for all capabilityTransformation objects is they can use the Transformer to make this transformation/translation between common terms and application settings. For the structure of this object, we refer to the individual documentation for each type of Settings Handler. For details on the transformations, see the Transformer documentation.

Triggering Settings Handlers

Settings handlers are included in the lifecycle management by the addition of the "setSettings" and "restoreSettings" keywords in the "lifecycleManager" block of a solutions declaration in the Solution Registry:

<syntaxhighlight lang="javascript">

       "lifecycleManager": {
           "start": [ 
               "setSettings"
           "stop": [ {
               "restoreSettings", 
           ]
       }

</syntaxhighlight>

Settings handlers can be combined with other lifecycle handlers: <syntaxhighlight lang="javascript">

       "lifecycleManager": {
           "start": [
               "setSettings",
               {
                   "type": "gpii.launch.exec",
                   "command": "gsettings set org.gnome.desktop.a11y.applications screen-magnifier-enabled true"
               }
           ],
           "stop": [
               {
                   "type": "gpii.launch.exec",
                   "command": "gsettings set org.gnome.desktop.a11y.applications screen-magnifier-enabled false"
               },
               "restoreSettings"
           ]
       }

</syntaxhighlight>

Examples

Now that we know what a settings handler is and the format it takes, let's see an example of how a settings handler might be configured for a solution in the Solution Registry. Note that the below is an example snippet from a longer solution declaration found in the Solution Registry.

The below block configures the GSettings Settings Handler, as can be seen from the type signature "gpii.gsettings.set". As can be seen on the GSettings Settings Handler page, it takes one key-value pair in the options block, namely a schema telling which gsettings schema to use. The capabilities block references a nested ontology term "display.screenEnhancement.screenMagnification". The "applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" is temporary due to a bug in the system.

The final capabilitiesTransformations block is a bit more complicated and we wont go into details with the content here. Suffice to say that describes three settings, namely mag-factor, show-cross-hairs and mouse-tracking. The first two get their values directly from the "display.screenEnhancement.magnification" and "display.screenEnhancement.showCrosshairs" as declared in the users Needs and Preferences Set. The mouse-tracking is assigned the result of a more complicated transformation based on the value the user has set for "display.screenEnhancement.tracking". For more information about these transformations, see the documentation on the Transformer

<syntaxhighlight lang="javascript">

      "settingsHandlers": [
           {
               "type": "gpii.gsettings.set",
               "options": {
                   "schema": "org.gnome.desktop.a11y.magnifier"
               },
               "capabilities": [
                   "display.screenEnhancement.screenMagnification.applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" 
               ],
               "capabilitiesTransformations": {
                   "mag-factor": "display.screenEnhancement.magnification",
                   "show-cross-hairs": "display.screenEnhancement.showCrosshairs",
                   "mouse-tracking": {
                       "expander": {
                           "type": "fluid.model.transform.valueMapper",
                           "inputPath": "display.screenEnhancement.tracking",
                           "options": {
                               "mouse": {
                                   "outputValue": "centered"
                               }
                           }
                       }
                   }
               }
           }
       ],

</syntaxhighlight>

Creating a new Settings Handler

Describe how to create a new settings handler TODO