XmlAspect.org/Xml4jQuery

From ApiFusion
Revision as of 05:08, 30 May 2017 by Suns (talk | contribs) (Methods chaining)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

xml4jquery.com - project home.

Goal

To provide full and sufficient API stack for data to UI binding over jQuery plugin exposed via reactive asynchronous API.

Asynchronous API

While jQuery chain calls are synchronous, it is pretty attractive to make a chain calls to be just a scenario whether the each call does its stuff immediately or with a delay.

Methods chaining

Xml4jQuery calls converting jQuery list into sequence of Promise-s. The list will be executed in its sequential order. This way you could

  • initialize the jQuery list
  • put the loading UX into elements
  • load data
  • convert/massage data
  • transform (via XSLT or another templating engine ) into elements
  • finalize/clean up UX by cancelling loading UX animations

all in one jQuery methods chain:

$('.my-link')
.$on('click')
.addClass('loading')
.xmlTransform( dataUrl, templateUrl )
.removeClass('loading');

No need for embedded callbacks and closures on UI developer's end.

Promise

The sequencing of steps is made by Promise assigned to each step. It is accessible via .promise() available after any Xml4jQuery method called. The promise object could be resolved only once and it could be handy if you need to orchestrate different processes by Promise.all() or Promise.race()

Its .then() method invokes callback only once when the promise is resolved. It is a method of JS Promise object and returns another Promise breaking the jQuery and Xml4jQuery ability for call chaining.

Also the use of promise is limited to one time. Xml4jQuery gives alternative ability to execute the chain each time the source is ignited via .$then()

$on

Unlike jQuery .on() method .$on() returns asynchronous chain executed each time the matching event triggered.

$then

Unlike Promise .then() the method .$then() could be called multiple times on each chain ignition and returns asynchronous chain instead of Promise object.

Data and XML

The XML stack in UI covers the following set of operations:

  • Transform the data into text|DOM to be embedded into target UI.
  • Load data asynchronously from URL or browser's DOM on event
  • data search over XPath query

The *data* could be presented in either way:

  • JS object
  • XML document, Node, NodeList, Node array
  • URL with JSON
  • URL to one of types above
  • html form fields|widgets
$(".toFill").xmlTransform( $.Xml(dataUrl).XPath("//book[@genre='romance']"), $.Xml(xslUrl) );

XML API

  • Xml load data. Web service data type is auto-detected.
$.Xml( string url | object json | XML document | node )

Reactive API

Following methods return asynchronous Xml4jQuery chain. The optional callback argument receives the whole history of the chain execution results. I.e. the values returned by each chain callback or chain method result value.

$('.my-el')
.Xml( jsonUrl ) // collection of results starts from Xml4jQuery chain here
.$then( ( data, $el ) => val ) // last in list is the jQuery object and previous chain result(data)
.$then( ( val, data, $el )=>console.log( val,json, $el) ) // 3 previous results in reverse order
$(...).$on('click').$then( ( event, $el ) => val ).$then( ( val, event, $el ) => ... )
$(...).attr('disabled','disabled').sleep(1000).transform(...).removeAttr('disabled')


Promise API

returns Promise

  • .promise()
    var promise = $.Xml(...).promise().then( onOK, onFail );
    

Troubleshooting

The console log for reactive API and additional info about Promise is triggered by debug or test sub-string in URL.

Each Action( function call in the chain ) has a promise() method. Which in debug console could give you a Promise status and some debug attributes like method name or promise resolved value.