jquerymy.js ‹{}›

Guide and API v1.2.14

Press Ctrl-F or ⌘-F to search the guide. To start without reading, explore demos. You can use cloudwall.me built-in IDE for authoring $.my apps and forms. 

Basic concepts

jquerymy is a plugin, not a framework. $.my works in browser and runs browser side of a webapp. $.my does not include router, net functions, auth and security functions and so on. Use your best-loved solutions for that tasks, $.my does not dictate.

One app – one object. Any $.my app, its behavior and facade, is defined using single standard javascript object, hereafter manifest. ‘Standard’ means you need not learn new syntax rules or list of directives. All plugins are applied using their standard APIs, all code is good old-fashion javascript.

Extension-friendly. jQuery.my understands a lot of rich-ui plugins out of the box, and can be extended to understand new solutions.

JSON-friendly. $.my manifests are JSONable and though are very well suited for modern noSQL DBs. One doc – one app, no additional files or resources. Also since apps are JSONs, they can be manipulated as JSON. 

Recursive. Any instance of $.my form can act as a single control for another form, it allows developers to create complex composite apps. Child manifests are included as properties of a parent manifest.

Robust. $.my is IE11+ compatible and fault-tolerant: when child form or any control fails, its parent form stays more or less operational.

Quick start

jQuery.my requires Sugar.js 1.4~ (not 1.5 or 2.x) and jQuery.js 2.0+ preloaded. You can use CDNJS repo for all required components:

xxxxxxxxxx
 
<script src="https://cdnjs.cloudflare.com/ajax/libs/sugar/1.4.1/sugar.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jQuery.my/1.2.11/jquerymy.min.js"></script>
xxxxxxxxxx
 
// Place your javascript here
xxxxxxxxxx
 
/* Container for CSS code */

$.my forms are initialized and managed during runtime according to jQuery standard  recommendations for plugins.

General syntax is $(DOM_node).my("command", param1, param2). If no command passed $.my assumes "init" requested. 

To create a form

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
// Source data
var person={ 
  name: "Ann", 
  metrics:{ age:"25" } 
};
// Manifest
var manifest = {
  
  //Default data  
  data: { name:"", metrics:{ age:"" }},
  
  // Init function  
  init: function ($node, runtime) {
    $node.html(
      '<h4>Simplest form</h4>'+
      '<div><input id="name" type="text" placeholder="Name"/></div>' +
      '<div><input id="age" type="number" placeholder="Age"/></div>'
    );
  },
  
  // Bindings
  ui: {
    "#name": { bind: "name" },
    "#age" : { bind: "metrics.age" }
  }
};
// Init $.my over DOM node
$("#form").my( manifest, person );
xxxxxxxxxx
 
/* Container for CSS code */

Above code generates this form:

Properties of person variable reflect states of two HTML controls. When control receive input, person is mutated.

Bindings like "metrics.age" are just syntax sugar. Strings "arrayName.3" to bind with an array rows are ok.

Variable manifest, the first argument for $.my invocation, defines form facade and bindings. Second argument, variable person, is data object form is bound to.

Getting form’s data

$("#form").my("data") returns a reference to dynamically updated object, bound to UI controls. When data is updated, change event is fired on form’s DOM node. Generally, object returned is ‘classic’ javascript object and is any-time serializable.

Setting form’s data

$("#form").my("data", { /* Data */ }) applied to running form updates its data and UI. Data received is merged deep with form’s data – so update can be partial. For above example $("#form").my("data", {name:"John"}) changes only name.

If data is external variable (like person in above example), external update of the var would not raise form update automatically. You must call $("#form").my("redraw") explicitly to make form know that data was updated.

Manifest structure

Manifest is a standard javascript object, that has some reserved properties and can have unlimited number of custom keys. Reserved property names are (in AZ order):

  • data Default data object
  • die Function called on form disband, with same arguments as init
  • expose Obj, array or string, list of nodes allowed to be inherited by successors
  • files CouchDB-style object with base64-encoded binary resources inlined. Resources obtain session URL when the form starts.
  • id String, unique identifier of the manifest, autogenerated if omitted
  • inherit Obj, array or string, list of manifest nodes to inherit from parent
  • init Function, called just before building bindings
  • lang Localization dicts
  • my Non-enumerable object, container of $.my app runtime methods, attached to manifest during form start.
  • params Object, defines form’s settings
  • radio Obj, array or string – radio relay object
  • require Array, list of resources required to start the form
  • style Object, defines CSS rules local for the form
  • ui Required property, defines bindings between DOM and data. Object, each key is a valid jQuery selector of form’s control. Value under each key defines control section for DOM element that matches a key.
Custom properties of a manifest, if any, better have Capitalized or camelCase keys to ensure no conflict with future versions of $.my. 

Binding data to a control

The ui object of a manifest assumed to be a flat key/value dict. Each key is jQuery selector and each value is a control section for the DOM node, that matches the selector.

Property bind of a control section should be a string reference or a function. 

  • If a string, bind assumed to be a dot-notation reference, pointing to the branch of form’s data object, or, if defined as "this.SomeKey", the branch of the runtime manifest.
  • If a function, bind is called any time control receives input or when $.my forced the control to update. The bind function receives three arguments: (dataObj, newValue, $control)

dataObj is a reference to form’s data object. It‘s important to keep data object anytime serializable to JSON.

If newValue is null, function must return value to put into the control. If not null – binder function must store newValue into appropriate branch of dataObj and may return new/updated value for the control.

So bind function acts like both getter and setter. The above example can be rewritten:

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
$("#form").my({
  ui:{
    "#name": "name",
    "#age" : {
      bind: function (data, value, $control) {
        var dm = data.metrics;
        if (value != null) dm.age = value; 
        return dm.age =  (dm.age + "").replace(/\D/g,"");
      }
    }
  }
}, person);
xxxxxxxxxx
 
/* Container for CSS code */

This example makes impossible to put anything but number into #age input. Depressing any non-num key makes no visible sense – non-nums are stripped immediately.

 Third argument, $control, is deprecated and will be probably removed in $.my 2.0. Use proxies like this.my.method instead. 

Third argument, $control, is a jQuery object of DOM control being processed. It has several extension properties and can be useful for navigation over form’s DOM tree. $control.my("find", "#name") returns #name control from inside the form, as jQuery object.

Also bind function receives this, referring to runtime version of form’s manifest.

Dependencies

Dependencies are defined using watch and/or recalc properties. 

Both watch and recalc are shown. Syntax watch: "#num2, #num3" means ‘When #num2 or #num3 changed, update me’. Syntax recalc: "#product" means ‘When I was changed, update #product’.

If both external recalc and own watch are defined for a control, recalc run first.

Loop dependencies

Controls can be cross-dependent. They even can be looped in dependency rings of 3+ more controls:

To keep recalc graph manageable, default dependency resolution depth is 2. Value can be increased for deep dependency trees or long loops using recalcDepth property, that can be defined for any particular control.

Tuning bind events

By default, $.my tracks control’s events, that might indicate control’s update most frequently. But we may need less frequent updates. For example we may need data to be updated when textarea is blurred, not on every key press.

Events that trigger control’s update, are defined using events property. It’s a string or an array of strings. 

To ensure event listeners unbind when form is removed use .my namespace postfix for event types.

Delayed bind

Some controls raise update events very frequently. Binding on every single update can take excessive amounts of CPU and RAM. The delay property defines minimum gap between subsequent bind calls. If there is a series of events all raised in gaps smaller then delay, only last event invokes bind, other are suppressed. 

When control is rebuilt during dependency recalc, its bind is executed without any delay, in sync.

Update on pub/sub event

Control can be updated on pub/sub event. For example we received new items and need list of them to be redrawn. Pub/sub events reaction is defined in listen property:

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
({
  List:[],
  ui:{
    "#filter":{
      bind: function(){ /* We (re)build list here */},
      
      listen:{
        // Here we listen to /list and /item channels
        "/list": true,
        "/item": function(data, message, $ctrl){
          if (message && message.doctype == "item") return true;
        },
      }
    },
    "#list":{
      bind:"this.List",
      watch:"#filter",  // Watch for filter changes
      manifest: { /* Here goes list item manifest */ }
    }
  }
})
xxxxxxxxxx
 
/* Container for CSS code */

This control #filter is redrawn when /list channel receives any message or when /item channel receives appropriate doctype. We assume that #filter rebuilds list of items, and then #list is redrawn.

Messages can be transmitted using $.my.radio(channel, msg) for global broadcast or using $ctrl.trigger("radio", {channel:"channelName", message:msg}) for realm-controllable broadcast.

Validation

There are three possible ways of validation. Validator can be defined in manifest or using control’s HTML5 markup. In-manifest controls‘ validators are functions or regexps.

Regexp validation can only indicate the fact of mismatch, message is predefined in the manifest (error property of control‘s ui section). 

Validator function can return custom error message, that varies depending on conditions that were not met.

Validation takes place just before bind call. When validation fails, closest DOM container of the control receives class .my-error. Then $.my looks for an element with class .my-error-tip within this container, makes it visible and puts error message inside. If no element found, title attribute of the control receives the message. 

For non-interactive controls (<div> bound to data, for example) .my-error class is applied to element itself, not to its container.

Regexp validation

If the #name input element has less then 3 chars, container receives class .my-error.

.my-error-tip receives validator message, so to make message visible there must be an element with my-error-tip class inside control’s container. 

Validation with function

Validator check receives same arguments as bind, but is executed before bind. Unlike bind, check is never called with value === null.

Entire form validity

$("#formObj").my("valid") returns true if all form’s controls are valid, and false otherwise.

$("#formObj").my("errors") returns object, each key of that is control’s selector, and value is error message. If object returned has no keys, form is valid. Child forms’ error objects are attached under selectors the child was bind to parent form.

Object returned after $control.my().errors call from inside bind function, is nearly the same, but can contain empty string values (it means control under key-selector is valid).

Conditional formatting

Allows different CSS rules to be applied over control’s container when conditions are met. Condition is a regexp or a function. There exists special key :disabled, that disables control when its condition is met.

Conditional formatting is applied after check and bind. To apply rule to control itself, not container, prefix self: must be added to a rule key. Rule "self:red":function(){...}  is applied to control, not to its container.

Local CSS rules

CSS classes .Red and .Green of above example are defined locally using style property of the manifest. Those classes are translated into runtime CSS rules, which are applicable only to form’s inside – so different forms don’t interfere. One form can have class .Green that is yellowish, and other – that is olive. They both are local.

When form starts, $.my creates unique <style> tag in current document, and puts compiled CSS rules inside. To avoid <style> dupes for every instance of a form, form’s manifest must have id property. 

Note leading spaces in keys. Spaces needed when key hierarchy is concatenated to produce rule.  " .Red" + " input" become something like

.my-manifest-1ftwlphd .Red input {background-color: #FCC; color: #C02;}.

Rules can be defined as functions:

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
style:{
  " .item": function ($form, runtime) {
    if ($form.width()<500) return "display:none";
    return {
      " p": "font-size:80%",
      " a": "color: blue"
    };
  }
}
xxxxxxxxxx
 
/* Container for CSS code */

When a rule is defined as a function, it is calculated on start, just before init function runs. 

Also function-defined custom rules can be recalculated each time window obj receives resize event. The property restyle of params section of manifest defines delay between resize event and style recalc. By default (value is -1) no restyle wired on resize – it can be costly. 

The above example evaluates form width and returns different CSS rules if the form is wider than 500px.

New <style> element is created for every single instance of a manifest with function-defined styles.

Form init

Every control’s bind section and entire manifest can have init property, that is function.

All those functions run once when form starts, can be async and are useful for remote data retrieval, rendering HTML, applying rich ui plugins to controls and so on. 

Any init function can return promise. Init assumed completed when promise is resolved. If returned value is not a promise, init assumed completed immediately.

Code below builds HTML skeleton, loads external data and builds <select> control, applies plugin to it and then fades the form in. 

Note how code that fades the form in is subscribed to form init successful finish. 

Init function is invoked after manifest properties inheritrequire, files and style are successfully processed (if any). So when init starts, all resources are loaded, files have session URLs and styles are calculated and applied to form.

Note that radio section and though pub/sub events are not processed unil entire form starts.

Runtime: this and this.my objects

Every manifest‘s function sees own parent manifest via this. Custom form functions of the first level of manifest‘s object, if any, are also bound to manifest as this during form start.

Actually, runtime version of a manifest is, in general, slightly different from original, passed for app init. Some properties, written in shorthanded form, are unfolded, some string references are resolved and so on. These differences are insignificant in most cases although.

Runtime as data store

Manifest runtime object is not sealed or frozen. It means internal app functions can use this to store intermediate results, that are not intended to live in main data section. 

Any form control can be also bound not only to childs of the data section, but to this-hosted data – just use bind:"this.MyProperty" syntax. Data sections, that are childs of this, are not restricted to be anytime-serializable, as the main data section. They can have circular references, DOM objects and so on. 

this.my methods

Since 1.2.0 any form‘s manifest receives additional non-enumerable property my, that proxies several useful runtime methods. They are visible from inside manifest functions as:

this.my.root()

Returns jQuery object of form‘s root DOM node.

this.my.indom()

Returns true if form‘r root is in document DOM (form was not removed).

this.my.parent()

Returns runtime manifest object of the parent form, if any. ‘Parent’ here means the first DOM ancestor with .my-form class.

this.my.ajax( obj )

Ajax call, by default uses standard jQuery syntax, returns jQuery promise.

this.my.cancel(), this.my.commit()

Triggers commit or cancel event on form‘s root. 

this.my.index()

For children forms in lists returns zero-based index of a form in parent list.

this.my.insert("#node", where, obj)

Inserts element in a list of forms under jQuery selector. If selector is omitted, insertion is performed on the first ancestor of the form‘s root (allows insert call from inside list elements). 

The where argument is a number or a string, position to insert. Strings "before" and "after" are allowed for insert calls from inside of other list elements.

Argument obj is an object to insert.

this.my.check("#node"), this.my.recalc("#node")

Triggers check or recalc events on a control for a given jQuery selector. Looks up a control only inside the form.

this.my.trigger("#node", "event")

Triggers given event on form‘s child.

this.my.modal("#node", obj)

Opens modal dialog, pivotted to "#node" DOM object. Returns dialog‘s promise. All child dialogs are automatically closed on parent form‘s disband.

Other this.my methods available are listed at External commands section, since they are mirroring appropriate commands.

Nested forms

Any $.my form can act as a control for other embracing $.my form – forms can be nested. Set of repeated child form bound to an array of data are also supported. Moreover, array can consist of different-typed items – and list can render different child forms for them.

When nested form is bound as a control, bind property must be a string. If bind points to an object, single child form is applied. If bind points to an array, list of repeated forms is built.

Single child form

Child forms’ init functions can be async if they return a promise. In this case list start (and parent form binding) assumed successful when all promises are resolved. 

Repeated child form

If bind property of a selector points to an array and there is manifest property, $.my builds repeated list of child forms. Each form by default lives in container <div></div>. To change container type or attributes, define container HTML in list property.

Insertion/deletion are event-driven. To delete row any control from inside the row must trigger remove event or this event can be fired over child form’s container.

Event insert must be triggered to insert row. Insertion supports additional argument, that defines what to insert and where. $control.trigger ("insert", param). Param is a string or an object:

  • "before" inserts empty row before caller row
  • "after" inserts row after
  • {where: "before" | "after" | index, what: ObjToInsert} – inserts ObjToInsert. If where property is a number, object is inserted into this index. Sparse arrays are not supported, so {where:1e6} inserts row at the end of the list.

List of different forms

Sometimes data array consists of different-typed items that require different manifests to render. To allow runtime selection, manifest property of a control section can contain a function. It receives each data item during runtime and must return suitable manifest.

Property stamp or equivalent is required to differentiate items. 

Dynamic lists functionality allows to build very complex ensembles of applications.

Identifying child forms

Control section, describing list of child forms, may have id and/or hash properties. Each can be a function, a string or an array of strings.

id function receives item and it’s index as arguments and must return unique item’s id. When id is a string, it’s assumed to be a pointer inside child form’s data object. If an array – list of pointers (values are concatenated).

hash function receives same args, but must return unique hash, that changes when any significant item’s property is changed. In general if hash of child form’s data changed, the form is redrawn. 

When no id or hash defined, sdbm code hash function from BerkeleyDB codebase is used.

Merging new data

If list‘s underlying array with data is modified externally, list must be rebuilt. There are two strategies of combining new and old (already rendered) data:

  • kill all forms with old data and re-init new child forms,
  • try to extend already existing forms if their data rows just slightly changed.

Ui section for a list can have property merge, with values true, false of function (oldObj, newObj){ }

Property omitted or false value turns on standard behavior – if new object received, new form is always created and this form is bound to new object.

If merge:true, new data is overlapped over old if row was already rendered. Overlapping is like deep merge, exept arrays, that are taken from new obj entirely.

If a function given, it must modify oldObj, that is 1st arg, using data from newObj

Inherit and expose sections

Sections inherit and expose manage what properties will manifest inherit from callee or root, or expose to child attached.

Property expose restricts properties, that can be inherited by childs from current form. If no expose defined, child forms can inherit any property of parent’s runtime.

Property inherit defines, what properties must be inherited form parent.

Both properties can be comma-separated strings or arrays of strings.

Require section

require property of a manifest defines a) external resources to load before form starts, b) local plugins required for a form to run.

require section is an array of groups, each group is processed after previous one finished successfully.

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
({
  require:[
    // First group
    {
      // Checks if select2 plugin loaded –
      // window.$.fn.select2 isn’t undefined –
      // and loads it if necessery
      "$.fn.select2": "http://some.url/select2.js",
      
      // Same here, but for manifest property Dict,
      // and with extended params defined
      "this.Dict" :{
        url: "http://some.url/some.json",
        dataType: "json"
      }
    },
    
    // Second group, executed after all 
    // resources of the first group are loaded
    {
      // some keys with urls as values
    }
  ],
  init: function(){ /* ... */ },
  ui:{ /* ... */ }
})
xxxxxxxxxx
 
/* Container for CSS code */

All these checks and preloads are executed before any other form’s function run.

Inlined resources

$.my allows to include binary resources into manifest as base64-encoded strings. Section files of a manifest is a container for them. 

All entries of the files section are processed during form start and each obtain local session URL. Files become accessible from <img src= or in links. 

After form’s start session URLs are accessible as this.files["fname.ext"].url from inside of any function.

files section has structure very similar to CouchDB’s _attachments section of a document. 

Settings

App instance params

There are several runtime settings, that has global defaults, but can be overridden using params property of a manifest.

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
var manifest = { 
  data:    { /* data section */ },
  ui:      { /* ui section */ },
  init:   function ( $form ){ /* init */ },
  // Manifest settings
  params:  { 
    container:function ($control) {/**/}, // Container getter, returns $ obj
    change: function ($form){},           // Change handler
    recalcDepth:2,                        // Depth of dependencies resolver tree
    delay:0,                              // Delay of bind invocation, ms
    strict:false,                         // If true form assumed unjsonned
    errorTip:".my-error-tip",             // $ selector of err tip container
    errorCss:"my-error",                  // Class applied to container on err
    pendingCss:"my-form-pending",         // Class applied when form starts
    remember:0,                           // Undo steps to remember
    historyDelay:100                      // Min history steps gap, ms
    restyle:-1                            // Custom styles recalc delay on window.resize
    locale:'en'                           // Locale for l10n using .lang dict
  }
}
xxxxxxxxxx
 
/* Container for CSS code */

recalcDepth and delay properties can be also set for a selector’s control section.

Localization

Each manifest can have lang section, that must be i18n dictionary of below structure:

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
{
  // en section must always be present
  // and must always have all necessery keys 
  en:{
    TITLE_PLC: 'Input title...',
    TITLE_ERR: 'A-Z and numbers'
  },
  // other sections may have incomplete
  // set of keys
  ru:{
    TITLE_PLC: 'Введите название...'
  }
}
xxxxxxxxxx
 
/* Container for CSS code */

During form start, appropriate dict branch is taken and merged with lang section itself. So all app functions can access constants in a manner like this.lang.LANG_CONST. Source locale branches are not removed, so all lang constants also accessible directly using this.lang.en.LANG_CONST syntax.

Default locale can be set using $.my.locale('lang') globally or using params.locale property for local override.

If no particular locale present in lang section, or some locale constants are omitted, en section is taken (entirely or partially). It means lang.en section must always be present and complete, if lang present.

External commands

Syntax is $obj.my("cmd", argument). $obj is form instance or form’s control.

Form commands

Form is manageable during runtime using form command $("#runningForm").my("command", arg). Available commands are:

$form.my("data")

.my("data") returns link to live data object.

.my("data", object) deep merge object with form’s data and redraws form.

$form.my("disabled")

Disables/enables form or returns current state. $form.my("disabled", true) marks all controls as inactive – form come inactive. $form.my("disabled") returns false if form is in active state.

$form.my("valid")

If all form’s controls are valid, returns true, else – false.

$form.my("errors")

Returns {} if all controls are valid, or {"#selector":"Error mesage", ...} with all invalid selectors. 

$form.my("manifest")

Returns runtime version of form’s manifest.

$form.my("redraw")

Redraws the form. 

$form.my("restyle")

Recalculates dynamic CSS rules for form and its childs.

$form.my("remove")

Removes the form. Unbinds all event listeners and removes all plugin instances attached. Returns form’s data.

$form.my("undo")

$form.my("undo", steps) rolls the form several steps back. To use this feature params.history property of a manifest must be 1+ – no undo steps are remembered by default. 

$form.my()

Returns jQuery data object "my", mounted on DOM node, is equivalent to $form.data("my"). Properties of an object returned:

  • cid unique form instance id
  • mid unique manifest id hash
  • data points to form’s data object
  • id manifest id, if it had any, or autogenerated id
  • initial initial data object deep clone
  • manifest form manifest
  • params full list of form instance’s settings
  • ui internal extended ui section

Control’s commands

 Not recommended. Using control‘s commands from inside running manifest‘s functions is not recommended. In those cases better use this.my[command](args) syntax introduced in 1.2.0 instead.

Syntax – $ctrl.my("command", arg). Available commands are:

$ctrl.my("container")

Returns jQuery object of DOM container of a control.

$ctrl.my("find")

$ctrl.my("find", "#selector") searches #selector inside the form.

$ctrl.my("insert")

$ctrl.my("insert", where, what ), if applied inside list item, inserts object what at where position of the list. To insert at the end – where:1e12.

$ctrl.my("remove")

If applied inside list item – removes it form the list.

$ctrl.my("val")

Returns control’s value.

$control.my()

Returns data object "my" of the control. Properties are:

  • data points to data object of the form
  • errors points to error list of the form
  • events, string, list of events tracked
  • id manifest id
  • params form settings
  • root jQuery object of the form
  • selector control’s jQuery selector
  • ui control section.

Form delivery, caching and merge

Manifests are single objects, without loop references and more or less scope independent. A manifest defines form’s facade and behavior more or less completely. So delivering a manifest you deliver an app. 

Manifest as JSON

If regexps and functions are represented as strings, manifest become valid JSON.

jQuery.my has service function $.my.tojson (obj), that converts objects with functions and regexps into JSON. This approach is not unique – functions are converted to strings in CouchDB for example. 

$.my.tojson( {x: function () {}} ) >> '{"x": "function (){}"}'

Converting functions into strings we surely loose all scope info, but functions of a manifest are scope-aware in general.

Service function $.my.fromjson( extJsonString ) converts extended JSON into object with functions and regexps.

Manifest cache

If manifest has id property like "ns.Name1.Name2", it can be cached using $.my.cache( manifest ). Cached manifest is available from inside of other forms by string reference like manifest: "ns.Name1.Name2".

Property id of cacheable manifest must be string of latins in dot notation, have no spaces and two parts minimum. ns is namespace string, Name1.Name2 .... NameN chain is unique form name.

Use $.my.cache( formId ) to get a clone of cached manifest. 

Combining manifests

Property id is a reference in dot-notation. It points to the branch of cache the manifest is put into. 

When we first cache manifest of  id:"app.Name", and then manifest of id:"app.Name.Component", first manifest in the cache receives property Component, that is second manifest.

If we call $.my.cache( "app.Name" ) we obtain app.Name manifest with  app.Name.Component manifest mounted into Component property.

Components are like dlls, they can be hot-swapped. 

Pub/sub radio

$.my app instances and their controls can both emit messages and listen to pub/sub channels. Pub/sub technique is good for broadcasting events, that may have out-of-app impact. For example, our app loaded a lot of data and notify neighbors, that cache is updated and they are to rebuild item lists.

There are two modes of radio – global broadcast and realm-based broadcast. Listeners for both of them are identical – a control must have listen property in ui section with channels control is subscribed to.

Difference is how radio event is submitted and propagated.

Realm-based radio

When radio packet is submitted using $ctrl.trigger("radio", {channel:"chName", msg:message}), transmission packet bubbles until it reach:

  • Any $.my form, that has radio section with event’s channel name, or
  • <body> DOM node.

If one of two is reached, event reflects and propages down to all child listeners. So if an app wants some radio channel to stay inside app – its manifest must have radio property with the channel listed.

Global radio

There is another way to broadcast – $.my.radio("chName", message). This command sends message to every channel subscriber across web page regardless if it’s screened with radio of parent manifest or not.

Utility functions

The plugin exports several service functions. They are:

$.my.version()

Returns jquerymy version like jQuery.my 1.2.6

$.my.locale( null or string )

Gets / sets locale. By default, locale is taken from the leading part of browser locale (mean en-GB and en-US both set internal locale to en).

$.my.tojson( obj )

Converts obj into json. Unlike JSON.stringify converts functions and regexps.

$.my.fromjson( string )

Parse extJSON string and returns object, with functions and regexps if any.

$.my.ajax( obj or fn )

Exec internal ajax request if obj passed. If function passed, replaces internal ajax implemetation ($.ajax by default) with external function.

Returns promise.

$.my.f.mask( obj, mask )

Select object properties by mask. Mask is an object, string reference or an array of references.

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
$.my.f.mask( {a:{b:1, c:2, d:{ e:3 }}}, "a.d.e" )         » 3
$.my.f.mask( {a:{b:1, c:2, d:{ e:3 }}}, ["a.d", "a.b"] )   » [{e:3}, 1]
$.my.f.mask( {a:{b:1, c:2, d:{ e:3 }}}, {a:{c:true}} )     » {a:{ c:2 }}
xxxxxxxxxx
 
/* Container for CSS code */

In no property exist, undefined is returned.

$.my.f.unmask( obj, mask ) 

Unfolds masked object into original.

xxxxxxxxxx
 
<!-- Put HTML code here -->
xxxxxxxxxx
 
// Two arguments
$.my.f.unmask( [{e:3}, 1], ["a.d", "a.b"] )         
  // returns {a:{b:1, d:{ e:3 }}}
$.my.f.unmask( ["","",""], ["a.b.c","e.f","e.h"] )   
  // returns {a:{b:{c:""}}, e:{f:"", h:""}}
// Three arguments
var obj = {a:[5]};
$.my.f.unmask (obj, [6,7], ["a.1", "c.d"]);
  // Returns mutated obj, that is now
  // {a:[5,6], c:{d:7}}
xxxxxxxxxx
 
/* Container for CSS code */

$.my.f.sdbmCode( any )

Simple sdbm hash function, from Berkeley ndb. Non-cryptographic and though blazing fast.

$.my.f.css2json( string )

Converts plain text CSS ruleset into object structured as style manifest property.

Modal dialog

jQuery.my plugin includes promise-based modal and non-blocking (popup) dialog implementation. Dialog can be $.my form, simple HTML or jQuery image.

Global modal is singletone and blocks all other inputs. Once opened global modal dialog blocks other global modals’ attempts to init – until closed.

Non-global popup dialogs are good for in-place pop-ups with info or settings for example. They are non-blocking.

$pivot.modal( obj , done )  » promise

Opens or closes modal. Both done done and promise can handle dialog close. Unlike promise, done can cancel popup close request. Promise is resolved or rejected on modal close.

Note, that since 1.2.6 $obj.modal does not conflict with Bootstrap implementation if Bootstrap was initialized before $.my. BT and $.my calls are distinguishable by argumants provided, so if arguments looks suitable for BT, BT.modal is invoked.

$pivot object can be $.my control or just DOM node inside $.my form – when parent form is removed, all linked dialogs are cold-closed. $pivot geometry and position are used to align non-modal dialogs.

One $pivot object can have only one linked and opened dialog at a time. If $pivot.data("modal") returns object, $pivot already have dialog opened.

Global blocking modal can be initialized calling $.my.modal(obj). This syntax opens global modal that is not linked with any form.

First argument:

Object Opens modal and renders $.my form inside. Properties:

  • manifest form manifest
  • data form data, mutated by dialog on user input
  • root jQuery object to hold modal’s DOM. Default is control’s container or parent form.
  • width dialog inside content width
  • esc allows ‘cold’ close on Esc pressed – promise is rejected with string Cancelled. Default is false for non-modals and true for blocking modals.
  • enter allows ‘warm’ close on Enter, default is false
  • nose string, defines where dialog tip is placed – allowed positions are  "left""right""top""bottom"
  • align string, determines modal position relative to pivot, like top:103%;left:0px; that means modal, that is 103% of pivot height shifted from top and zero pixels from left of the pivot
  • global boolean, true opens global blocking dialog
  • screen boolean or string with CSS-compatible color. Defines if blocking screen div must be shown under dialog
  • focus auto-focuses first control in the form after init, default is true.
  • drag allows dragging the dialog if jQuery UI Draggable plugin is loaded. 
  • bound Number, distance in pixels between modal and it’s root obj, default is false, that is no bounds
  • hardClose Boolean, defines X close button behavior, if true, closing is cold, if false closing is warm and can be stopped by .done function
  • done – function (formErrors, formValue), allows or denies warm close, this inside the function points to modal form‘s manifest.
Promise returned is resolved with form’s data if modal was ‘warm’ closed.

Boolean Close dialog. Modal close has two scenarios – cold and warm. 

Warm close request  $.my.modal(false) can be cancelled – function done(null or err, data), called just before close, can return true to keep modal. 

Cold close request $.my.modal(true) invokes done (null, null) and regardless of value returned rejects promise with "Cancelled" value.

jQuery image Image passed pops up with max available width, if no width received.

HTML string  HTML content for modal.

$.my.modal.visible() » boolean

Returns true if modal is visible.

$.my.modal.parent( selector or null ) » jQuery object

Sets or gets DOM container, that holds modal screen and modal itself. Default is "body".



© 2017 ermouth, license – MIT