zuix.js emoji_nature API

Zuix class

Constructor

new Zuix() → {Zuix}

Allocates a new instance of zuix.js, JavaScript library for component-based development. A zuix.js instance is automatically allocated on page load, and always available in the global scope as zuix.

Returns

Zuix

Properties

$ → ZxQueryStatic

Helper function for manipulating the DOM.

Methods

activeRefresh($view, $element, contextData, refreshCallback) → {ActiveRefresh}

Active-Refresh factory method.

Parameters
NameTypeDescription
$viewZxQueryThe component's view
$elementZxQueryThe target element
contextDataobjectCustom data that ca be passed from call to call
refreshCallbackActiveRefreshHandlerThe refresh handler function
Returns

ActiveRefresh ‐ The ActiveRefresh object. Invoke the start() method on the returned object, to actually activate the refresh handler.

bundle(bundleData, callback) → {Zuix|Array.<BundleItem>}

Gets/Sets the application's data bundle (all components and scripts used in the page packed into a single object).

Parameters
NameTypeArgumentDescription
bundleData!Array.<BundleItem> | trueoptionalA bundle object holding in memory all components' data (cache)
callbackfunctionoptionalCalled once the bundle compilation ends. Works if bundleData is true
Returns

Zuix | Array.<BundleItem>

componentize(element) → {Zuix}

Searches the document, or inside the given element, for elements with z-load attribute, and loads the requested components. Is also possible to disable/enable the componentizer by passing a boolean value as argument.

Parameters
NameTypeArgumentDescription
elementElement | ZxQuery | booleanoptionalContainer to use as starting element for the search (default: document)
Returns

Zuix ‐ The {Zuix} object itself.

Example
 zuix.componentize(document);
 // Globally disable the componentizer
 zuix.compenentize(false);
 // Re-enable the componentizer
 zuix.compenentize(true);

context(contextId, callback) → {ComponentContext}

Gets a ComponentContext object, given its contextId or its host element. The contextId is the one specified in the ContextOptions object or by using the z-context attribute on the host element.

Parameters
NameTypeArgumentDescription
contextIdElement | ZxQuery | stringThe contextId or the component's host element.
callbackContextReadyCallbackoptionalThe callback function that will pass the component's context object once loaded and ready.
Returns

ComponentContext ‐ The matching component's context or null if the context does not exist or not yet loaded.

Example
<div z-load="site/components/slideshow"
     z-context="my-slide-show">...</div>
slideShow = null;
zuix.context('my-slide-show', function(ctx) {
  slideShow = ctx;
  // call component's methods
  slideShow.setSlide(1);
});

controller(handler, options) → {ContextControllerHandler}

Allocates a component's controller handler. The provided handler function will be called to initialize the component's controller instance once the component has been loaded.

Parameters
NameTypeArgumentDescription
handlerContextControllerHandler | stringFunction called to initialize the component controller that will be passed as argument of this function
optionsObject | ObjectoptionalOptional controller options / callback
Returns

ContextControllerHandler ‐ The allocated controller handler.

Example
// Allocates and assign a controller for
// the component 'path/to/component_name'
ctrl = zuix.controller(function(cp) {
  // `cp` is the {ContextController}
  // TODO: inline code of controller follows...
}).for('path/to/component_name');

dumpCache() → {Array.<ComponentCache>}

Dumps content of the components cache. Mainly for debugging purpose.

Returns

Array.<ComponentCache>

dumpContexts() → {Array.<ComponentContext>}

Dumps allocated component's contexts. Mainly for debugging purpose.

Returns

Array.<ComponentContext>

field(fieldName, container, context) → {ZxQuery}

Search the document or inside the given container for elements having the #<field_name> (or z-field="<name>") attribute matching the given value. This method implements a caching mechanism and automatic disposal of allocated objects and events.

Parameters
NameTypeArgumentDescription
fieldNamestringThe name of the #<field_name> (or z-field="name") attribute of the element(s) to get
containerElementoptionalStarting DOM element for this search (default: document)
contextobjectoptionalThe context
Returns

ZxQuery ‐ A {ZxQuery} object wrapping the matching element(s). If there's just one matching element, then the returned object will also have the additional method field(fieldName) to search for fields inside the element itself.

Example
<div #sample-container>
   <!-- HTML -->
</div>
<script>
container = zuix.field('sample-container');
container.html('Hello World!');
</script>

getResourcePath(path) → {string}

Gets the path of a loadable resource.

Parameters
NameTypeDescription
pathstringLoadable resource id
Returns

string ‐ The resource's path.

hook(eventPath, eventHandler) → {Zuix}

Sets a callback for a global event. There can be only one callback for each kind of global event. Pass null as eventHandler to unset a previously set callback.

Parameters
NameTypeArgumentDescription
eventPathstringThe event path
eventHandlerfunction | undefinedoptionalThe handler function
Returns

Zuix ‐ The {Zuix} object itself.

Example
// The context `this` in the event handlers will be
// the {ComponentContext} object that sourced the event.
// The `data` parameter passed to the handlers, is of
// variant type, depending on the type of the occurring event.
zuix.hook('load:begin', function(data) {

  loaderMessage.html('Loading "' + data.task + '" ...');
  loaderMessage.show();

}).hook('load:next', function(data) {

  loaderMessage.html('"' + data.task + '" done, loading next..');

}).hook('load:end', function() {

  loaderMessage.hide();

}).hook('html:parse', function(data) {
  // Process HTML content before it's attached to the DOM

  if (this.options().markdown === true && typeof showdown !== 'undefined') {
    // ShowDown - MarkDown syntax compiler
    let htmlMarkDown = data.content;
    htmlMarkDown = new showdown.Converter()
      .makeHtml(htmlMarkDown);
    // return the processed content
    data.content = htmlMarkDown;
  }

}).hook('css:parse', function(data) {
  // Process CSS content before it's attached to the DOM

  let css = data.content;
  // process css, eg. run a CSS pre-processor
  // eg. Sass, Less, ...
  css = run_pre_processor(css);
  // return the processed content
  data.content = css;

}).hook('view:process', function(view) {
  // The view DOM is now fully loaded and ready
  // `view` is of {ZxQuery} type

  // Prism code syntax highlighter
  view.find('code').each(function(i, block) {
    this.addClass('language-javascript');
    Prism.highlightElement(block);
  });

  // Force opening of all non-local links in a new window
  zuix.$('a[href*="://"]').attr('target', '_blank');

  // Material Design Light auto-detection
  // Call DOM upgrade on newly added view elements
  if (componentHandler)
    componentHandler.upgradeElements(view.get());

});

lazyLoad(enable, threshold) → {Zuix|boolean}

Enables/Disables lazy-loading or gets the current setting.

Parameters
NameTypeArgumentDescription
enablebooleanoptionalEnable or disable lazy loading.
thresholdnumberoptionalLoad-ahead threshold in pixels. When < 0, elements will be loaded before entering the viewport for the given amount of pixels. Positive values will delay loading of element until the entered the viewport for at least the given number of pixels.
Returns

Zuix | booleantrue if lazy-loading is enabled, false otherwise.

load(componentId, options) → {ComponentContext}

Loads a component. This is the programmatic equivalent of z-load attribute used to load components from HTML.

Parameters
NameTypeArgumentDescription
componentIdstringThe identifier name of the component to be loaded
optionsContextOptionsoptionalOptions used to initialize the loaded component
Returns

ComponentContext ‐ The component context.

Example
 <!--
 The controller will be loaded on the following host element:
 -->
<div #sample-view></div>

<script>
// Get the host element
const view = zuix.field('sample-view');

// Declares inline controller for 'my/example/component'
const exampleController = zuix.controller((cp) => {
  cp.create = onCreate;

  function onCreate() {
    // Sets the initial content of the view
    cp.view().html('Hello World!');
    // Exposes the private `testMethod`
    // as the public method `test`
    cp.expose('test', testMethod);
  }

  function testMethod() {
    cp.log.i("Method exposing test");
    cp.view().html('A simple test.');
  }
}).for('my/example/component');

// loads the controller
zuix.load('my/example/component', { view, ready: (ctx) => {
  // call the public method `test` after 1 second
  setTimeout(ctx.test, 1000);
}});
</script>

loadComponent(elements, componentId, type, options) → {Zuix}

Loads a component, given the target host element(s). If the target is already a component, it will be unloaded and replaced by the new one.

Parameters
NameTypeArgumentDescription
elementsZxQuery | ElementThe target host element(s) or component context(s)
componentIdstring | objectThe id of the component to load (path/component_name)
type'view' | 'ctrl' | undefinedoptionalThe component type
optionsContextOptions | undefinedoptionalThe component options
Returns

Zuix ‐ The {Zuix} object itself.

Example
<div layout="rows center-spread">

  <div class="card-component">
    <div #title>Card 1</div>
  </div>

  <div class="card-component">
    <div #title>Card 2</div>
  </div>

</div>
<style>
.card-component {
  margin: 8px;
  max-width: 360px;
}
</style>
<script>
  const elements = zuix.$.find('.card-component');
  zuix.loadComponent(elements, 'templates/mdl_card', 'view');
</script>
Card 1
Card 2

observable(obj) → {ObservableObject}

Gets an observable instance of the given object. Based on the browser's built-in Proxy object.

Parameters
NameTypeDescription
objobjectObject to observe
Returns

ObservableObject ‐ The observable object.

runScriptlet(scriptCode, $el, $view, data) → {object|undefined}

Runs a script in the scripting context of the given view element.

Parameters
NameTypeArgumentDescription
scriptCodestringScriptlet Js code
$elZxQueryTarget ZxQuery-wrapped element
$viewZxQueryComponent's view (ZxQuery)
dataobject | undefinedoptionalCustom data
Returns

object | undefined

setComponentCache()

Sets components cache.

Returns

‐ void

store(name, value) → {object}

Gets/Sets a global store entry.

Parameters
NameTypeArgumentDescription
namestringEntry name
valueobjectoptionalEntry value
Returns

object

Example
 // stores *myObjectData* in the store entry named *my-data*
 zuix.store('my-data', myObjectData);
 // gets data from the store entry named *my-data*
 const data = zuix.store('my-data');

trigger(context, eventPath, eventData) → {Zuix}

Triggers the event specified by eventPath.

Parameters
NameTypeArgumentDescription
contextobjectThe context object (this) passed to handler functions listening for this event
eventPathstringThe path of the event to fire
eventDataobjectoptionalThe data object of the event
Returns

Zuix ‐ The {Zuix} object itself.

unload(context) → {Zuix}

Unloads the given component context(s) releasing all allocated resources.

Parameters
NameTypeDescription
contextComponentContext | ZxQuery | ElementThe instance of the component to be unloaded, a ZxQuery selection, or the component's host element
Returns

Zuix ‐ The {Zuix} object itself.

Example
zuix.unload(ctx);

using(resourceType, resourcePath, callback, ctx) → {Zuix}

Loads a CSS, script or a singleton component. Resources loaded with this method are available in the global scope and can also be included in the application bundle.

Parameters
NameTypeArgumentDescription
resourceTypestringEither 'style', 'script' or 'component'
resourcePathstringRelative or absolute resource url path
callbackResourceUsingCallbackoptionalCallback function to call once resource is loaded
ctxComponentContextoptionalThe target context. Mandatory when loading resources for a component with ShadowDOM (custom element).
Returns

Zuix ‐ The {Zuix} object itself.

Example
zuix.using('script', 'https://some.cdn.js/moment.min.js', function(){
  // can start using moment.js
});

Type Definitions

ActiveRefreshCallback(data, refreshMs, forceActive)

The callback for setting data and delay of next refresh request.

Parameters
NameTypeArgumentDescription
dataobjectoptionalData to be passed to next refresh call
refreshMsnumberoptionalDelay in milliseconds before the next refresh call
forceActiveboolean | undefinedoptionalIgnore visibility, schedule anyway

ActiveRefreshHandler($view, $element, data, nextCallback, attributeName)

The Active-Refresh function that will be called for each refresh request.

This
Parameters
NameTypeArgumentDescription
$viewZxQueryThe component's view
$elementZxQueryThe target element as ZxQuery object
dataobjectCustom data that ca be passed from call to call
nextCallbackActiveRefreshCallbackCallback for scheduling the next refresh call
attributeNamestringoptionalSource attribute name if it's a '@' handler

BindingAdapterCallback($element, fieldName, $view, refreshCallback)

Binding adapter callback.

Parameters
NameTypeArgumentDescription
$elementZxQueryThe view's element bound to the data model's fieldName
fieldNamestringThe element's bound field name
$viewZxQueryThe view
refreshCallbackBindingAdapterRefreshCallbackoptionalRefresh loop callback

BindingAdapterRefreshCallback(refreshMs)

Binding adapter refresh callback

Parameters
NameTypeArgumentDescription
refreshMsnumberoptionalMilliseconds to wait before refresh (default: 500ms)

BundleItem

Bundle item object.

Properties
NameTypeDescription
viewElement
cssstring
controllerContextControllerHandler

ComponentCache

Component cache object.

Properties
NameTypeDescription
componentIdstringThe id of the cached component.
viewElementThe view element.
cssstringThe CSS style text.
css_appliedbooleanWhether the CSS style has been applied to the view or not.
controllerContextControllerHandlerThe controller handler function.
usingstringThe url/path if this is a resource loaded with zuix.using(..) method.

ContextControllerCreateCallback()

Function that gets called after loading, when the component is actually created and ready.

ContextControllerDisposeCallback()

Function called when the component is about to be disposed.

ContextControllerHandler(cp)

This function is called after the component is loaded and it is used to initialize its controller.

This
Parameters
NameTypeDescription
cpContextControllerThe component controller object

ContextControllerInitCallback()

Function that gets called after loading and before the component is created.

ContextControllerUpdateCallback(target, key, value, path, old)

Function called when the data model of the component is updated

Parameters
NameTypeDescription
targetObjectThe target object.
keystringThe name of the property.
valueObjectThe value of the property.
pathstringThe full property path (dotted notation).
oldObjectThe target object before the update.
Returns

‐ undefined

ContextErrorCallback(error, ctx)

Callback function triggered if an error occurs when loading a component.

This
Parameters
NameTypeDescription
errorObject
ctxComponentContextThe component context object (same as this).

ContextLoadedCallback(ctx)

Callback function triggered when a component is created, after all of its dependencies have been loaded.

This
Parameters
NameTypeDescription
ctxComponentContextThe component context (same as this).

ContextOptions

This object can be supplied when loading a component. It can be either passed as argument for the zuix.load(...) / zuix.loadComponent(...) methods, in the javascript code, or with the z-options attribute in the HTML code of the component's host element.

Properties
NameTypeDescription
contextIdObject | undefinedThe context id. HTML attribute equivalent: z-context. If not specified it will be randomly generated. HTML attribute equivalent: z-context.
containerElement | undefinedThe container element.
modelJSON | undefinedThe data model. HTML attribute equivalent: z-model.
viewElement | undefinedThe view element.
controllerContextControllerHandler | undefinedThe controller handler.
controllerMembersObjectAdditional methods/properties to add to the context controller.
onObject.<string, EventCallback> | Object.<string, string> | undefinedThe map of event handlers for standard and component's events. An event can also be simply routed to another component's event by specifying the mapped event name string. HTML attribute equivalent: z-on.
behaviorObject.<string, EventCallback> | Object.<string, string> | undefinedThe map of event handlers for behaviors. An event can also be simply routed to another component's event by specifying the mapped event name string. HTML attribute equivalent: z-behavior.
cssHTMLStyleElement | string | boolean | undefinedCustom stylesheet to apply to the component's view.
encapsulationboolean | undefinedWhether to use style encapsulation or not (default: false).
resetCssboolean | undefinedWhether to reset view style to prevent inheriting from parent containers (default: false).
cextstring | undefinedWhen loading content of the view, appends the specified extension instead of .html.
htmlboolean | string | undefinedIt can be set to false, to disable HTML template loading, or it can be set to a string containing the inline HTML template code.
lazyLoadboolean | undefinedEnables or disables lazy-loading (default: false). HTML attribute equivalent: z-lazy.
prioritynumber | undefinedLoading priority (default: 0). HTML attribute equivalent: z-priority.
fetchOptionsObject | undefinedOptions to be used when fetching this component resources.
usingstring | undefinedComma separated contexts' id list of components used in this context. A variable with camel-case converted name for each referenced context, will be available in the local scripting scope.
loadedContextLoadedCallback | undefinedThe loaded callback, triggered once the component is successfully loaded.
readyContextReadyCallback | undefinedThe ready callback, triggered once all component's dependencies have been loaded.
errorContextErrorCallback | undefinedThe error callback, triggered when an error occurs.

ContextReadyCallback(ctx)

Callback function triggered when a component has been successfully loaded.

This
Parameters
NameTypeDescription
ctxComponentContextThe component context (same as this).

ElementPosition

The ElementPosition object returned by the position() method.

Properties
NameTypeDescription
xnumberX coordinate of the element in the viewport
ynumberY coordinate of the element in the viewport
framePositionPosition of the element relative to the viewport
eventstringCurrent state change event description (enter, exit, scroll, off-scroll)
visiblebooleanBoolean value indicating whether the element is visible in the viewport

ElementsIterationCallback(count, item, $item)

Callback function used with the each(..) method.

This
Parameters
NameTypeDescription
countnumberIteration count.
itemElementCurrent element.
$itemZxQueryZxQuery wrapped element (same as 'this').

EventCallback(event, data, $el)

Callback function triggered when an event registered with the on method occurs.

This
Parameters
NameTypeDescription
eventstringEvent name
dataObjectEvent data
$elZxQueryZxQuery wrapped element that sourced the event (same as this)

IterationCallback(k, item)

The IterationCallback function.

This
Parameters
NameTypeDescription
knumber | objectIteration count / item key.
itemobjectCurrent element (same as this).

LoggerMonitorCallback(ctx, level)

Callback function for monitoring all log messages.

This
Parameters
NameTypeDescription
ctxObject
levelstring
...argsArray.<Object>

PlayFxCallback($element, classQueue)

Callback function used with the each(..) method.

This
Parameters
NameTypeDescription
$elementZxQueryTarget element (same as 'this').
classQueueArray.<string>Transition/animation class queue left to play, null if the animation ended.

PlayFxConfig

Configuration object for playFx, playTransition, playAnimation utility methods.

Properties
NameTypeArgumentDescription
type'transition' | 'animation'The type of effect to play.
targetElement | ZxQueryTarget element.
classesArray.<string> | stringList of transition or animation classes to play.
optionsobjectoptionalTransition/animation options ('delay', 'duration', etc..).
holdStatebooleanoptionalHold last transition/animation class.
onStepPlayFxCallbackoptionalSince class list can contain more than just two classes, this callback will be called after each pair of transition/animation ended.
onEndPlayFxCallbackoptionalCalled when all transitions/animations ended.

Position

Relative position.

Properties
NameTypeDescription
dxnumber
dynumber

ResourceUsingCallback(resourcePath, hashIdOrContext)

Callback in response to a zuix.using request.

Parameters
NameTypeDescription
resourcePathstring
hashIdOrContextstring | object

ZxQueryHttpBeforeSendCallback(xhr)

The ZxQueryHttpBeforeSendCallback function.

This
Parameters
NameTypeDescription
xhrXMLHttpRequest

ZxQueryHttpErrorCallback(xhr, statusText, statusCode)

The ZxQueryHttpErrorCallback function.

This
Parameters
NameTypeDescription
xhrXMLHttpRequest
statusTextstring
statusCodenumber

ZxQueryHttpOptions

zuix.$.http options object.

Properties
NameTypeDescription
urlstring
beforeSendZxQueryHttpBeforeSendCallback | undefined
successZxQueryHttpSuccessCallback | undefined
errorZxQueryHttpErrorCallback | undefined
thenZxQueryHttpThenCallback | undefined

ZxQueryHttpSuccessCallback(responseText)

The ZxQueryHttpSuccessCallback function.

This
Parameters
NameTypeDescription
responseTextstring

ZxQueryHttpThenCallback(xhr)

The ZxQueryHttpThenCallback function.

This
Parameters
NameTypeDescription
xhrXMLHttpRequest
GitHub logo
JavaScript library for component-based websites and applications.