====== XDHTML ======

<note>This is about about a set of //C++// libraries for developing web, desktop and, in the future, mobile interfaces. If you are looking for bindings to this libraries, you will find them at http://atlastk.org/ </note>

===== Introduction =====

//XDHTML// is a technology currently under development. Its goal is to provide a way to develop user interfaces which combines //HTML// and, instead of JavaScript which is usually used with //HTML//, the //C++// language.

Its purpose is also to provide an easy way to customize the user interface without, as far as possible, writing a single line of //C++//, or even //JavaScript//.\\
To reach this goal, besides the way the //HTML// code is generated, some extra tags and attributes are used. To follow the //HTML// specifications, extra tags are prefixed with ''xdh-'', and extra attributes with ''data-xdh-''.

The [[computing:epeios:apps:mmuaq:|Epeios Meta Mail User Agent]] implements this technology and acts as //proof of concept//. As this concepts are not yet fully validated, you will not find a detailed documentation about the //XDHTML// technology, but you can refer to this application as an example of the below described concepts.

===== Configuration =====

The //XDHTML// module configuration file has a name which looks like : ''//<app_name>//xdh.xcfg'', where ''//<app_name>//'' is the application's name.

==== XDHTML module ====

The //XDHTML// related tools (currently //[[/computing/epeios/tools/xdhcefq/]]// and //[[/computing/epeios/tools/xdhbrwq/]]//) have a ''Parameters'' section's ''ModuleFilename'' entry which had to be set to the path and file name of the //xdhtml// module (a specially designed dynamic library). More about this can generally be found in the documentation of each application.

==== XSL root dir ====

At the beginning of the configuration file, there is a section which looks like :

<code xml>
<xpp:define name="XSLRootDir">
 <xpp:bloc>
  <xpp:expand select="XSLRootDirHeader"/>
  <xpp:bloc>epeios/apps/xdhdq/frontend/XDHTML/XSL/</xpp:bloc>
 </xpp:bloc>
</xpp:define>
</code>

Replace what is between the most inner ''<xpp:bloc>'' tag by the __absolute__ path to the XSL root directory of the package (with a final ''/''). It should then look like :

<code xml>
<xpp:define name="XSLRootDir">
 <xpp:bloc>ABSOLUTE_PATH_TO/APP_NAME-sources/frontend/XDHTML/XSL/</xpp:bloc>
</xpp:define>
</code>

where ''//ABSOLUTE_PATH_TO//'' is the absolute path of where you decompress the package, and ''//APP_NAME//'' the application's name.
==== Other ====

This tools may also have a ''Definitions'' section, and particularly a ''Definitions/Scripts'' section and a ''Definitions/CustomItems'' section in their configuration file. Don't modify this sections unless you really know what you are doing.


===== Features =====


==== Generation of the interface component in HTML ====

The //HTML// code for the interface components is not directly generated by the application. Instead, the application generates an //XML// tree, which contains relevant data from the application. The //HTML// is generated by an //XSL// transformation, following rules given in a //XSL// file written by the user. This allows, when used with other //HTML// related technology as //CSS//, to generate a fully customizable interface.\\
The //XSL// files to use to generated this //HTML// code are defined in the application configuration file.

Before be used for the //XSL// transformation, //XSL// files are processed by the //[[/computing/epeios/tools/xppq/|XML preprocessor]]//, so you can use its directives. Also, all text between a ''#'' marker is considered as an identifier of a text to be translated and replaced (including the ''#'') by the translation. The translations are defined in the ''Locale'' section of the application's configuration file. Two ''#'' (''%%##%%'') are replaced by a single one (''#'').

==== Handling of the 'accessibility' of the interface components ====

The //accessibility// of a component (the fact it has attributes like ''hidden'', ''disabled''... set or not) is handled through a set of extra tags and attributes.

One of this extra attribute is ''data-xdh-cast'' and its value refers to an //id// of a ''xdh-cast'' tag. This tags have an ''kind'' attribute with one of, for example, following values  :
  * ''Hide'' : elements which refer through its ''data-xdh-cast'' attribute to a ''xdh-cast'' element with a ''kind'' attribute of this value are hidden,
  * ''Disable'' : elements which refer through its ''data-xdh-cast'' attribute to a ''xdh-cast'' element with a ''kind'' attribute of this value are disabled,
  * ''Vanish'' : a ''fieldset'' element which refers through its ''data-xdh-cast'' attribute to a ''xdh-cast'' element with a ''kind'' attribute of this value is hidden, but its content remains visible, unlike what would happen if the ''hidden''  attribute of a ''fieldset'' element would simply be set to ''true'',
  * ''Plain'' : elements which refer through its ''data-xdh-cast'' attribute to a ''xdh-cast'' element with a ''kind'' attribute of this value becomes visible and enabled.

The ''data-xdh-cast'' attribute are set by the user during the HTML generation described in previous paragraph. The ''xdh-cast'' elements are generated by a //XSL// transformation on a //XML// tree generated by the application which contains relevant informations about the application's context, and a user-written //XSL// file, defined in the configuration file. This gives to the user full control over element's accessibility.


==== Event handling ====

The event handler are defined through extra attributes : ''data-xdh-onevent'' to define one event handler, and ''data-xdh-onevents'' (with a tailing ''s'') to define more the one event handlers. An event handler, called an action, is a //C++// callback with a unique identifier. The ''data-xdh-event(s)'' contains the event (''mouseleave'', ''click''...), and the identifier of the action to associate to this event. The event can be omitted, than the default event is used (it's generally the ''click'' event).

There exist special predefined actions, such the opening of a file selector. Parameters used by this actions (such, for example, the default file, or the extensions of the files to be displayed in the selector) can also be added.

==== HTML UI component and JQuery ====

There are numerous //HTML// UI components which are based on //JQuery//. They are usually instantiated by applying to a //HTML// element some //JavaScript// code, which is roughly always the same, with parameters which are specific to each component.

To avoid to write this //JavaScript// code, you can set, for the element concerned by this //JavaScript// code, an attribute called ''data-xdh-widget'' with, for value, simply the component name, and its specific parameters.

==== Links ====

If there is a ''<a href="...">...</a>'' in the //HTML// code, the link is automatically be opened in another window, even without the ''target'' attribute, so you can easily return in the application.

===== Third party JS components =====

To improve the interface, you can use some third party JS components. As example, following components are provided :

  * [[http://ckeditor.com/|CKEditor]] ([[http://ckeditor.com/about/license|license]]),
  * [[http://github.com/eternicode/bootstrap-datepicker|bootstrap-datepicker]] ([[http://github.com/eternicode/bootstrap-datepicker/blob/master/LICENSE|license]]),
  * [[http://interactjs.io/|interact.js]] ([[http://github.com/taye/interact.js/blob/master/LICENSE|license]]),
  * [[http://jqueryte.com/|jQuery TE]] ([[http://jqueryte.com/license|license]]),
  * [[http://github.com/KevinSheedy/jquery.alphanum|JQuery Alphanum]] ([[http://github.com/KevinSheedy/jquery.alphanum/blob/master/MIT-LICENSE.txt|license]]),
  * [[http://jqueryui.com/|jQuery UI]] ([[http://github.com/jquery/jquery-ui/blob/master/LICENSE.txt|license]]),
  * [[http://rubaxa.github.io/Sortable/|Sortable]] ([[http://github.com/RubaXa/Sortable/blob/master/README.md#mit-license|license]]),
  * [[http://jonthornton.github.io/jquery-timepicker/|jquery.timepicker]] ([[http://github.com/jonthornton/jquery-timepicker/blob/master/jquery.timepicker.js|license]]),
  * [[http://touchpunch.furf.com/|jQuery UI Touch Punch]] ([[http://github.com/furf/jquery-ui-touch-punch/blob/master/jquery.ui.touch-punch.js|license]]),
  * [[http://stefangabos.ro/jquery/zebra-dialog/|Zebra_Dialog]] ([[http://github.com/stefangabos/Zebra_Dialog/blob/master/license.txt|license]]),
  * [[http://jquery.com/|jQuery]] ([[http://github.com/jquery/jquery/blob/master/LICENSE.txt|license]]).
  * [[http://www.javascripttoolbox.com/lib/mktree/|mktree]] ([[http://www.javascripttoolbox.com/lib/mktree/source.php|license]]).