XML Plug-in options

From ColourWiki

Simple Toolkit Abstraction is the name of a project idea on the GSoC2008 OpenICC page. Its goal is to provide a simple way for plug-ins and CMM's to describe options and have some slightly control over its presentation layout. Jon A. Cruz gave some helpful suggestions on what to focus on this area.

Table of contents

Architecture

The dataflow could be something like this:

XFORMS + XML -> xslt -> toolkit XML -> native toolkit widgets

XForms and HTML elements need to be supported for the UI definition. The idea is to have as less layout code there as possible and let the UI engine decide how to display. The plug-ins should be able to expose the grouping of their options, their type and icons, labels and so on. To automate processing, some default options need to be specified on Oyranos side.

Who is who:

key handlers (Elektra) <------> XFORMS interpreters
                ^                   ^
                 \                 /
                  v               v
                   plug-in (hooks)

Key Values pairs are stored in Elektra.

XFORMS interpreters are selectable libraries to provide widgets or entire dialog windows for drawing the UI content. They draw XFORMS documents with toolkit widgets.

Plug-ins register not only key, they provide a UI description for those keys and helpers to handle the key manipulations in a GUI.


Which details should be take care of?

  • key names or registration strings, which map to Elektra paths and the XFORMS data model
    • e.g. "colour/oyranos.org/colour_icc/lcms/preserve_black" (should be suficient for Elektra)
  • i18n for widget labels and tooltips translation
    • possibly through gettext or by dynamic XFORMS code generation, where this can be done by plug-in code on the fly
  • UI backends (toollkits) deploy xslt conversions to their native xml UI representation
  • event handling
    • plug-in side hook to verify user input
    • it is unclear to me whether XFORMS evaluation (http://www.w3.org/TR/xforms/#expr-lib) is sufficient
    • hooks to talk back to plug-in
    • according UI refreshing
  • UI generation
    • plug-in side generator of new UI document part
    • hook to allow for fetching external data (ICC profiles from disk, device informations from services, ...)
  • differentiated representations and their conversions:
    • in memory C struct
    • permanent disk storage
    • XML/XFORMS de-/serialisation


  • Oyranos backend API's mapping (CMM need images, profiles and options, filters want images + options?)
    • For backends common dynamic resources should be handled elsewhere. Would'nt it be useful to register through a specialised module key word handlers? The key words can then be used to place specific resources into the UI.

Requirements

  • based on W3C technology (Xforms, Dom ...)
  • slim XML footprint
  • callback mechanism (possibly to pass the changed serialised widget layout, like a diff, to the callback)
  • callback as C function or CTL for portability?
  • easy separation of layout (widgets) from data (options)
    • should work fairly good with XForms
    • a form is required on how to present the Oyranos options in XFORMS and an easy way to convert between both.
  • widget set: tabs, groups, lists, choice list, sliders (range), buttons, check button, radio button, text box, drawing area
    • there shouldnt be a problem using interactive and non-interactive widgets using AJAX technology
    • screenshots / forms selection
      • currently I am exploring processors:
      • Firefox 2 + 3 (https://addons.mozilla.org/de/firefox/addon/824) 2.0.0.13 with XForms-v0.8.5 does with a xforms.xhtml (not *.html)
      • Orbeon (http://www.orbeon.com) looks nice but seems rather big and needs a local tomcat compilation
  • select one widget per group for scaling; place this widget at top, bottom, right, left, centered or to fill as specified
  • serialise and deserialise from Oyranos C struct oyOption_s to XML/XForms and back
  • support console applications
  • converters for at least Qt, Gtk, FLTK ...
  • XML data models will be made by using XML_Schema (W3C).
  • simple XForms subset example (http://www.oyranos.org/scm?p=oyranos.git;a=blob_plain;f=doc/oforms-example.xhtml)

RFC

Key value pairs are stored in namespaces in Elektra expressed by paths. This proposal covers how to represent them to users.

A user can select a namespace and a viewer conforming to this RFC is required to render the content according to the UI description found in the Elektra key namespace. A document applies to all children of a node, except a child node tree has own UI descriptions. Then these take precedence.

The key xforms_ui has a special meaning. It contains the render descriptions expressed in a XFORMS syntax subset. The actual xforms model is extracted from the keys in the actual path level.

<ns_A>
  <ns_A_1>
    <ns_A_1_1>
      <key name="xforms_ui">...</key>
      <key name="my_key1">value1</key>
    </ns_A_1_1>
  </ns_A_1>
</ns_A>

A

To allow for hooks the XFORMS ui part is integrated as keywords like:

<xf:choices label="Editing RGB">
  <elui:choices:oyranos-profiles vars="" args="--elui" cspace="Rgb" class="prtr,mntr,scnr"/>
</xf:choices>

elui:choices: indicates a namespace in the sense of this RFC. elui represents the abbreviated elektra_ui. The following command oyranos-profiles will be executed with the attributes appended. The args attribute shall be given without the args= part and without quotes. The content of vars= will be set in the environment of the call.

$ oyranos-profiles --elui cspace="Rgb" class="prtr,mntr,scnr"

The returned text will be parsed. The first element shall be a number indicating how many items are to be expected. in to value pairs and will be expanded to label and value items. See the following example:

<xf:choices label="Editing RGB">
 <xf:item>
   <xf:label>sRGB.icc</xf:label>
   <xf:value>/usr/local/share/color/icc/sRGB.icc</xf:value>
 </xf:item>
 <xf:item>
   <xf:label>eciRGB_v2.icc</xf:label>
   <xf:value>~/local/share/color/icc/eciRGB_v2.icc</xf:value>
 </xf:item>
</xf:choices>

I18N:

An other keyword is elui:i18n:. It tells about the to be used translation programm and the namespace.

<elui:i18n:gettext vars="TEXTDOMAINDIR=/usr/local/share/locale;TEXTDOMAIN=oyranos" args="-n %label%"/>

expands to:

$ TEXTDOMAINDIR=/usr/local/share/locale TEXTDOMAIN=oyranos gettext -n %translate%

The actual text will be set at runtime for the %translate% string. Translated will be any kinds of labels and hint elements. Not so for values.

B

Alternatively a system could be though of to call a updater, which writes a complete XFORMS document in the current locale. This would as well solve the I18N issues:

<elui:init:oyranos-devices vars="" args="--scanner --xforms-ui"/>

... will create a XFORMS document with all choices in place:

$ oyranos-devices --scanner --xforms-ui
<elui:update:oyranos-devices vars="" args="--scanner --xforms-ui --evaluate-file=%update%"/>
$ oyranos-devices --scanner --xforms-ui --evaluate-file=temp_file_name.xforms


TODO:

How to work within non cli environments?

Strategy on how to handle consitency ...

How to deliver results without storing persitently in Elektra? Just return the model part containing the changed keys?

  • build UI from elui:xforms_ui and other keys
  • update UI to user interaction
  • applying a return or Ok style button returns XFORMS model changes to the caller
  • optionally read the model into the Elektra db or process otherwise

References