Formulierenserver Documentatie > Seneca XForms Engine > XForms Extensibility and Integration > Creating (jQuery-)enriched controls

Creating (jQuery-)enriched controls

Release 2.0 - ...

The XForms Engine uses HTML Render Devices to generate HTML markup for individual controls. The actual HTML rendered depends on the chosen Render Device. Custom Render Devices may be plugged into the architecture.

The built-in Render devices generate markup that you, as a front-end developer, can hook into. This is done using jQuery. The HTML render devices include references to jQuery plugins and enhancements.

XForms jQuery plugin

The jquery.xforms.js plugin is launched when the output of an XForms Document is rendered by the HTML Render Devices. This plugin hooks into form events, transfers state to the server using Json over Ajax, and raises events that enable subclassing of XForms functionality.

The jQuery custom events

XForms_Enrich Event

When attaching enrichments using progressive enhancement, the best way to attach to controls is to hook into the XForms_Enrich Event.

The following snippet attaches the jQuery UI datepicker to controls having the CSS class "ui-date-picker":

  CopyCode image Copy Code 
;(function ($) {
 $(function () {
  $("form.xforms-form").bind({
   XForms_Enrich : function (e) {
    if ($.fn.datepicker) {
     $("input.ui-date-picker", e.args.data).datepicker({
      dateFormat : dateFormat,
      changeMonth : true,
      changeYear : true,
      showWeek : true,
      firstDay : 1
     });
    }
   }
  })
 })
})(jQuery);

Enrichment Meta data

Some controls need some more context in order to be properly enriched. The range control, for instance, has step, start and end attributes that make sense to enriched controls to display properly.

In the example above, the datepicker is attached, but it uses its standard date formatting, which may be invalid in the current UI culture (the XForms Engine is fully culture-aware).

To allow the datepicker plugin to submit dates using the expected date formatting, the XForms Render Devices provide meta data to be used by clients, in a non-obtrusive way. Especially XHTML is very strict and doesn't allow custom attributes, unless in another namespace. This is why the meta data is provided in a different way:

  CopyCode image Copy Code 
$.xforms.getProperty(<jQuery selector object>, '<property>');

The example above can now be extended to use the proper date formatting:

  CopyCode image Copy Code 
;(function ($) {
 $(function () {
  $("form.xforms-form").bind({
   XForms_Enrich : function (e) {
    if ($.fn.datepicker) {
     $("input.ui-date-picker", e.args.data).each(function(){
      var inp=$(this);
      var dateFormat = $.xforms.getProperty(inp, 'dateFormat') || 'd-M-yy';
      dateFormat = dateFormat.replace('MM', 'mm').replace('M', 'm').replace('yyyy', 'yy');
      
      inp.datepicker({
       dateFormat : dateFormat,
       changeMonth : true,
       changeYear : true,
       showWeek : true,
       firstDay : 1
      })
     });
     $("#ui-datepicker-div").hide();
    }
   }
  })
 })
})(jQuery);


Meta Data currently exposed

  • date controls (input controls bound to date schema types)
    • dateFormat (string)
  • range controls
    • type (XmlTypeCode of the schema type)
    • step (type-dependent object)
    • start (type-dependent object)
    • end (type-dependent object)

 

Seneca XForms Engine