XML Settings Handler

From wiki.gpii
Jump to: navigation, search

Description

The XML Settings Handler is one of several Settings Handlers available to the Cloud4All/GPII implementers when making their solution (application) compatible with the GPII. The XML Settings Handler is able to read and write XML files and works cross platform.

The focus of this page will be the specifics of the XML Settings Handlers, for more general information about how and where Settings Handlers are used, we refer to the Settings Handler Documentation.

Using the XML Settings Handler

Like all settings handlers, this one is used in the solution entries of the Solution Registry, describing how a particular solution configures the settings handler and what application settings are supported. Like all Settings Handlers, the XML Settings Handler is configured using four key-value pairs in each settings handler declaration, namely: type, options, capabilities and capabilitiesTransformations. For the XML Settings Handler, they are declared in the following way:

  • "type": This should always have the value "gpii.settingsHandlers.XMLHandler.set" when using the XML settings handler.
  • "options": The XML Settings Handler takes 3 options. "filename" should be a path to the XML file used by the solution. "encoding" tells the XML settings handler what encoding to use when reading/writing the XML file, and finally, "xml-tag" can be used to describe the XML version to be used. The value of the "xml-tage" will be printed in the beginning of the XML file.
  • "capabilities": This array tells what ontology terms the solution matches. This is not specific to the type of settings handler - we refer to the Settings Handler Documentation for more information.
  • "capabilityTransformations": As always, this blocks describes how common terms (from the Common Terms Registry) translates into settings understandable by the application. The indexes (keys) of this hash should match the gsettings keys to be set, and the values should be the Common Term that matches the gsettings key. Often the settings of an application might not entirely match that of a Common Term (eg. one might specify font size in pixels and the other one in points), for this type of transformations the Transformer is used - more information can be found here.

Below you can find an example of how the GSettings Settings Handler is used. For more information about Settings Handlers and the individual blocks described above, see this page. The capabilityTransformation block is simple in it's most basic form, but get rather complicated due the transformations. Information on what transformations are available and their syntax can be found on the Transformer page

Examples

Below is an example of usage. Note that the below is an example snippet from a longer solution declaration found in the Solution Registry.

As always, for GSettings Settings Handlers the type signature is "gpii.gsettings.set". The schema to be modified in the example is "org.gnome.desktop.a11y.magnifier" which contains the values related to the built in magnifier of Gnome Shell. The capabilities block declares that this solution covers the needs and preferences described by the nested ontology term "display.screenEnhancement.screenMagnification". The "applications.org\\.gnome\\.desktop\\.a11y\\.magnifier.name" is temporary due to a bug in the system.

The capabilitiesTransformations 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". If this user setting has the value "mouse", the "mouse-tracking" gsettings key will have the value "centered" assigned. For more information about the available transformations, see the documentation on the Transformer.

<syntaxhighlight lang="javascript">

       "settingsHandlers": [
           {
               "type": "gpii.settingsHandlers.XMLHandler.set",
               "options": {
                   "filename": "${{environment}.APPDATA}\\Texthelp Systems\\ReadAndWrite\\10\\RWSettings10.xml",
                   "encoding": "utf-8",
                   "xml-tag": "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
               },
               "capabilities": [
                   "languageAssistance.applications.com\\.texthelp\\.readWriteGold.name",
               ],
               "capabilitiesTransformations": {
                   "ApplicationSettings\\.AppBar\\.Width": "ApplicationSettings\\.AppBar\\.Width",
                   "ApplicationSettings\\.AppBar\\.ShowText": "ApplicationSettings\\.AppBar\\.ShowText",
                   "ApplicationSettings\\.AppBar\\.optToolbarShowText": "ApplicationSettings\\.AppBar\\.optToolbarShowText",
                   "ApplicationSettings\\.AppBar\\.LargeIcons": "ApplicationSettings\\.AppBar\\.LargeIcons",
                   "ApplicationSettings\\.AppBar\\.optToolbarLargeIcons": "ApplicationSettings\\.AppBar\\.optToolbarLargeIcons",
                   "ApplicationSettings\\.Speech\\.optSAPI5Speed": "ApplicationSettings\\.Speech\\.optSAPI5Speed",
                   "ApplicationSettings\\.Speech\\.optAutoUseScreenReading": "ApplicationSettings\\.Speech\\.optAutoUseScreenReading"
               }
           }
       ],

</syntaxhighlight>


Referencing XML in as a JSON path

Examples

<?xml version="1.0"?>
<Sociable.Launcher.Properties.Settings>
   <setting name="GameResources" serializeAs="String">
       <value>C:\Sociable\Games\Resources</value>
   </setting>
   <setting name="Resources" serializeAs="String">
       <value>C:\Sociable\Games\Resources\Launcher</value>
   </setting>
   <setting name="AutoLogin" serializeAs="String">
       <value>0</value>
   </setting>
</Sociable.Launcher.Properties.Settings>

Becomes:

{
   "Sociable.Launcher.Properties.Settings": {
       "setting": [
           {
               "name": "GameResources",
               "serializeAs": "String",
               "value": {
                   "$t": "C:\\Sociable\\Games\\Resources"
               }
           },
           {
               "name": "Resources",
               "serializeAs": "String",
               "value": {
                   "$t": "C:\\Sociable\\Games\\Resources\\Launcher"
               }
           },
           {
               "name": "AutoLogin",
               "serializeAs": "String",
               "value": {
                   "$t": "0"
               }
           }
       ]
   }
}