Come into the simplistic, powerful developer cloud. Save money, increase efficiency, and optimize spend with solutions that take away the process and cut the long story short.
Ride more on open source with our commitment to open source. WebQit Cloud lets you build on open technologies that you can always bank on.
Ready for a stress-free go-live experience? Watch this space for when we come in beta.
Web-native is an approach to web tooling that seeks to solve for the traditonal, native web over vendor-specific interests. This is an especially important goal for a web community that is now fragmented into framework silos.
WebQit Community is an initiative to support an obvious community-wide paradigm shift for web-native development. We seek to drive community participation in new ideas for the web platform, and in all the projects that are revisiting much of the assumptions that brought us here, to explore new possibilities around just conventional web languages and APIs.
We're beginning this initiative by giving mentions to the actionable discussions from around the web that are painting this future of the web. It'll be nice to see the whole picture from one place.
Come into the simplistic, powerful developer cloud. Save money, increase efficiency, and optimize spend with solutions that take away the process and cut the long story short.
Ride more on open source with our commitment to open source. WebQit Cloud lets you build on open technologies that you can always bank on.
Ready for a stress-free go-live experience? Watch this space for when we come in beta.
Web-native is an approach to web tooling that seeks to solve for the traditonal, native web over vendor-specific interests. This is an especially important goal for a web community that is now fragmented into framework silos.
WebQit Community is an initiative to support an obvious community-wide paradigm shift for web-native development. We seek to drive community participation in new ideas for the web platform, and in all the projects that are revisiting much of the assumptions that brought us here, to explore new possibilities around just conventional web languages and APIs.
We're beginning this initiative by giving mentions to the actionable discussions from around the web that are painting this future of the web. It'll be nice to see the whole picture from one place.
Taste the future today from an ecosystem of open source tooling that explores the web-native approach to engineering modern web applications. It comes bringing all of the goodness of the native web platform and the traditional paradigms that have historically been traded.
We're iterating really fast - fast going from experimental to stable - on all the new possibilities we are exploring around conventional web languages and APIs, and the traditional web.
Contributions are welcome on each project! Help report typos and bugs via github issues, or submit a fix. Contributions are taken promptly and are well-acknowledged!
Taste the future today from an ecosystem of open source tooling that explores the web-native approach to engineering modern web applications. It comes bringing all of the goodness of the native web platform and the traditional paradigms that have historically been traded.
We're iterating really fast - fast going from experimental to stable - on all the new possibilities we are exploring around conventional web languages and APIs, and the traditional web.
Contributions are welcome on each project! Help report typos and bugs via github issues, or submit a fix. Contributions are taken promptly and are well-acknowledged!
Play UI is a family of tools that brings a utility-based approach and wholistic experience to UI development. This gives you full UI authoring capabilities in the liberty and combinational power of standalone utilities!
Take the playbook! Visit the docs for an overview, the API and usage guides.
Also, join the Github Discussions for Play UI.
Help report bugs, or request features; or join in the development.
The MIT license.
Welcome to the Play UI documentation. We hope you find it easy to understand and navigate.
If you have questions about anything related to the Play UI, you're always welcome to ask on our GitHub Discussions.
Explore the API Reference.
Classes in this category.
class TransformRule {}This class is an object model of the CSS transform rule.
let transformRuleObject = new TransformRule(transformRuleDefinition);Parameters
transformRuleDefinition: Object|String - An object of the transform rule properties or the string none.Create a transfrom rule instance from an object.
let transformRuleObject = new TransformRule({
translate: [30, 40],
sclae: 3,
});
// Convert to string
console.log(transformRuleObject.toString());
// translate(30, 40) scale(3)Create a transfrom rule instance from the string none.
let transformRuleObject = new TransformRule('none');
// Convert to string
console.log(transformRuleObject.toString());
// noneparse()This function is used to parse an element's transform rule into an instance of TransformRule. If the input is a computed transform matrix, it automatically calls the TransformRule.parseMatrix() method.
let transformRuleObject = TransformRule.parse(rule);Parameters
rule - String: A CSS transform rule.Return
TransformRule - An object model of the parsed transform rule.Parse transform rule declaration.
// Parse
let transformRuleObject = TransformRule.parse('translate(30, 40) scale(3)');
// Show
console.log(transformRuleObject);
/**
{
translate: [30, 40],
sclae: 3,
}
*/
//Convert to string
console.log(transformRuleObject.toString());
// translate(30, 40) scale(3)parseMatrix()This function is used to parse an element's computed transform rule matrix into an instance of TransformRule.
let transformRuleObject = TransformRule.parseMatrix(matrix);Parameters
matrix - String: The computed CSS transform matrix.Return
TransformRule - An object model of the parsed transform rule.Parse an element's computed transform rule.
<style>
div {
transform: translate(30, 40) scale(3);
}
</style>
<div id="el"></div>let transformRule = document.querySelector('#el').style.transform;
// Set attribute
let transformRuleObject = TransformRule.parse(transformRule);
// Show
console.log(transformRuleObject);
/**
{
translate: [30, 40],
sclae: 3,
}
*/
//Convert to string
console.log(transformRuleObject.toString());
// translate(30, 40) scale(3).css()This method is an alias of the .cssSync() method. See .cssSync() for documentation.
The .css() instance method is internally based on the standalone css/cssSync() function which may be used statically.
const { cssSync: css } = $.css;import { cssSync as css } from '@webqit/playui-js/src/css/index.js';.cssAsync()This method is used to asynchronously set or get one or more style properties for the given element. It is a convenient alternative to the native window.getComputedStyle and ElementCSSInlineStyle.style. It also has special support for vendor-prefixed properties.
The suffix Async differentiates this method from its Sync counterpart - .cssSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Set a single property
await $(el).cssAsync(prop, value, params = {});
// Set multiple properties
await $(el).cssAsync({
[prop]: value,
}, params = {});Parameters
prop: String - A CSS property.value: Any - The property value to set. When an empty string '', the property is unset from the element.params: Object - Additional directives for the method. (This parameter only applies in the second syntax above, where the first parameter is an array.) Valid directives are:scope - Set to global to write the new rules to a stylesheet. Or set to inline to write to the element's style attribute. By default, the element's computed CSS object is what is updated. But the browser also automatically writes the rules to the element's style attribute. The scope:inline directive thus has no special effect.prepend - Set to true to write the new rules behind existing rules instead, making existing rules take priority. With the scope:global directive, the given rules are inserted at the start of the target stylesheet. With the scope:inline directive, the given rules are prepended to the element's style attribute.pseudo - (Works with the scope:global directive. Forbidden otherwise.) Set to a pseudo selector (e.g ::before) to set the CSS of a pseudo element associated with the matched element instead.autoUuid - (Works with the scope:global directive.) Set to false to prevent Play UI from automatically generating a special attribute playuo-uuid for the element. By default, this is what is used as the CSS selector for the rules written to stylesheet.autoId - (Works with the scope:global directive.) Set to true to automatically generate an ID for the element where not present. This is used as the CSS selector for the rules written to stylesheet. This also prevents Play UI from automatically generating the special playuo-uuid attribute as above. Note that autoUuid and autoId cannot be both false.noScratchPad - (Works with the scope:global directive.) Set to true to target the latest editable stylesheet for the operation. Otherwise, a stylesheet maintained by Play UI is used.vendorize - Set to true to automatically handle applicable vendor-specific rule prefixing.Return
this - The Play UI instance.Change an element's CSS, then change the CSS of its :after pseudo element.
$(el).cssAsync('color', 'red').then($el => {
$el.cssAsync({
display: 'block',
content: '"[NEW]"',
}, {pseudo: ':after'});
});// Get a single property
let value = await $(el).cssAsync(prop);
// Get multiple properties
let values = await $(el).cssAsync([...prop], params = {});Parameters
prop: String - A CSS property.params: Object - Additional directives for the method. Valid directives are:scope - Set to global to read the global, stylesheet-based CSS for the matched element. Or set to inline to read the element's style attribute instead. By default, the element's computed CSS object is what is read.pseudo - (Forbidden with the scope:inline directive.) Set to a pseudo selector (e.g ::before) to get the CSS of a pseudo element associated with the matched element instead.all - (Works with the scope:global directive.) Set to true to return an array of rule blocks gathered for the matched element from across stylesheets. Otherwise, rule blocks are merged into a single object and returned.noCache - (Works with the scope:global directive.) Set to true to bypass Play UI's internal cache that optimizes traversing the document's stylesheets.vendorize - Set to true to automatically handle applicable vendor-specific rule prefixing.Return
value: Any - The value of the named CSS property.values: Object - A key/value hash of the listed CSS properties.Get an element's computed CSS. Note that if we must provide a params object, props list has to be an array.
let result = await $(el).cssAsync(['color'], {scope: 'inline'});
// {color: 'red'}The .cssAsync() instance method is internally based on the standalone css/cssAsync() function which may be used statically.
const { cssAsync } = $.css;import { cssAsync } from '@webqit/playui-js/src/css/index.js';.cssSync()This method is used to set or get one or more style properties for the given element. It is a convenient alternative to the native window.getComputedStyle and ElementCSSInlineStyle.style. It also has special support for vendor-prefixed properties.
The suffix Sync differentiates this method from its Async counterpart - .cssAsync(). Unlike the Async counterpart, this method is not promised-based.
// Set a single property
$(el).cssSync(prop, value, params = {});
// Set multiple properties
$(el).cssSync({
[prop]: value,
}, params = {});Parameters
prop: String - A CSS property.value: Any - The property value to set. When an empty string '', the property is unset from the element's inline CSS.params: Object - Additional directives for the method. Valid directives are:scope - Set to global to write the new rules to a stylesheet. Or set to inline to write to the element's style attribute. By default, the element's computed CSS object is what is updated. But the browser also automatically writes the rules to the element's style attribute. The scope:inline directive thus has no special effect.prepend - Set to true to write the new rules behind existing rules instead, making existing rules take priority. With the scope:global directive, the given rules are inserted at the start of the target stylesheet. With the scope:inline directive, the given rules are prepended to the element's style attribute.pseudo - (Works with the scope:global directive. Forbidden otherwise.) Set to a pseudo selector (e.g ::before) to set the CSS of a pseudo element associated with the matched element instead.autoUuid - (Works with the scope:global directive.) Set to false to prevent Play UI from automatically generating a special attribute playuo-uuid for the element. By default, this is what is used as the CSS selector for the rules written to stylesheet.autoId - (Works with the scope:global directive.) Set to true to automatically generate an ID for the element where not present. This is used as the CSS selector for the rules written to stylesheet. This also prevents Play UI from automatically generating the special playuo-uuid attribute as above. Note that autoUuid and autoId cannot be both false.noScratchPad - (Works with the scope:global directive.) Set to true to target the latest editable stylesheet for the operation. Otherwise, a stylesheet maintained by Play UI is used.vendorize - Set to true to automatically handle applicable vendor-specific rule prefixing.Return
this - The Play UI instance.Change an element's CSS, then change the CSS of its :after pseudo element.
$(el).cssSync('color', 'red');
$(el).cssSync({
display: 'block',
content: '"[NEW]"',
}, {pseudo: ':after'});// Get a single property
let value = $(el).cssSync(prop);
// Get multiple properties
let values = $(el).cssSync([...prop], params = {});Parameters
prop: String - A CSS property.params: Object - Additional directives for the method. (This parameter only applies in the second syntax above, where the first parameter is an array.) Valid directives are:scope - Set to global to read the global, stylesheet-based CSS for the matched element. Or set to inline to read the element's style attribute instead. By default, the element's computed CSS object is what is read.pseudo - (Forbidden with the scope:inline directive.) Set to a pseudo selector (e.g ::before) to get the CSS of a pseudo element associated with the matched element instead.all - (Works with the scope:global directive.) Set to true to return an array of rule blocks gathered for the matched element from across stylesheets. Otherwise, rule blocks are merged into a single object and returned.noCache - (Works with the scope:global directive.) Set to true to bypass Play UI's internal cache that optimizes traversing the document's stylesheets.vendorize - Set to true to automatically handle applicable vendor-specific rule prefixing.Return
value: Any - The value of the named CSS property.values: Object - A key/value hash of the listed CSS properties.Get an element's computed CSS. Note that if we must provide a params object, props list has to be an array.
let result = $(el).cssSync(['color'], {scope: 'inline'});
// {color: 'red'}The .cssSync() instance method is internally based on the standalone css/cssSync() function which may be used statically.
const { cssSync } = $.css;import { cssSync } from '@webqit/playui-js/src/css/index.js';.cssTransaction()This method is used to start a transaction on an element for CSS operations that eventually might need to be rolled back. It is a convenient way to use the Play UI's Transaction class.
let transaction = $(el).cssTransaction(props, asyncWrites = false);Parameters
props: String|Array - A property or list of properties that describes the operation on the element.asyncWrites: Boolean - Specifies whether to use the asynchronous mode for writes by using cssAsync instead of cssSync.Return
Transaction - The Transaction instance.Below, we modify an element's CSS properties and later roll back the element to its initial state.
Define the element's stylesheet- and inline-based CSS:
<style>
div {
background-color: yellow;
}
</style>
<div id="el" style="color:red"></div>Start a transaction:
// Obtaine a Transaction instance. We're using the asyncWrites mode
let transaction = $('#el').cssTransaction(['background-color', 'color'], true);Do some modifications and create savepoints along the way:
const el = document.querySelector('#el');
// Create a savepoint for the initial state of the element - savepoint1
// We can rollback to this point later
transaction.savepoint();
// Alter the element's computed style
$(el).cssSync({
color: 'green',
backgroundColor: 'black',
});
// Create a savepoint - savepoint2
// We can rollback to this point later
transaction.savepoint();
// Alter the element's computed style further.
// Here we use the transaction's .apply method to keep things neat.
// Calls cssSync() (or cssAsync where asyncWrites is true) under the hood.
transaction.apply({
color: 'brown',
backgroundColor: 'teal',
});
// Create a savepoint - savepoint3
// We can rollback to this point later
transaction.savepoint();Rollback to a savepoint
// Rollback to anypoint after some time
setTimeout(() => {
// Rollback all the way to the element's initial state
transaction.rollback(0);
// Now background-color should fallback to yellow
// And color should be back to red
}, 2000);In the code above, if another part of the app had changed one of those properties after the last savepoint we made, then the call to rollback() would have overridden those foreign changes to restore the element to the specified savepoint.
To automatically detect foreign changes and leave them untouched, we would set the preserveCurrentState parameter of the rollback() method to true.
// The following changes were made after our last savepoint
el.style.color = 'brown';
// Rollback to savepoint2
setTimeout(() => {
// Rollback all the way to the element's initial state
transaction.rollback(0, true);
// Color will be left at 'brown'
}, 2000);The .cssTransaction() instance method is internally based on the standalone css/cssTransaction() function which may be used statically.
const { cssTransaction } = $.css;import { cssTransaction } from '@webqit/playui-js/src/css/index.js';This method is used to store and manage arbitrary data with a data store internally associated with an element.
// Set a single value
$(el).data(key, value);
// Set multiple values
$(el).data({
[key]: value,
});Parameters
key: String - The key to set.value: Any - The data value to set. When undefined, the data key is unset from the data store; see below.Return
this - The Play UI instance.Set several distinct values for all elements matched by $().
$(el).data('key1', 'value 1').data({
key2: 'value 2',
key3: 'value 3'
});// Retrieve single value
let value = $(el).data(key);
// Retrieve multiples values
let values = $(el).data([...key]);
// Retrieve all values
let values = $(el).data();Parameters
key: String - The data key to read.Return
value: Any - The data value as initially stored, or undefined.values: Object - A hash of key/value pairs for each key in the list or in the entire data store, as in the last syntax.Retrieve values for the first element matched by $().
let value = $(el).data('key1');
// value-1// Unset single property
.data(key, undefined);
// Unset multiples values
$(el).data({
[key]: undefined,
});Parameters
key: String - The data key to unset.Return
this - The Play UI instance.Unset values for all elements matched by $().
$(el).data('key1', undefined).data({
key2: undefined,
key3: undefined,
});The .data() instance method is internally based on the standalone misc/data() function which may be used statically.
const { data } = $.misc;import { data } from '@webqit/playui-js/src/misc/index.js';.list()This method is used to create a live list within an element in an OOHTML-based document. (It requires the OHHTML polyfill to be available in the document.)
$(el).list(items[, params]);Parameters
items: Array - A list of data items to populate into a list container.
params: Object - An optional list of additional parameters for the operation.
renderCallback: function(directive, itemElement, itemData, index[, isUpdate]) - An optional callback that is called to handle rendering or unrendering of itemData.
Parameters
directive: String - This will be render when itemData is to be rendered into the given itemElement. It will be unrender when itemData is to be disposed off the given itemElement.itemElement: Element - A newly created list item element, or an existing list item element, that corresponds to the current itemData.itemData: Any - The current entry in the input items associated with itemElement.index: Int - The index of itemData in the input items.isUpdate: Boolean - A flag that indicates whether or not the given itemData is an update to a previous entry in the input items. This flag is only supplied when directive is render.Return
viod|false - A return value is not required for this function. But false can be returned to tell list() that itemData has been successfully rendered/unrendered. Otherwise, list() will automatically render/unrender itemData using the itemElement's setState() and clearState() methods respectively.
overflowCallback: function(directive, itemElement, itemData, index, collapsedCount) - An optional callback that is called to handle overflow events. When omitted, list() doesn't watch any items for overflow.
Parameters
directive: String - This will be collapse when itemElement is at the verge of overflowing the list container. It will be restore when itemElement can be again restored from its collapsed state.itemElement: Element - The list item element to be collapsed or restored.itemData: Any - The current entry in the input items associated with itemElement.index: Int - The index of itemData in the input items.collapsedCount: Int - The number of items still in the collapsed state. This will be 0 if itemElement is the last element in collapsed state.Return
viod|Promise - A return value is not required for this function. But a Promise can be returned to tell list() to wait while collapsing or restoring itemElement.
overflowContainerCallback: function(isOverflowing, containerElement, uncollapsedCount, collapsedCount) - An optional callback that is called both at the start and at the end of the reflow process that collapses or restores overflowing items.
Parameters
isOverflowing: Boolean - This is true when the reflow process is just beginning; false when the process has just ended.containerElement: Element - The container element undergoing a reflow.uncollapsedCount: Int - The number of items in the uncollapsed state.collapsedCount: Int - The number of items still in the collapsed state.Return
Boolean|Promise - A return value is not required for this function. But false (or a Promise that resolves to false) can be returned when isOverflowing is true to tell list() to skip a reflow.
collapsionPoint: String - A keyword specifying at what point along the list container to clip overflowing elements. Valid values are:
start - Clip overflows at the left (for horizontal lists) or top (for vertical lists) of the list container.center-start - Clip overflows at the center of the list container, but when visible elements are even in number, go one item less to the left (for horizontal lists) or top (for vertical lists) of the list container.center - Clip overflows at the center of the list container. This behaves as center-start when visible elements are even in number.center-end - Clip overflows at the center of the list container, but when visible elements are even in number, go one item less to the right (for horizontal lists) or bottom (for vertical lists) of the list container.end - Clip overflows at the right (for horizontal lists) or bottom (for vertical lists) of the list container.orientation: String - This is either horizontal or vertical to indicate the direction of the list and along which axis to watch for overflow. Default is horizontal.
clearDOM: Boolean - Specifies whether or not for list() to clear out any existing item elements that may have been created in a previous call to list(). This is false by default; list() will try to update any existing item elements with new data.
live: String - Specifies whether or not for list() to observe input items for mutations. This is true by default.
itemIndexAttribute: String - The attribute name on itemElement on which to set the index of the item. This defaults to data-index.
itemExportId: String - The export ID used for importing item elements for each item in the input items. When this sub parameter is omitted, the fragment identifier found in the module reference on the list container is used. Otherwise, the default export of the referenced module is used.
parentalOverflowBounds: Boolean - Whether or not to use the container of the list container or the list container itself as the overflow bounds. By default, the container of the list container is used. Set to false to use the list container itself.
Return
this - The Play UI instance.The document in context. The list items <li> in the module will be used to derive the items for the list container <ul>.
<head>
<template name="module1">
<li></li> <!-- the default export -->
<li exportgroup="export1" class="fancy-item"></li> <!-- a named export -->
</template>
</head>
<body>
<ul id="list" template="module1"></ul>
</body>Create a list of cities.
const items = [
{name: 'London'},
{name: 'Lagos'},
{name: 'Berlin'},
];
$('ul').list(items);A list item <li> is created for each city, and list()has bound the item data for each item element to the state of the element using the element's .setState() method. But binding the data alone doesn't get it rendered.
<ul id="list" template="module1">
<li data-index="0"></li>
<li data-index="1"></li>
<li data-index="2"></li>
</ul>Now, we provide a renderCallback function to handle rendering of item data.
$('ul').list(items, {
renderCallback(directive, itemElement, itemData) => {
if (directive === 'render') {
itemElement.innerHTML = itemData.name;
}
}
});Item data are now rendered.
<ul id="list" template="module1">
<li data-index="0">London</li>
<li data-index="1">Lagos</li>
<li data-index="2">Berlin</li>
</ul>The .list() instance method is internally based on the standalone data/list() function which may be used statically.
const { list } = $.data;import { list } from '@webqit/playui-js/src/data/index.js';.append()This method is an alias of the .appendSync() method. See .appendSync() for documentation.
The .append() instance method is internally based on the standalone dom/appendSync() function which may be used statically.
const { appendSync: append } = $.dom;import { appendSync as append } from '@webqit/playui-js/src/dom/index.js';.appendAsync()This method is used to asynchronously append content to an element. It works exactly the same as the native ParentNode.append() except that when the implied content is undefined, it is converted to an empty string.
The suffix Async differentiates this method from its Sync counterpart - .appendSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Append content(s) to an element
await $(el).appendAsync(content[, ...content]);Parameters
content: String|Node - The text or HTML content, or some DOM node, to append.Return
this - The Play UI instance.Append an element node and some text content to an element.
let div = document.createElement("div");
$(el).appendAsync(div, 'Playful', ' ', 'people', '!');The .appendAsync() instance method is internally based on the standalone dom/appendAsync() function which may be used statically.
const { appendAsync } = $.dom;import { appendAsync } from '@webqit/playui-js/src/dom/index.js';.appendSync()This method is used to append content to an element. It works exactly the same as the native ParentNode.append() except that when the implied content is undefined, it is converted to an empty string.
The suffix Sync differentiates this method from its Async counterpart - .appendAsync(). Unlike the Async counterpart, this method is not promised-based.
// Append content(s) to an element
$(el).appendSync(content[, ...content]);Parameters
content: String|Node - The text or HTML content, or some DOM node, to append.Return
this - The Play UI instance.Append an element node and some text content to an element.
let div = document.createElement("div");
$(el).appendSync(div, 'Playful', ' ', 'people', '!');The .appendSync() instance method is internally based on the standalone dom/appendSync() function which may be used statically.
const { appendSync } = $.dom;import { appendSync } from '@webqit/playui-js/src/dom/index.js';.appendToSync()This method is used to append matched elements to target elements.
The suffix Sync differentiates this method from its Async counterpart - .appendToAsync(). Unlike the Async counterpart, this method is not promised-based.
$(el).appendToSync(target);Parameters
target: String|Element - A CSS selector of the element, or the element itself Element, to append to.Return
this - The Play UI instance.Append some dynamically-created nodes to document body.
$('<h1>Playful people!</h1>').appendToSync(document.body);Append an existing div to multiple targets. The div is cloned into all targets except the last target.
let div = document.querySelector('div');
$(div).appendToSync('.multiple');The .appendToSync() instance method is internally based on the standalone dom/appendToSync() function which may be used statically.
const { appendToSync } = $.dom;import { appendToSync } from '@webqit/playui-js/src/dom/index.js';.attr()This method is an alias of the .attrSync() method. See .attrSync() for documentation.
The .attr() instance method is internally based on the standalone dom/attrSync() function which may be used statically.
const { attrSync: attr } = $.dom;import { attrSync as attr } from '@webqit/playui-js/src/dom/index.js';.attrAsync()This method is used to asynchronously set or get an element's attribute. It is a shorter alternative to the native Element.setAttribute(), Element.getAttribute(), and Element.removeAttribute(). It also has special support for list-based attributes like class.
The suffix Async differentiates this method from its Sync counterpart - attrSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Set a single attribute
await $(el).attrAsync(name, value);
// Set multiple attributes
await $(el).attrAsync({
[name]: value,
});Parameters
name: String - The attribute name to set.value: String|Boolean - The attribute value to set. When true, the string "true" is set on the attribute. When false, the attribute is unset from the element; see below.Return
this - The Play UI instance.Set the ID attribute on an <input /> element. Then set other attributes.
// Set a single attribute
$(el).attrAsync('id', 'email-input').then($el => {
$el.attrAsync({
type: 'email',
required: true,
});
});// Get a single attribute
let attribute = await $(el).attrAsync(name);
// Get multiple attributes
let attributes = await $(el).attrAsync([...name]);Parameters
name: String - The attribute name.Return
value: Any - The value of the named attribute.values: Object - A key/value hash of the listed attributes.Get the attribute on an <input /> element.
// Set a single attribute
let value = await $(el).attrAsync('id');
// email-input// Remove a single attribute
$(el).attrAsync(name, false);
// Remove multiple attributes
await $(el).attrAsync({
[name]: false,
});Parameters
name: String - The attribute name.Return
this - The Play UI instance.Unset an element's ID attribute.
$(el).attrAsync('id', false);// Add a single token to an attribute
await $(el).attrAsync(name, token, mutation === true);
// Add multiple tokens to an attributes
await $(el).attrAsync(name, [ token, ... ] mutation === true);
await $(el).attrAsync(name, {
[token]: mutation === true,
});
// Remove a token from a single delimited attribute
await $(el).attrAsync(name, token, mutation === false);
// Remove multiple tokens to an attributes
await $(el).attrAsync(name, [ token, ... ] mutation === false);
await $(el).attrAsync(name, {
[token]: mutation === false,
});Parameters
name: String - The attribute name to modify.token: String - The attribute token to add or remove.mutation: Boolean - The add/remove directive. When true, the given token is added to the attribute's value. When false, the given token is removed from the attribute's value.Return
this - The Play UI instance.Modify an element's class attribute, then confirm the operation.
<div class="class1 class2" role="article"></div>let el = document.querySelector('.class1');
// Insert a class entry
await $(el).attrAsync('class', 'class3', true);
// Confirm the operation
console.log(await $(el).attrAsync('class')); // class1 class2 class3Toggle icon classes on an element.
<i class="volume-icon bi bi-volume-up"></i>let volumeIconElement = document.querySelector('.volume-icon');
let isMute = false;
$(volumeIconElement).on('click', async e => {
await $(el).attrAsync('class', {
'bi-volume-mute': isMute,
'bi-volume-up': !isMute,
});
isMute = !isMute;
});The .attrAsync() instance method is internally based on the standalone dom/attrAsync() function which may be used statically.
const { attrAsync } = $.dom;import { attrAsync } from '@webqit/playui-js/src/dom/index.js';.attrSync()This method is used to set or get an element's attribute. It is a shorter alternative to the native Element.setAttribute(), Element.getAttribute(), and Element.removeAttribute(). It also has special support for list-based attributes like class.
The suffix Sync differentiates this method from its Async counterpart - attrAsync(). Unlike the Async counterpart, this method is not promised-based.
// Set a single attribute
$(el).attrSync(name, value);
// Set multiple attributes
$(el).attrSync({
[name]: value,
});Parameters
name: String - The attribute name to set.value: String|Boolean - The attribute value to set. When true, the string "true" is set on the attribute. When false, the attribute is unset from the element; see below.Return
this - The Play UI instance.Set the ID attribute on an <input /> element. Then set other attributes.
// Set a single attribute
$(el).attrSync('id', 'email-input');
$(el).attrSync({
type: 'email',
required: true,
});// Get a single attribute
let attribute = $(el).attrSync(name);
// Get multiple attributes
let attributes = $(el).attrSync([...name]);Parameters
name: String - The attribute name.Return
value: Any - The value of the named attribute.values: Object - A key/value hash of the listed attributes.Get the attribute on an <input /> element.
// Set a single attribute
let value = $(el).attrSync('id');
// email-input// Remove a single attribute
$(el).attrSync(name, false);
// Remove multiple attributes
$(el).attrSync({
[name]: false,
});Parameters
name: String - The attribute name.Return
this - The Play UI instance.Unset an element's ID attribute.
$(el).attrSync('id', false);// Add a single token to an attribute
$(el).attrSync(name, token, mutation === true);
// Add multiple tokens to an attributes
$(el).attrSync(name, [ token, ... ] mutation === true);
$(el).attrSync(name, {
[token]: mutation === true,
});
// Remove a token from a single delimited attribute
$(el).attrSync(name, token, mutation === false);
// Remove multiple tokens to an attributes
$(el).attrSync(name, [ token, ... ] mutation === false);
$(el).attrSync(name, {
[token]: mutation === false,
});Parameters
name: String - The attribute name to modify.token: String - The attribute token to add or remove.mutation: Boolean - The add/remove directive. When true, the given token is added to the attribute's value. When false, the given token is removed from the attribute's value.Return
this - The Play UI instance.Modify an element's class attribute, then confirm the operation.
<div class="class1 class2" role="article"></div>let el = document.querySelector('.class1');
// Insert a class entry
$(el).attrSync('class', 'class3', true);
// Confirm the operation
console.log($(el).attrSync('class')); // class1 class2 class3Toggle icon classes on an element.
<i class="volume-icon bi bi-volume-up"></i>let volumeIconElement = document.querySelector('.volume-icon');
let isMute = false;
$(volumeIconElement).on('click', e => {
$(el).attrSync('class', {
'bi-volume-mute': isMute,
'bi-volume-up': !isMute,
});
isMute = !isMute;
});The .attrSync() instance method is internally based on the standalone dom/attrSync() function which may be used statically.
const { attrSync } = $.dom;import { attrSync } from '@webqit/playui-js/src/dom/index.js';.class()This method is an alias of the .classSync() method. See .classSync() for documentation.
The .class() instance method is internally based on the standalone dom/classSync() function which may be used statically.
const { classSync: _class } = $.dom;import { classSync as _class } from '@webqit/playui-js/src/dom/index.js';.classAsync()This method is used to asynchronously modify or match an element's class list. It provides convenience over using the attrAsync() method to modify an element's class attribute.
The suffix Async differentiates this method from its Sync counterpart - classSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Add member classes
await $(el).classAsync(class, mutation === true);
await $(el).classAsync([ class, ... ], mutation === true);
await $(el).classAsync({
[class]: mutation === true,
});
// Remove member classes
await $(el).classAsync(class, mutation === false);
await $(el).classAsync([ class, ... ], mutation === false);
await $(el).classAsync({
[class]: mutation === false,
});Parameters
class: String - The class to add or remove.mutation: Boolean - The add/remove directive. When true, the given string is added to the class list. When false, the given string is removed from the class list.Return
this - The Play UI instance.Add member classes to an element, then confirm operation.
<div class="class1 class2"></div>let el = document.querySelector('.class1');
$(el).classAsync('class3 class4', true).then(Sel => {
// Confirm operation
console.log($el.attrSync('class')); // class1 class2 class3 class4
});Toggle icon classes on an element.
<i class="volume-icon bi bi-volume-up"></i>let volumeIconElement = document.querySelector('.volume-icon');
let isMute = false;
$(volumeIconElement).on('click', e => {
$(el).classAsync({
'bi-volume-mute': isMute,
'bi-volume-up': !isMute,
});
isMute = !isMute;
});// See if one pr more class exists
var exists = await $(el).classAsync(classList);Parameters
classList: String|Array - One or more class names.Return
exists: Boolean - This is true if all listed classes exist.Assert that the given class names exist.
<div class="class1 class2 class3"></div>let el = document.querySelector('.class1');
// Match classes
console.log(await $(el).classAsync('class1')); // true
console.log(await $(el).classAsync('class1 class3')); // true
console.log(await $(el).classAsync('class1 class4')); // false
// As an array
console.log(await $(el).classAsync(['class1 class3'])); // true
console.log(await $(el).classAsync(['class1', 'class3'])); // true
console.log(await $(el).classAsync(['class1', 'class4'])); // false
// Mixed
console.log(await $(el).classAsync(['class1', 'class3 class2'])); // trueThe .classAsync() instance method is internally based on the standalone dom/classAsync() function which may be used statically.
const { classAsync } = $.dom;import { classAsync } from '@webqit/playui-js/src/dom/index.js';.classSync()This method is used to modify or match an element's class list. It provides convenience over using the attrSync() method to modify an element's class attribute.
The suffix Sync differentiates this method from its Async counterpart - classAsync(). Unlike the Async counterpart, this method is not promised-based.
// Add member classes
$(el).classSync(class, mutation === true);
$(el).classSync([ class, ... ], mutation === true);
$(el).classSync({
[class]: mutation === true,
});
// Remove member classes
$(el).classSync(class, mutation === false);
$(el).classSync([ class, ... ], mutation === false);
$(el).classSync({
[class]: mutation === false,
});Parameters
class: String - The class to add or remove.mutation: Boolean - The add/remove directive. When true, the given string is added to the class list. When false, the given string is removed from the class list.Return
this - The Play UI instance.Add member classes to an element, then confirm operation.
<div class="class1 class2"></div>let el = document.querySelector('.class1');
$(el).classSync('class3 class4', true);
// Confirm operation
console.log($(el).attrSync('class')); // class1 class2 class3 class4Toggle icon classes on an element.
<i class="volume-icon bi bi-volume-up"></i>let volumeIconElement = document.querySelector('.volume-icon');
let isMute = false;
$(volumeIconElement).on('click', e => {
$(el).classSync({
'bi-volume-mute': isMute,
'bi-volume-up': !isMute,
});
isMute = !isMute;
});// See if one pr more class exists
var exists = $(el).classSync(classList);Parameters
classList: String|Array - One or more class names.Return
exists: Boolean - This is true if all listed classes exist.Assert that the given class names exist.
<div class="class1 class2 class3"></div>let el = document.querySelector('.class1');
// Match classes
console.log($(el).classSync('class1')); // true
console.log($(el).classSync('class1 class3')); // true
console.log($(el).classSync('class1 class4')); // false
// As an array
console.log($(el).classSync(['class1 class3'])); // true
console.log($(el).classSync(['class1', 'class3'])); // true
console.log($(el).classSync(['class1', 'class4'])); // false
// Mixed
console.log($(el).classSync(['class1', 'class3 class2'])); // trueThe .classSync() instance method is internally based on the standalone dom/classSync() function which may be used statically.
const { classSync } = $.dom;import { classSync } from '@webqit/playui-js/src/dom/index.js';.getTextNodes()This method is used to get all text nodes within an element.
let textNodes = $(el).getTextNodes();Return
textNodes: Array - The text nodes found; each an instance of Text.Return all text nodes in the document.
let textNodes = $(document.body).getTextNodes();
textNodes.forEach(node => {
// Show text content
console.log(node.wholeText);
// Replace text content
node.textContent = 'New text content.';
});The .getTextNodes() instance method is internally based on the standalone dom/getTextNodes() function which may be used statically.
const { getTextNodes } = $.dom;import { getTextNodes } from '@webqit/playui-js/src/dom/index.js';.html()This method is an alias of the .htmlSync() method. See .htmlSync() for documentation.
The .html() instance method is internally based on the standalone dom/htmlSync() function which may be used statically.
const { htmlSync: html } = $.dom;import { htmlSync as html } from '@webqit/playui-js/src/dom/index.js';.htmlAsync()This method is used to asynchronously set or get an element's HTML/XML content. It is the programmatic alternative to Element.innerHTML. Additionally, when this function receives undefined for a set operation, it is converted to an empty string.
The suffix Async differentiates this method from its Sync counterpart - .htmlSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Set HTML content of an element
await $(el).htmlAsync(content);Parameters
content: String|Node - The text or HTML content, or some DOM node, to set.Return
this - The Play UI instance.Replace an element's content with some HTML markup.
let div = '<div>Playful people!</div>';
$(el).htmlAsync(div);// Get HTML content of an element
let content = await $(el).htmlAsync();Return
content: String - The element's HTML content.Get an element's HTML content.
let content = await $(el).htmlAsync();
// <div>Playful people!</div>The .htmlAsync() instance method is internally based on the standalone dom/htmlAsync() function which may be used statically.
const { htmlAsync } = $.dom;import { htmlAsync } from '@webqit/playui-js/src/dom/index.js';.htmlSync()This method is used to set or get an element's HTML/XML content. It is the programmatic alternative to Element.innerHTML. Additionally, when this function receives undefined for a set operation, it is converted to an empty string.
The suffix Sync differentiates this method from its Async counterpart - .htmlAsync(). Unlike the Async counterpart, this method is not promised-based.
// Set HTML content of an element
$(el).htmlSync(content);Parameters
content: String|Node - The text or HTML content, or some DOM node, to set.Return
this - The Play UI instance.Replace an element's content with some HTML markup.
let div = '<div>Playful people!</div>';
$(el).htmlSync(div);// Get HTML content of an element
let content = $(el).htmlSync();Return
content: String - The element's HTML content.Get an element's HTML content.
let content = $(el).htmlSync();
// <div>Playful people!</div>The .htmlSync() instance method is internally based on the standalone dom/htmlSync() function which may be used statically.
const { htmlSync } = $.dom;import { htmlSync } from '@webqit/playui-js/src/dom/index.js';The main Play UI constructor is used to derive elements from a number of input formats and return a Play UI instance for them. It is a constructable function that can be instantiated either with the new keyword (new $()) or via a static call ($()).
// Pass in a CSS selector, and an optional query context
$(selector[, queryContext]);Parameters
selector - String: A CSS selector.queryContext - Element|Document: A context within which to run the query. This defaults to the document in the current window.The document in context.
<body>
<div>
<span></span>
</div>
<div>
<span></span>
</div>
<p>
<span></span>
</p>
</body>Select all div elements.
let $divs = $('div').toArray(); // .length: 2Select all span elements within a div element.
let $spans = $('div', divs[0]).toArray(); // .length: 1The above works as when the native Document.querySelectorAll() / Element.querySelectorAll() method os used except that $() internally polyfills the CSS :is(), (:matches(), :any()) pseudo-class functions.
let $spans = $(':is(div, p) > span').toArray(); // .length: 3// Pass in an HTML markup
$(markup);Parameters
markup - String: An HTML markup.Translate an HTML markup to actual elements.
let $divs = $('<div></div><div></div>').toArray(); // .length: 2// Accept an actual element instance
$(element);
// Accept a list of actual element instances
$([...element]);
// Accept an instance of NodeList
$(nodeList);Parameters
element - Element: A DOM Element.nodeList - NodeList: A DOM NodeList object.Accept an actual element.
let result = document.querySelector('div');
let $divs = $(result).toArray(); // .length: 1Accept a NodeList result.
let result = document.querySelectorAll('div');
let $divs = $(result).toArray(); // .length: 2.itemize()This method is an alias of the .list() method. See .list() for documentation.
The .itemize() instance method is internally based on the standalone dom/itemize() function which may be used statically.
const { itemize } = $.dom;import { itemize } from '@webqit/playui-js/src/dom/index.js';.prepend()This method is an alias of the .prependSync() method. See .prependSync() for documentation.
The .prepend() instance method is internally based on the standalone dom/prependSync() function which may be used statically.
const { prependSync: prepend } = $.dom;import { prependSync as prepend } from '@webqit/playui-js/src/dom/index.js';.prependAsync()This method is used to asynchronously prepend content to an element. It works exactly the same as the native ParentNode.prepend() except that when the implied content is undefined, it is converted to an empty string.
The suffix Async differentiates this method from its Sync counterpart - .prependSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Prepend content(s) to an element
await $(el).prependAsync(content[, ...content]);Parameters
content: String|Node - The text or HTML content, or some DOM node, to prepend.Return
this - The Play UI instance.Prepend an element node and some text content to an element.
let div = document.createElement("div");
$(el).prependAsync('!', 'people', ' ', 'Playful', div);The .prependAsync() instance method is internally based on the standalone dom/appendAsync() function which may be used statically.
const { prependAsync } = $.dom;import { prependAsync } from '@webqit/playui-js/src/dom/index.js';.prependSync()This method is used to prepend content to an element. It works exactly the same as the native ParentNode.prepend() except that when the implied content is undefined, it is converted to an empty string.
The suffix Sync differentiates this method from its Async counterpart - .prependAsync(). Unlike the Async counterpart, this method is not promised-based.
// Prepend content(s) to an element
$(el).prependSync(content[, ...content]);Parameters
content: String|Node - The text or HTML content, or some DOM node, to prepend.Return
this - The Play UI instance.Prepend an element node and some text content to an element.
let div = document.createElement("div");
$(el).prependSync('!', 'people', ' ', 'Playful', div);The .prependSync() instance method is internally based on the standalone dom/prependSync() function which may be used statically.
const { prependSync } = $.dom;import { prependSync } from '@webqit/playui-js/src/dom/index.js';.prependToAsync()This method is used to asynchronously prepend matched elements to target elements.
The suffix Async differentiates this method from its Sync counterpart - .prependToSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
await $(el).prependToAsync(target);Parameters
target: String|Element - A CSS selector of the element, or the element itself Element, to prepend to.Return
this - The Play UI instance.Prepend some dynamically-created nodes to document body.
$('<h1>Playful people!</h1>').prependToAsync(document.body);Prepend an existing div to multiple targets. The div is cloned into all targets except the last target.
let div = document.querySelector('div');
$(div).prependToAsync('.multiple');The .prependToAsync() instance method is internally based on the standalone dom/prependToAsync() function which may be used statically.
const { prependToAsync } = $.dom;import { prependToAsync } from '@webqit/playui-js/src/dom/index.js';.prependToSync()This method is used to prepend matched elements to target elements.
The suffix Sync differentiates this method from its Async counterpart - .prependToAsync(). Unlike the Async counterpart, this method is not promised-based.
$(el).prependToSync(target);Parameters
target: String|Element - A CSS selector of the element, or the element itself Element, to prepend to.Return
this - The Play UI instance.Prepend some dynamically-created nodes to document body.
$('<h1>Playful people!</h1>').prependToSync(document.body);Prepend an existing div to multiple targets. The div is cloned into all targets except the last target.
let div = document.querySelector('div');
$(div).prependToSync('.multiple');The .prependToSync() instance method is internally based on the standalone dom/prependToSync() function which may be used statically.
const { prependToSync } = $.dom;import { prependToSync } from '@webqit/playui-js/src/dom/index.js';.text()This method is an alias of the .textSync() method. See .textSync() for documentation.
The .text() instance method is internally based on the standalone dom/textSync() function which may be used statically.
const { textSync: text } = $.dom;import { textSync as text } from '@webqit/playui-js/src/dom/index.js';.textAsync()This method is used to asynchronously set or get an element's text content. It is the programmatic alternative to Element.innerText. Additionally, when this function receives undefined for a set operation, it is converted to an empty string.
The suffix Async differentiates this method from its Sync counterpart - .textSync(). Unlike the Sync counterpart, this method is promised-based. See Async UI.
// Set text content of an element
await $(el).textAsync(content);Parameters
content: String - The text content to set.Return
this - The Play UI instance.Replace an element's content with some text.
let text = 'Playful people!';
$(el).textAsync(text);// Get Text content of an element
let content = await $(el).textAsync();Return
content: String - The element's text content.Get an element's text content.
let content = await $(el).textAsync();
// Playful people!The .textAsync() instance method is internally based on the standalone dom/textAsync() function which may be used statically.
const { textAsync } = $.dom;import { textAsync } from '@webqit/playui-js/src/dom/index.js';.textSync()This method is used to set or get an element's text content. It is the programmatic alternative to Element.innerText. Additionally, when this function receives undefined for a set operation, it is converted to an empty string.
The suffix Sync differentiates this method from its Async counterpart - .textAsync(). Unlike the Async counterpart, this method is not promised-based.
// Set text content of an element
$(el).textSync(content);Parameters
content: String - The text content to set.Return
this - The Play UI instance.Replace an element's content with some text.
let text = 'Playful people!';
$(el).textSync(text);// Get Text content of an element
let content = $(el).textSync();Return
content: String - The element's text content.Get an element's text content.
let content = $(el).textSync();
// Playful people!The .textSync() instance method is internally based on the standalone dom/textSync() function which may be used statically.
const { textSync } = $.dom;import { textSync } from '@webqit/playui-js/src/dom/index.js';Classes in this category.
class Transaction {}This class lets us create rollback points while manipulating an element.
let transaction = new Transaction(el, props, readCallback, writeCallback);Parameters
el: Element - The element that will be modified.
props: String|Array - A property or list of properties that describes the operation on the element.
readCallback: function(el, props) - A function that is called to capture the state of the element using the listed props.
Parameters
el: Element - The element being operated on.props: Array - An array of the properties passed to the instance.Return
Object - A key/value hash for the listed properties.
Promise - A promise that should resolve to the object above.
This return value is what the transaction's savepoint() instance method returns when called.
writeCallback: function(el, record) - A function that is called to re-apply the recorded state of the element as previously derived by the readCallback function.
Parameters
el: Element - The element being operated on.record: Object - The recorded state of the element as previously derived by the readCallback function.Return
Any - Any value may be returned and will not be used.
Promise - A promise that may resolve to anything.
This return value is what the transaction's rollback() and apply() instance methods return when called.
Return
Transaction - The Transaction instance.Below, we modify an element's CSS properties and later roll back the element to its initial state.
Define the element's stylesheet- and inline-based CSS:
<style>
div {
background-color: yellow;
}
</style>
<div id="el" style="color:red"></div>Start a transaction:
// The readCallback will read the INLINE values of the listed properties
// This state is what will be restored on a call to transaction.rollback()
// Notice the "inline" flag, which tells cssSync() to read INLINE CSS
const readCallback = (el, props) => {
return $(el).cssSync(props, {inline: true});
};
// The writeCallback will restore the INLINE values of the listed properties previously stored
// It is triggered by a call to transaction.rollback() and to transaction.apply()
const writeCallback = (el, record) => {
return $(el).cssSync(record);
};
// Obtaine a Transaction instance
let transaction = $('#el').transaction(['background-color', 'color'], readCallback, writeCallback);Do some modifications and create savepoints along the way:
const el = document.querySelector('#el');
// Create a savepoint for the initial state of the element - savepoint1
// We can rollback to this point later
transaction.savepoint();
// Alter the element's computed style
el.style.color = 'green';
el.style.backgroundColor = 'black';
// Create a savepoint - savepoint2
// We can rollback to this point later
transaction.savepoint();
// Alter the element's computed style further
el.style.color = 'brown';
el.style.backgroundColor = 'teal';
// Create a savepoint - savepoint3
// We can rollback to this point later
transaction.savepoint();Rollback to a savepoint
// Rollback to anypoint after some time
setTimeout(() => {
// Rollback all the way to the element's initial state
transaction.rollback(0);
// Now background-color should fallback to yellow
// And color should be back to red
}, 2000);In the code above, if another part of the app had changed one of those properties after the last savepoint we made, then the call to rollback() would have overridden those foreign changes to restore the element to the specified savepoint.
To automatically detect foreign changes and leave them untouched, we would set the preserveCurrentState parameter of the rollback() method to true. (The readCallback function will be called again to take the element's current state for comparison.)
// The following changes were made after our last savepoint
el.style.color = 'brown';
// Rollback to savepoint2
setTimeout(() => {
// Rollback all the way to the element's initial state
transaction.rollback(0, true);
// Now, color will be left at 'brown'
}, 2000);.length: Int - Gives the number of savepoints in the transaction.Check out Transaction's methods.
.apply()The
transaction.apply()method.
This method is used to apply a new state to the element in a transaction. It is just another way to call the writeCallback function that was used to create the instance.
transaction.apply(state);Parameters
state: Object - A new state object that is passed to the instance's writeCallback.Return
Any - The return value of the transaction's writeCallback function.Obtain an instance of an ongoing transaction and call .apply(). Below, we build on the usage example on the Transaction page. Here we use the .apply() method to apply the CSS properties in that example.
ananimationi.apply({
color: 'brown',
backgroundColor: 'teal',
});.commit()The
transaction.commit()method.
This method is used to commit up to a savepoint in a transaction. It is used to certify that all records up to the specified savepoint are permanent changes.
transaction.commit(savepoint = 0);savepoint: Int - The savepoint to commit up to. 0 refers to the record of the first call to .savepoint(); 1 to the second call; and so on.Return
this - The Transaction instance.Obtain an instance of an ongoing transaction and call .commit(). Below, we build on the usage example on the Transaction page. Here we use the .commit() method to commit all savepoints. Calling the transaction's .rollback() method after this point will have no effect.
ananimationi.commit(0);.rollback()The
transaction.rollback()method.
This method is used to roll back up to a savepoint in a transaction. It re-applies the previously recorded state of the element by calling the writeCallback function that was used to create the instance. The complementary readCallback function will also be involved if the preserveCurrentState parameter is set to true.
transaction.rollback(savepoint = 0, preserveCurrentState = false);Parameters
savepoint: Int - The savepoint to roll back to. 0 refers to the record of the first call to .savepoint(); 1 to the second call; and so on.preserveCurrentState: Boolean - Specifies whether or not to detect and preserve any additional changes made after the last call to savepoint().Return
Any - The return value of the writeCallback function.See the Transaction class.
.savepoint()The
transaction.savepoint()method.
This method is used to create a savepoint from the current state of an element in a transaction. It takes records by calling the readCallback function that was used to create the instance.
transaction.savepoint();Return
Any - The return value of the readCallback function.See the Transaction class.
.transaction()This method is used to start a transaction on an element for operations that eventually might need to be rolled back. It is a convenient way to use the Play UI's Transaction class.
let transaction = $(el).transaction(props, readCallback, writeCallback);Parameters
props: String|Array - A property or list of properties that describes the operation on the element.readCallback: function(el, props) - A function that is called to capture the state of the element using the listed props. See the Transaction class.writeCallback: function(el, record) - A function that is called to re-apply the recorded state of the element as previously derived by the readCallback function. See the Transaction class.Return
Transaction - The Transaction instance.See the Transaction class.
The .transaction() instance method is internally based on the standalone misc/transaction() function which may be used statically.
const { transaction } = $.misc;import { transaction } from '@webqit/playui-js/src/misc/index.js';class Animation {}This class provides an intuitive way to use the native Web Animations API (WAAPI).
let animation = new Animation(element, effect[, timing = {}]);Parameters
element: Element - A DOM element.effect: Array|Object|String - The effect to play. This could be a standard keyframes array, a CSS rules object, or a stylesheet-based animation name.timing: Object - Options for the animation.duration: Number - The animation's duration in milliseconds.fill: String - The element's final state on finish; one of none (default), forwards, both.delay: Number - The animation's delay in milliseconds before playing.endDelay: Number - The animation's delay in milliseconds after playing.direction: String - The animation's direction; one of normal (default), reverse, alternate, alternate-reverse.easing: String - The rate of the animation's change over time; one of linear (default), ease, ease-in, ease-out, ease-in-out, or a custom cubic-bezier value like cubic-bezier(0.42, 0, 0.58, 1).iterations: Number - The number of times the animation should repeat.iterationStart: Number - At what point in the iteration the animation should start.cancelForCss: Boolean - (Specific to this class) Whether or not to cancel the animation on finish for subsequent CSS rules on the element to take effect. By default, properties animated with WAAPI cannot be modified with CSS. Setting cancelForCss to true fixes it. Create and play an animation.
let el = document.querySelector('#el');
let animation = new Animation(el, [{opacity:1}, {opacity:0}], {duration:600});
animation.play().then(el => {
console.log('The end!');
});Animation provides the following rich set of features over WAAPI:
Support for single-frame keyframes. Animation will automatically derive the animation's first frame from the element's current state.
// Fade out from current opacity level
let animation = new Animation(el, {opacity: 0}, timing);Support for CSS keyframes. Animation can play animations defined in the document's stylesheets. Just mention an animation name.
<style>
@keyframes fadeout {
0% { opacity: 1;}
100% { opacity: 0;}
}
</style>// Play the animation from stylesheet
let animation = new Animation(el, 'fadeout', timing);Support for auto height and width. Animation accepts and automacally computes the keyword auto for the width and height properties.
<div style="width:0px"></div>// Expand to the element's real size at "auto"
let animation = new Animation(el, {width: 'auto'}, timing);Automatic units for unit-based CSS properties. Animation will automacally suffix numeric values with px for properties like top that don't go without units.
// Help add "px" to the value for width
let animation = new Animation(el, {width: 50}, timing);Support for shortform rules. Animation will accept an object or array for the following shortforms: inset, margin, padding.
// Destructure the following object into their individual properties
let animation = new Animation(el, {inset: {top: 50, left: 100}}, timing);
// Here we actually mean
let animation = new Animation(el, {top: 50, left: 100}, timing);
// ---------------
// Destructure the following array into their individual properties
let animation = new Animation(el, {inset: [50, 100, 75, 125,]}, timing);
// Here we actually mean
let animation = new Animation(el, {top: 50, right: 100, bottom: 75, left: 125}, timing);
// All shortforms go in this order: top, right, bottom, leftSensible default timing parameters. Animation will automatically create sensible values for the animation timing where not defined.
// The timing object has the following defaults
{
duration: 400,
fill: 'both',
}Other usefull methods. See below.
Explore the instance methods of this class.
.cancel()The
animation.cancel()method.
This Animation instance method is used to cancel an animation. If there are oncancel handlers, they are called.
animation.cancel();Return
this - The Animation instance.Obtain an instance of an ongoing animation and call .cancel().
animation.cancel();.finish()The
animation.finish()method.
This Animation instance method is used to force an animation to the finished state. If there are onfinish handlers, they are called.
animation.finish();Return
this - The Animation instance.Obtain an instance of an ongoing animation and call .finish().
animation.finish();.oncancel()The
animation.oncancel()method.
This Animation instance method is used to bind a handler to the 'cancelled' state of an animation.
animation.oncancel(callback);Parameters
callback: function(element) - The function to call on cancel.
Parameters
element: Element - The DOM element of the animation instance.Return
this - The Animation instance.Bind an oncancel callback to an animation.
// Obtain an Animation instance
let animation = new Animation(el, {opacity: 0});
// Bind a callback
animation.oncancel(el => {
console.log('Animation on the ' + el.id + ' element cancelled!');
});
// Bind another callback if necessary
animation.oncancel(el => {
// Do something else
});.onfinish()The
animation.onfinish()method.
This Animation instance method is used to bind a handler to the 'finished' state of an animation.
animation.onfinish(callback);Parameters
callback: function(element) - The function to call on finish.
Parameters
element: Element - The DOM element of the animation instance.Return
this - The Animation instance.Bind an onfinish callback to an animation.
// Obtain an Animation instance
let animation = new Animation(el, {opacity: 0});
// Bind a callback
animation.onfinish(el => {
console.log('Animation on the ' + el.id + ' element finished!');
});
// Bind another callback if necessary
animation.onfinish(el => {
// Do something else
});.pause()The
animation.pause()method.
This Animation instance method is used to pause an animation.
animation.pause();Return
this - The Animation instance.Obtain an instance of an ongoing animation and call .pause().
animation.pause();.play()The
animation.play()method.
This Animation instance method is used to play an animation. This method is promised-based.
await animation.play();Return
this - The Animation instance.Obtain an instance of an ongoing animation and call .play().
let animation = new Animation(el, [{
opacity:1,
}, {
opacity:0,
}], {
duration:600
});
animation.play().then(animation => {
console.log('The end!');
// Call other methods
animation.reverse();
});.progress()The
animation.progress()method.
This Animation instance method is used to get the percentage progress of an animation.
let progress = animation.progress();Return
progress: Number - A number between 0 and 1, representing 0% and 100% respectively, of the animation's total timing. Here the total timing is calculated as delay + duration + endDelay.Get the progress of an animation at 350ms.
let animation = new Animation(el, [{
opacity:1,
}, {
opacity:0,
}], {
delay: 100,
duration:600,
});
setTimeout(() => {
console.log(animation.progress()); // About 0.5
}, 350);.ready()The
animation.ready()method.
This Animation instance method is used to bind a handler to the 'ready' state of an animation. This is useful as there are cases where the animation is created asynchronously.
animation.ready(readyCallback[, failureCallback = null]);Parameters
readyCallback: function(waapi, timing, firstFrame, lastFrame): The function to call on ready.
Parameters
waapi: Animation - The underlying WAAPI Animation instance.timing: Object - The instance's timing object.firstFrame: Object - The animation's firstFrame object. Especially useful where this has to be automatically derived by Ani.lastFrame: Object - The animation's lastFrame object. Especially useful where this has to be automatically resolved by Ani.failureCallback: function(errorMsg) - A function to call on fatal errors preventing the creation of the animation.
Parameters
errorMsg: String - The description of the error.Return
this - The Animation instance.Bind a ready callback to an animation.
// Obtain an Ani instance and call ready()
let animation = new Animation(el, {
width: 'auto',
});
aanimationni.ready((waapi, timing, firstFrame, lastFrame) => {
// Show the two keyframes
console.log(firstFrame, lastFrame);
});.reverse()The
animation.reverse()method.
This Animation instance method is used to reverse an animation.
animation.reverse();Return
this - The Animation instance.Obtain an instance of an ongoing animation and call .reverse().
animation.reverse();.seek()The
animation.seek()method.
This Animation instance method is used to seek to a percentage point in an animation.
animation.seek(point);Parameters
point: Number - A number between 0 and 1, representing 0% and 100% respectively, of the animation's total timing. Here the total timing is calculated as delay + duration + endDelay.Return
this - The Animation instance.Seek an animation to half its total duration.
let animation = new Animation(el, [{
opacity:1,
}, {
opacity:0,
}], {
delay: 100,
duration:600,
});
// Seek the animation to 350ms
animation.seek(0.5);class Event {}Instances of this class represent a DOM event or user gesture event.
let event = new Event(target, e);Parameters
target: Element - The DOM element on which the event happend.e: Event - The origin event object that this class will wrap. This is either a native browser event object or a Hammer.js event object describing a gesture event.event.type: String - (Readonly) Returns the type of the origin event passed to the constructor.event.target: Element - (Readonly) Returns the target element passed to the constructor.event.defaultPrevented: Boolean - (Readonly) Tells if the instance's .preventDefault() method has been called.event.propagationStopped: Boolean - (Readonly) Tells if the instance's .stopPropagation() method has been called.event.promises: null|Promise - (Readonly) Returns a Promise that consolidates all promises assigned by the event handlers using the instance's .promise() method. Returns null if no Promise has been received.event.e: Event - (Readonly) Returns the origin event object passed to the constructor.event.preventDefault()event.stopPropagation()event.promise()event.response()class Listener {}Instances of this class represent an event listener.
Instances are created internally.
listener.disconnect()listener.fire()Classes in this category.
This class provides a convenient way to control multiple Animation instances.
let timeline = new Timeline(animations[, params = {}]);Parameters
animations: Array - Zero or more Animation instances.params: Object - A few parameters for the timeline. (Currently none).Play/pause multiple animations in one call.
let ani1 = new Animation(el1, [{opacity:1}, {opacity:0}], {duration:600});
let ani2 = new Animation(el2, [{width:0}, {width:100}], {duration:900});
let timeline = new Timeline([ani1, ani2]);
timeline.pause();
setTimeout(() => {
timeline.play().then(() => {
console.log('The end; all animations!');
});
}, 1000);Runtime manipulation of timeline. Timeline allows you to add/remove animation instances at runtime without altering coordination and synchronization.
// Fade out from current opacity level
let timeline = new Timeline([ani1, ani2]);
// Kick off
timeline.play().then(() => {
console.log('The end; all animations!');
});
// On the fly
timeline.add(ani3);
timeline.remove(ani1);
// Yet, our play.then() will work as expectedExplore the instance methods of this class.
.add()The
timeline.add()method.
This Timeline instance method is used to add an Animation to the timeline.
timeline.add(animation);Return
this - The Timeline instance.Obtain a timeline instance and call .add().
// The timeline
let timeline = new Timeline;
// The animation instance
let animation = new Animation(el, {opacity:0});
// Add
timeline.add(animation);.cancel()The
timeline.cancel()method.
This Timeline instance method is used to cancel all animations in the timeline. If there are oncancel handlers, they are called. Animation instances added after this call are canclled immediately.
timeline.cancel(except = []);Parameters
except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .cancel().
timeline.cancel();.clear()The
timeline.clear()method.
This Timeline instance method is used to clear all animations from off the timeline.
timeline.clear(except = []);Parameters
except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .clear().
timeline.clear();.finish()The
timeline.finish()method.
This Timeline instance method is used to finish all animations in the timeline. If there are onfinish handlers, they are called. Animation instances added after this call are finished immediately.
timeline.finish(except = []);Parameters
except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .finish().
timeline.finish();.oncancel()The
timeline.oncancel()method.
This Timeline instance method is used to bind a handler to the 'cancelled' state of all animations in the timeline.
timeline.oncancel(callback);Parameters
callback: function(element) - The function to call on cancel.
Parameters
element: Element - The DOM element of the animation instance.Return
this - The Timeline instance.Bind an oncancel callback to all animations.
// The timeline
let timeline = new Timeline;
// The animation instance
let animation = new Animation(el, {opacity:0});
// Add
timeline.add(animation);
// Bind a callback
timeline.oncancel(el => {
console.log('Animation on the ' + el.id + ' element cancelled!');
});
// Bind another callback if necessary
timeline.oncancel(el => {
// Do something else
});
// Try cancel an animation
animation.cancel();.onfinish()The
timeline.onfinish()method.
This Timeline instance method is used to bind a handler to the 'finished' state of all animations in the timeline.
timeline.onfinish(callback);Parameters
callback: function(element) - The function to call on finish.
Parameters
element: Element - The DOM element of the animation instance.Return
this - The Timeline instance.Bind an onfinish callback to all animations.
// The timeline
let timeline = new Timeline;
// The animation instance
let animation = new Animation(el, {opacity:0});
// Add
timeline.add(animation);
// Bind a callback
timeline.onfinish(el => {
console.log('Animation on the ' + el.id + ' element finished!');
});
// Bind another callback if necessary
timeline.onfinish(el => {
// Do something else
});
// Try finish an animation
animation.finish();.pause()The
timeline.pause()method.
This Timeline instance method is used to pause all animations in the timeline. Animation instances added after this call are paused immediately.
timeline.pause(except = []);Parameters
except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .pause().
timeline.pause();.play()The
timeline.play()method.
This Timeline instance method is used to play all animations in the timeline. Animation instances added after this call are played immediately. This method is promise-based. The promise resolves at the time the animation with the highest timing completes. An animation's total timing withing the timeline could, in addition to its delay, duration, endDelay parameters, be affected by a direct play/play call, or its relative time of entering the timeline.
await timeline.play();Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .play().
let timeline = new Timeline;
timeline.play().then(() => {
console.log('The end!');
});
// Duration: 600ms
timeline.add(new Animation(el1, {opacity:0}, {duration: 600}));
setTimeout(() => {
// Duration: 600ms. But htis will finish in 900ms
timeline.add(new Animation(el2, {opacity:0}, {duration: 600}));
}, 300);.progress()The
timeline.progress()method.
This Animation instance method is used to get the average percentage progress of all animations in the timeline.
let progress = timeline.progress();Return
progress: Number - A number between 0 and 1, representing 0% and 100% respectively, of the timeline's calculated timing.Get the progress of an timeline at 450ms.
let timeline = new Timeline;
timeline.play().then(() => {
console.log('The end!');
});
// Duration: 600ms
timeline.add(new Animation(el1, {opacity:0}, {duration: 600}));
setTimeout(() => {
// Duration: 600ms. But htis will finish in 900ms
timeline.add(new Animation(el2, {opacity:0}, {duration: 600}));
}, 300);
// Total duration of timeline: 900ms
// Get the progress of an animation at 450ms.
setTimeout(() => {
console.log(timeline.progress()); // About 0.5
}, 450);.remove()The
timeline.remove()method.
This Timeline instance method is used to remove an Animation from the timeline.
timeline.remove(animation);Return
this - The Timeline instance.Obtain a timeline instance and call .remove().
// The timeline
let timeline = new Timeline;
// The animation instance
let animation = new Animation(el, {opacity:0});
// Add
timeline.add(animation);
// Then remove
timeline.remove(animation);.reverse()The
timeline.reverse()method.
This Timeline instance method is used to reverse all animations in the timeline. Animation instances added after this call are reversed immediately. But where the last call to timeline.reverse() restores the timeline to its original direction, Animation instances added are left as-is.
timeline.reverse(except = []);Parameters
except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Obtain an instance of an ongoing animation and call .reverse().
timeline.reverse();.seek()The
timeline.seek()method.
This Timeline instance method is used to seek to a percentage point in all animations in the timeline.
timeline.seek(point[, except = []]);Parameters
point: Number - A number between 0 and 1, representing 0% and 100% respectively, of an animation's total timing. Here the total timing is calculated as delay + duration + endDelay.except: Array - An optional list of Animation instances to excempt.Return
this - The Timeline instance.Seek an animation to half its total duration.
// The timeline
let timeline = new Timeline;
// The animation instance
let animation = new Animation(el, {opacity:0});
// Add
timeline.add(animation);
// Seek the timeline to half its total duration
timeline.seek(0.5);class UIRect {}Instances of this class represent the rendered rectangle of an element in the UI. And a good amount of transformation to this rect is possible.
let rect = new UIRectect(props[, params = {}]);Parameters
props: Object - Properties with to initalize the instance. These props are set as readonly properties of the instance. Standard properties are: left, top, bottom, right, width, height. Any additional properties are defined as non-enumerable on the instance.params: Object - The directives used during calculation of the given props.rect.params: Object - (Readonly) The original params object passed to the constructor.rect.offset: Object - (Readonly) A hash of the instance's .left and .top properties.rect.size: Object - (Readonly) A hash of the instance's .width and .height properties.rect[prop]: Any - (Readonly) Any other property (prop) in the original props object passed to the constructor.Parameters
element: Element - A DOM element.params: Object - Directives for the method.offsetOrigin: Any - This directive is used to specify the offset origin from which to calculate the top/left distances of the rendered rectangle for the element. Three origins can be used:client - offsets are calculated from the top/left origins of the screen. This is the default offset origin.page - offsets are calculated from the top/left origins of the page. Specify this origin by setting this directive to the keyword page or document, or to the document object.offset - offsets are calculated from the top/left origins of the element's offset parent. Specify this origin by setting this directive to true or the keyword offset, or to an instance of the element to use as origin (must be an ancestor of the subject element).Return
UIRect - An instance of UIRect.
rect.intersectionWith()rect.unionWith()rect.angleWith()rect.proximityWith()rect.rotationTo()rect.scaleTo()rect.translationTo()Play UI's event system can be hooked into to provide custom event implementations. For example, its tripletap, doubletap, and singletap gestures are custom implementations/variations of the tap gesture. But, a custom event can be as simple as an alias for another event. Play UI makes everything easy!
To create a custom event, import the CustomEvents object.
const { CustomEvents } = $.ui;import { CustomEvents } from '@webqit/playui-js/src/ui/index.js';To create an alias of an existing event:
// Simply map the custom event name to an existing event name
CustomEvents.hit = 'tap';
// Now we can bind to the "hit" event instead of "tap"
$(document.body).on('hit', event => {
console.log(event.type);
})To create an advanced custom event implementation, provide a class with two methods: setup() and teardown(). The setup() method will be called the first time the event is being bound to on the given element. This function will receive certain useful parameters, e.g. the emitter (being the most important). The teardown() method will be called the last time the event is being unbound off the element.
CustomEvents.tick = class {
// When the fisrt listenr of this event
// is attached to the element, we start ticking
setup(el, type, emitter, hammertime) {
this.el = el;
this.type = type;
this.hammertime = hammertime;
this.interval_id = setInterval(() => {
emitter.call();
}, 100);
}
// When the last listener of this
// event is removed, no need to keep ticking
teardown() {
clearInterval(this.interval_id);
}
};
// Now we can bind to the "tick" event
$(document.body).on('tick', event => {
console.log(event.type);
});.off()This method is used to unbind event or gesture handlers previously bound to an element using .on().
// Unbind all listeners bound to the following event name
// regardless of the event handler
$(el).off(eventName);
// Unbind the listener bound with the following event handler
$(el).off(eventName, originalHandler);
// Unbind the listener bound with the following event handler and tag
$(el).off(eventName, originalHandler, {tags:[...originalTags]});
// Unbind the listener bound with the following tag
// regardless of the event handler
$(el).off(eventName, null, {tags:[...originalTags]});Parameters
eventName: String - The event or gesture name.originalHandler: Function - The handler function originally used with .on().params: Object - Additional parameters.Return
this - The Play UI instance.Unbind a specific listener bound to doubletap.
$(document.body).off('doubletap', originalHandler);Unbind all listeners bound to doubletap.
$(document.body).off('doubletap');The params.tags parameter can be used to match listeners that were tagged by the .on() method.
$(el).off(eventName, originalHandler, {tags:['#tag']});The .off() instance method is internally based on the standalone ui/off() function which may be used statically.
const { off } = $.ui;import { off } from '@webqit/playui-js/src/ui/index.js';.on()This method is used to bind event or gesture handlers to an element. This works like the native EventTarget.addEventListener() function but adds support for user gestures and custom event implementation.
let listener = $(el).on(eventName, handler[, params = {}]);Parameters
eventName: String - The event or gesture name.
handler: function(event) - The handler function.
Parameters
event: Object - An Event object.params: Object - Additional parameters.
Return
listener: Listener - An instance of Listener.Handle gesture events.
$(document.body).on('doubletap', event => {
console.log('You doubletapped me!', event.details);
});Try using the trigger() method to fire the event.
// Trigger
$(document.body).trigger('doubletap');
// And we can add details
$(document.body).trigger('doubletap', {time:0});The params.tags parameter can be used to tag a listener. Tags are an array of values (strings, numbers, objects, etc) that can be associated with the listener for later use. See tags in action using the .off() method.
let listener = $(el).on(eventName, handler, {tags:['#tag']});Programmatically manipulate the returned listener object.
// Synthetically trigger the listener
listener.fire({
type: 'doubletap',
});
// Disconnect the listener
listener.disconnect();PlayUI uses the Hammer.js gesture library to support the following gestures out of the box. For details of these gestures, see the Hammer.js documentation.
Be sure to include Hammer.js on your page before trying to observe gestures.
The .on() instance method is internally based on the standalone ui/on() function which may be used statically.
const { on } = $.ui;import { on } from '@webqit/playui-js/src/ui/index.js';.play()This method is used to create and play an animation. This method is promise-based.
await $(el).play(effect[, timing = {}]);Parameters
effect: Array|Object|String - The effect to play. See Animation.timing: Object - Options for the animation. See Animation.Return
this - The Play UI instance.Play from Standard Keyframes. Below, we fade out an element using an array of keyframes.
let el = document.querySelector('#el');
$(el).play([{opacity:1}, {opacity:0}], {duration:600}).then($el => {
console.log('The end!');
});Play a CSS Transition. Below, we fade out an element by simply specifying a end-state keyframe. The starting keyframe for the animation is automatically derived from the element's current state.
$(el).play({opacity:0}, {duration:600}).then($el => {
console.log('The end!');
});Play a CSS Animation Name. Below, we fade out an element using an animation defined in the document's stylesheet.
<style>
@keyframes fadeout {
0% { opacity: 1;}
100% { opacity: 0;}
}
</style>$(el).play('fadeout', {duration:600}).then($el => {
console.log('The end!');
});The .play() instance method is internally based on the standalone ui/play() function which may be used statically.
const { play } = $.ui;import { play } from '@webqit/playui-js/src/ui/index.js';.rect()This method is used to obtain the rendered rectangle of an element in the UI for manipualtion. It is an alias of the UIRect.calculate() function.
let rect = $(el).rect(params = {});Parameters
params: Object - Directives for the method. See UIRect.calculate().Return
rect: UIRect - An instance of UIRect.Get the rect of a button element.
let rect = $('button').rect();Manipulate the rect.
The .rect() instance method is internally based on the standalone ui/rect() function which may be used statically.
const { rect } = $.ui;import { rect } from '@webqit/playui-js/src/ui/index.js';.trigger()This method is used to trigger event or gesture handlers previously bound to an element using .on().
let event = $(el).trigger(eventName[, details = {}]);Parameters
eventName: String - The event or gesture name.details: Object - Custom data to pass to the fired event handlers.Return
event: Event - An instance of Event.Programmatically fire gesture handlers.
let event = $(document.body).trigger('doubletap', {time:0});Inspect the returned event object to see how the fired listeners responded to the event.
if (event.defaultPrevented) {
// event.preventDefault() has been called by a handler
// Or a handler returned false
} else if (event.propagationStopped) {
// event.stopPropagation() has been called by a handler
// Or a handler returned false
} else if (event.promises) {
// event.promise() has been called by a handler
// Or a handler returned a promise
event.promises.then(() => {
// When all promises resolve
}).catch(() => {
// When any of the promises fail
});
}The .trigger() instance method is internally based on the standalone ui/trigger() function which may be used statically.
const { trigger } = $.ui;import { trigger } from '@webqit/playui-js/src/ui/index.js';The Play UI command-line tool.
$ playui bundleThe playui bundle command is used to automatically bundle static HTML files from the filesystem into HTML Modules.
Here, each directory will represent a module element and the files within it will be the module's exports. We will take the following directory structure as an example:
project-root
├-- views
├-- about
│ ├-- index.html <div class="page-container">About Page</div>
├-- home
├-- index.html <div class="page-container">Home Page</div>The goal is to translate the above layout into the following module structure and get it written to a single file that can be linked to:
<template name="views">
<template name="home">
<div exportgroup="index" class="page-container">Home Page</div>
</template>
<template name="about">
<div exportgroup="index" class="page-container">About Page</div>
</template>
</template>file: ./bundle.html
You can find a working example of a typical module structure right at OOHTML's documentation.
Now, on getting the files into a single bundle, we would next link to it as a remote content for a <template> element - the actual module element - in the main document.
<html>
<!--
Here, we link to the remote content
-->
<head>
<template name="main" src="./bundle.html"></template>
</head>
<!--
Here our application router would be dynamically pointing to either "home" or "about"
-->
<body template="main/views/about">
<import name="index"></import>
</body>
</html>That said, lets go on to bundle.
Syntax:
playui bundle
Navigate to project-root and run playui bundle. Two files should be reported bundled.
Remote content is now ready at ./bundle.html!
Now, beyond this point are so many other things we can do! And here is where a few configurations come in!
Run playui config bundler to walk down the options.
On completing the options below, the
playui configcommand will save the configurations to a JSON file at./.webqit/playui-cli/config/bundler.json. Subsequent calls toplayui bundlewill be based on the saved configurations. And subsequent calls toplayui config bundlerwill pull up the saved configurations for update.
[ENTRY_DIR]This specifies the entry point into the filesystem - the source directory. The default value is ./, which resolves to the current working directory (CWD) on the terminal.
This is good for pointing the bundler to the actual views (or equivalent) folder in the project directory. E.g. ./views. (An absolute path may also be used.)
To specify multiple entry directories, slot in the exact string [name] as a placeholder on a segment in the path. Bundler will loop through all folders at that level in the directory to resolve the placeholder and obtain a final path. Specifying ./views/[name] as the entry directory, for example, will equate to running playui bundle on both ./views/about and ./views/home.
[OUTPUT_FILE]This specifies the file name of the output bundle. The default value is ./bundle.html, which is resolved relative to [ENTRY_DIR].
This is good for directing the output bundle to the actual public (or equivalent) folder of the application. E.g. ./public/bundle.html. (An absolute path may also be used.)
Where multiple source directories are specified in the [ENTRY_DIR] option above, this option will require a [name] placeholder, this time, to specify a unique output file each for the source directories. Specifying ./public/[name].bundle.html as the output file, for example, will equate to saving the output bundle of ./views/about to ./public/about.bundle.html, and the output bundle of ./views/home to ./public/home.bundle.html.
[ASSETS_STORAGE_BASE]This specifies the output directory for images or other assets bundled from the source directory. (See Bundling Assets below.) The default value is ./, which is resolved relative to [ENTRY_DIR], and which means assets will not be copied to any new location. If set to empty, the same directory as [OUTPUT_FILE]'s is used.
This is good for directing assets like images to the actual place in the public (or equivalent) folder of the application. E.g. ./public/assets. (An absolute path may also be used.)
This option supports the same [name] placeholder as used in the [ENTRY_DIR] option, this time, to specify a unique assets storage directory each for the source directories. Specifying ./public/assets/[name] as the assets storage path, for example, will equate to saving the assets bundled at ./views/about to ./public/assets/about, and the assets bundled at ./views/home to ./public/assets/home.
[ASSETS_PUBLIC_BASE]This specifies the HTTP path that maps to [ASSETS_STORAGE_BASE] in the filesystem. The default value is /, which is assumed to map to the public (or equivalent) folder of the application. The src (or equivalent) attribute of every asset bundled will be prefixed with this path.
This is good for aligning the public path for assets with the internal [ASSETS_STORAGE_BASE] path. E.g. /assets, where [ASSETS_STORAGE_BASE] had been set to ./public/assets.
[MAX_DATA_URL_SIZE]This specifies the upper limit of the file size under which to inline the contents of an image file or other asset as data URLs. (See Bundling Assets below.) The default value is 1024, in bytes. Assets smaller than this size will be bundled with data URLs.
This is good for having small image files embed their own content instead of having them create additional HTTP requests on the page.
[LOADERS]This specifies an optional list of loaders for the bundling operation. (See Loaders.) The default value is an empty object {}.
This is good for extending the capabilities of the bundler to custom-load certain file formats that are not natively provided for.
Skip where not apply. Or follow the prompt to interactively specify loaders, optionally along with their arguments or flags. The following options are presented recursively:
[name] - The path to a function, or the name of an installed npm package, that is a Play UI loader. (The bundler imports loaders using the ES6 import() syntax.)
To refer to the bundler's built-in loaders, like the markdown-to-HTML loader (md-loader), simply add the prefix default: to the loader's bare name. E.g. default:md-loader.
[args] - Optional list of parameters (arguments/flags) for a loader - each in name/value pair.
Skip where not apply. Or follow the prompt to interactively specify parameters. The following options are presented recursively:
[name] - The name of the parameter as required by a loader. E.g. flavor - in the default md-loader.[value] - The value of the parameter. E.g. github - for the flavor parameter above.[IGNORE_FOLDERS_BY_PREFIX]This specifies a comma-separated list of prefixes for certain types of folders to ignore. Folders with a name that begins with any of the listed prefixes are ingnored. The default value is an array of one prefix: dot ..
This is good for excluding certain system folders or dot directories like .git. Dot directories are automatically excluded by the default value.
[CREATE_OUTLINE_FILE]This specifies whether or not to generate a JSON outline of the bundle. The default value is create. The generated file is named after [OUTPUT_FILE]; e.g. ./bundle.html.json. Set to create_merge to merge the generated JSON outline with any previously generated one. Set to empty to disable outline generation.
This is good for programmatically traversing the module tree. Simply JSON.parse() the contents of ./bundle.html.json.
[MODULE_EXT]This specifies an extended tag name for the module element. This value will be set to the is attribute of the <template> elements generated by the bundler. The is empty by default.
This is good for automatically extending generated <template> elements. A value like special-module will generate <template is="special-module"></template> elements. Be sure to take into account the element.template setting in the OOHTML meta tag of the page where the bundle will be used.
[MODULE_ID_ATTR]This specifies the attribute name for designating the module ID. The default value is name which conforms to the default module ID attribute in the OOHTML spec.
This should generally only be changed to align with the attr.moduleid setting in the OOHTML meta tag of the page where the bundle will be used.
[EXPORT_MODE]This specifies the syntax for designating the module exports within the generated <template> elements. The default value is attribute which translates to using the exportgroup attribute (or [EXPORT_GROUP_ATTR]) to designate module exports. Set to element to use the <export> element (or [EXPORT_ELEMENT]) instead. (See the two standard convetions.)
[EXPORT_GROUP_ATTR]This specifies the attribute name for designating the export ID in attribute mode. The default value is exportgroup which conforms to the default syntax in the OOHTML spec. E.g. <div exportgroup="export-id"></div>.
This should generally only be changed to align with the attr.exportgroup setting in the OOHTML meta tag of the page where the bundle will be used.
This option is only shown when the export mode option is set to
attribute.
[EXPORT_ELEMENT]This specifies the tag name for designating module exports in element mode. The default value is export which conforms to the default syntax in the OOHTML spec. E.g. <export> <div></div> </export>
This should generally only be changed to align with the element.export setting in the OOHTML meta tag of the page where the bundle will be used.
This option is only shown when the export mode option is set to
element.
[EXPORT_ID_ATTR]This specifies the attribute name for designating the export ID in element mode. The default value is name which conforms to the default syntax in the OOHTML spec. E.g. <export name="export-id"> <div></div> </export>
This should generally only be changed to align with the element.export setting in the OOHTML meta tag of the page where the bundle will be used.
This option is only shown when the export mode option is set to
element.
While HTML modules are created by reading the file's contents, assets, like images, are handled differently. These files are copied from their location into the [ASSETS_STORAGE_BASE] directory to make them accessible to HTTP requests. An appropriate HTML element that points to this new location is automatically generated as the module export in the bundle. This is illustrated below.
We have an image file at project-root/assets/img and we have set the [ASSETS_STORAGE_BASE] to ./public, and the [OUTPUT_FILE] option to ./public.
project-root
│
├-- assets
│ ├-- img
│ ├-- image1.png
│
├-- views
├-- about
│ ├-- index.html <div class="page-container">About Page</div>
├-- home
├-- index.html <div class="page-container">Home Page</div>On running the playui bundle command, our final directory structure will be…
project-root
│
├-- assets
│ ├-- img
│ ├-- image1.png
│
├-- public
│ ├-- assets
│ │ ├-- img
│ │ ├-- image1.png
│ │
│ ├-- bundle.html
│
├-- views
├-- about
│ ├-- index.html <div class="page-container">About Page</div>
├-- home
├-- index.html <div class="page-container">Home Page</div>…and an <img> element pointing to the public location of image1.png is added as a module export to the bundle.
<template name="assets">
<template name="img">
<img exportgroup="image1" src="/assets/img/image1.png" />
</template>
</template>
<template name="views">
<template name="home">
<div exportgroup="index" class="page-container">Home Page</div>
</template>
<template name="about">
<div exportgroup="index" class="page-container">About Page</div>
</template>
</template>Taking things further, it is possible to bundle small images (or other assets) with inline data URLs. This way, the browser won't have to load them via HTTP request. Cutting down on the number of assets to load should greatly speed up the site's load time.
The Bundler just needs to know under what file size to use the data-URL format. Set the [MAX_DATA_URL_SIZE] option to a size measured in bytes. E.g. 2048. Assets below this size will now be bundled in data-URL format.
In the case of image1.png above, the generated module export would look like:
<img exportgroup="image1" src="data:image/png,%89PNG%0D%0A=" />Play UI loaders are packages that extend the capabilities of the OOHTML Bundler. Play UI comes with certain loaders built-in and also makes it possible to provide custom loaders.
Loaders are functions that are called with each file during the bundling process. Multiple loaders are made cascaded and a loader will be expected to call the next. This makes for an awesome processing pipeline for each file being bundled. But it also requires thoughtfulness in the order in which these loaders are specified.
By default, the main Play UI bundler only handles .html files and images (.ico, .png, .jpg, .jpeg, .svg). Then it features built-in loaders that extend the list.
md-loaderThe md-loader loader is used to load .md (markdown) files into HTML exports just the way regular HTML files are. It takes an initial step of converting the markdown content into HTML using the Showdown library, then goes ahead to add it to the bundle as a module export. Markdown links are automatically resolved to better work as HTML links. A few other transformations are supported through arguments/flags. (Learn more about specifying arguments/flags for a loader here.)
All parameters are optional.
base_url - Set this to a value that will be used as the base URL for relative links. This is similar to how the [ASSETS_PUBLIC_BASE] option works.outline_generation - Set this to a non-empty value to generate a JSON outline of the page's content. The generated outline will show up in the meta data for the file in the bundle's overall JSON outline.code_highlighting - Set this to a non-empty value to transform code blocks into stylable markup using the Showdown-Highlight utility. The transformed code blocks are highlighted in the UI on adding any of the Highlight.js CSS to the page.flavor - This equates to any of Showdown's three flavours: original, vanilla, github.md-loader automatically parses any found markdown metadata (defined at the top of the document between ««« and »»» or between --- and ---) into JSON and this will show up in the meta data for the file in the bundle's overall JSON outline. Below is an example metadata: ---
description: Page description.
---
# Page Title | h1 | h2 | h3 |
|:------|:-------:|--------:|
| 100 | [a][1] | ![b][2] |
| *foo* | **bar** | ~~baz~~ |The md-loader loader is used by specifying default:md-loader in the [LOADERS] config option.
Custom Loaders are easy to develop. They are basic functions that recieve the current file being processed along with a few paramters, to return a fully-formed module export markup.
export default function loadsCSS(resource, params, args, received, meta, next) {
if (received || !resource.endsWith('.css')) {
// Or let the flow continue
return next(received);
}
// Return a module export format
return '<style exportgroup="">...</style>';
}Parameters
resource: String - The filename of the resource being processed - relative to the current working directory (CWD).params: Object - The options object that the Bundler was initialized with. It also has an additional property indentation - a number which represents how deep in the source directory the given resource is. This number is 0 at the root of the source directory.args: Object - The args object defined specifically for the loader.received: String - The output forwarded (that is, next()ed) by the previous loader in the list, if any.meta: Object - The meta object for the given resource. Properties can be added and they will show up in the meta data for the file in the bundle's overall JSON outline.next: Function - A function that forwards control to the next loader in the list, if any, and if none, to the default internal loader. It accpets only one parameter, which is received by the next loader on its received parameter. (When any value passed this way reaches the internal loader, it is added to the bundle as-is without any further processing of the resource.)Return Value
Loaders are expected to return a valid markup string as the module export for the resource.
Loaders may throw exceptions, they will be gracefully handled, that is, formatted and printed to the console.
Custom loaders are used by specifying their filename in the [LOADERS] config option. Loaders installed as an npm package are used by specifying their package name.
$ playui configThe playui config command is used to configure other Play UI commands or a feature.
The playui config command is part of thoughtful strategies to make the developer experience on the command line great. Its sole purpose is to provide an interactive way to configure flags for other commands and to persist such configurations. It is indeed painstaking and error-prone to write commands with a long list of flags each time. The playui config command will eliminate this for you.
Syntax:
playui config <command>- where<command>is any of the other Play UI commands, or the ellipsis..., which lets you pick from a list.
Config will walk you through the configuration options for the specified command and save your configurations for repeat use. (Configurations are generally saved to a JSON file in the project-relative directory: ./.webqit/playui-cli/config/, except as otherwise stated in the documentation for a specific command.) Now, subsequent calls to playui config <command> will pull up the saved configurations for update. But, config files may also be updated, or even created, by hand.
To try, run playui config ..., pick a command from the list and follow the prompt. Be sure to consult the documentation for a command to achieve good configurations.
$ playui helpThe playui help command is used to show available Play UI commands.
Remembering things is hard. Run the playui help command anytime to show a list of available commands.
Syntax:
playui help.
Refer to the documentation of the command you want to use.
The Play UI JavaScript library offers a succinct API for working with the DOM and UI.
In the Play UI family:
The Play UI JavaScript library can be used either from a CDN or as an npm package.
Add the following script tag to your page to include the all-in-one Play UI module:
<script src="https://unpkg.com/@webqit/playui-js/dist/main.js"></script>The above tag loads Play UI into a global "WebQit" object.
<script>
const $ = window.WebQit.$;
</script>With npm available on your terminal, run the following command to install Play UI:
$ npm i @webqit/playui-jsImport and initialize the installed package:
// Import the initializer
import PlayUI from '@webqit/playui-js';
// Initialize
const $ = PlayUI();And you can selectively import Play UI's descrete parts to streamline your imports to your needs. The API reference has the import syntax for each of Play UI's functions. For example:
// Import a function...
import { htmlSync as html } from '@webqit/playui-js/src/dom/index.js';
// Supply an element as first argument...
html(selector, 'Play away!');Details are in the Quick Start guide.
The Play UI Command Line Interface is installable as an npm package.
With npm available on your terminal, run the following command to install Play UI CLI as a dev dependency to your project:
System Requirements: Node.js 12.0 or later
$ npm i -g @webqit/playui-cli --save-devThe -g flag makes it a global installation. It makes the playui command available from any location on your terminal. Omit this flag to install Play UI CLI to just your project directory.
To test, run playui help; an overview of available commands will be shown.
The API Reference or the Command Line Reference.
Play UI is a family of tools that brings a utility-based approach and a wholistic experience to UI development. This means: full UI authoring capabilities in the liberty and combinational power of standalone functionalities! Take an overview.
Although they share a family name, these are really independent libraries.
Play UI JavaScript is a resilient, jQuery-inspired, DOM and UI abstraction library. It offers simple, but powerful, JavaScript functions that do a good job at interacting with the DOM and UI, following the most-performant way. And it's a succint API surface you'll love! (.html(), .play(), .on(), .off(), etc.)
Play UI JavaScript is designed to meet a wide range of usage styles.
Include Play UI on any page and use as you would jQuery. Play UI looks and feels just like it!
Simply obtain the constructable Play UI function ($) as shown below.
If Play UI was loaded via a script tag:
// The constructable function would be available in a global WebQit object
const $ = window.WebQit.$;If Play UI was installed as a package:
// We would first call the initializer to obtain the constructable function
import PlayUI from '@webqit/playui-js';
const $ = PlayUI();Construct instances with the new operator or by calling the function statically.
With the new operator:
(new $(selector)).html('Some fun!');Statically:
$(selector).html('Some fun!');Now, while total parity with jQuery's design isn't the goal, there exists good similarity: .html(), .append(), .prepend(), .attr(), .css(), .data(), .on(), .off(), .trigger().
Use Play UI on the server with server-side DOM instances, such as the type provided by the jsdom library. (Think cases like server-side rendering, web crawling, or just server-side DOM manipulation.) Here is how that could look.
Create a window object:
// Utilities we'll need
import fs from 'fs';
import path from 'path';
// Import jsdom
import jsdom from 'jsdom';
// Read the HTML document file from the server
const documentFile = fs.readFileSync(path.resolve('./index.html'));
// Instantiate jsdom so we can obtain the "window" for building Play UI
// Detailed instruction on setting up jsdom is available in the jsdom docs
const JSDOM = new jsdom.JSDOM(documentFile.toString());
const window = JSDOM.window;Initialize Play UI with the window object passed in as its this context. (Note the PlayUI.call() syntax.):
// Import Play UI
import PlayUI from '@webqit/playui-js';
// Initialize
const $ = PlayUI.call(window);
// Query...
$(selector).append('Ready!');The per-window initialization approach makes it possible to have Play UI running in multiple window instances, if we need to, without getting weird behaviours.
Tie Play UI to multiple window instances:
const $ = PlayUI.call(window_1);
$('.some-element-in-document-1').append('This is for you!');const $$ = PlayUI.call(window_2);
$$('.some-element-in-document-2').append('This is for you!');Play UI's instance methods are internally based on certain core standalone functions which may be imported and used individually. The .on() instance method, for example, is based on the standalone $.ui.on() function.
const ( on ) = $.ui;import ( on ) from '@webqit/playui-js/src/ui/index.js';Standalone functions have their import syntax documented alongside their instance counterpart.
Generally, these standalone functions work the same way as their instance counterpart, except that they initially take an element selector as their first argument - where element selector is any of the input types accepted by the initializer $() function.
Compare:
$(selector).on('swipeleft', e => {
// Handle swipe gesture
});on(selector, 'swipeleft', e => {
// Handle swipe gesture
});If you were to run your code in a window context other than the global browser window, you could use the <Function>.call() syntax to pass in the window object as the this context for the function.
on.call(window, selector, 'swipeleft', e => {
// Handle swipe gesture
});However, functions obtained from the already initialized Play UI object $ automatically inherit the window of the Play UI object $.
// Import Play UI
import PlayUI from '@webqit/playui-js';
// Initialize
const $ = PlayUI.call(window);
// Worry no more about a window object
$.ui.on(selector, 'swipeleft', e => {
// Handle swipe gesture
});Note that functions that are normally chainable as instance methods are not chainable when used statically. But these functions will return whatever was the this context passed in using <Function>.call().
Surgically updating the UI is generally a costly operation for browsers. It happens when we write to the DOM and read from it in quick succession in a rendering cycle - causing document reflows, or better put, forced synchronous layout. (But a common word is layout thrashing.) This is covered in detail in this article on Web Fundamentals.
Play UI meets this challenge with a simple timing strategy that keeps UI manipulation in sync with the browser's rendering cycle. To do this, DOM operations are internally held in read/write queues, then executed in read/write batches within each rendering cycle, eliminating the forced synchronous layout problem. This is what happens under the hood with all of the Play UI functions that have the Async suffix; e.g htmlAsync(). The asynchronous nature of these functions bring them under the term Async UI.
The order of execution of the code below demonstrates the asynchronous nature of these functions.
// Set content
$(document.body).htmlAsync('Hi').then(() => {
console.log('Completed: write operation 1');
});
// Get content
$(document.body).htmlAsync().then(content => {
console.log('Completed: read operation 1');
});
// Set content
$(document.body).htmlAsync('Hi again').then(() => {
console.log('Completed: write operation 2');
});
// Get content
$(document.body).htmlAsync().then(content => {
console.log('Completed: read operation 2');
});
// ------------
// console
// ------------
Completed: read operation 1
Completed: read operation 2
Completed: write operation 1
Completed: write operation 2Notice that read operations are executed first, then write operations.
Where the order of execution matters, subsequent code could be moved into the then() block each of the async functions.
// Set content
$(document.body).htmlAsync('Hi').then(() => {
console.log('Completed: write operation 1');
// Get content
$(document.body).htmlAsync().then(content => {
console.log('Completed: read operation 1');
});
});
// ------------
// console
// ------------
Completed: write operation 1
Completed: read operation 1Now, where immediate DOM manipulation is still a necessity, the Sync counterpart of the functions above will be just as good.
// Set content
$(document.body).htmlSync('Hi');
console.log('Completed: write operation 1');
// Get content
$(document.body).htmlSync();
console.log('Completed: read operation 1');
// ------------
// console
// ------------
Completed: write operation 1
Completed: read operation 1Note that the Sync option is what is implied where no suffix is explicitly used in the function name.
$(document.body).html('Hi');
console.log('Completed: write operation 1');Play UI Command Line is a utility that lets you move certain aspects of UI authoring to a build process. It offers the automation that allows you to hand-author your UI in absolute free-form mode and then have everything automatically come to shape. And it's an experience at the command line you'll love!
Follow the installation guide to install the Play UI CLI.
Supercharge your UI templating! Author your HTML templates as standalone HTML files and automatically bundle them from the filesystem into shippable HTML modules.
Command: playui bundle.
Taking the liberty with Subscript? There's a way to have Subscript come off as Web Components - to give you the best of both worlds, without the difficulty of the latter!
Command: comming soon.
Take the process out of writing CSS! Instead of having to have every class already defined in CSS before using in HTML, try a process that automatically writes your CSS classes to file from looking in your HTML!
Command: comming soon.
The download options.