Skip to content

sQuery()

Jump to bottom
esr360 edited this page Apr 18, 2019 · 5 revisions 
sQuery(query, callback, defaults, custom, parser);
Param Type Info
query * The query to retrieve/pass DOM elements - this is the only required parameter
[callback] Function Function to call on each element returned from query
[defaults] Object Default configuration (will be merged with custom and passed to callback)
[custom] Object Custom configuration (will be merged with default and passed to callback)
[parser] Function Function to call on the merged default + custom object

Query

This parameter should be used to determine which HTML Element(s) from the DOM you are interested in. Throughout the Wiki, what you enter as the value for this parameter will be referred to as a Synergy Query.

A Synergy Query can be one of the following:

  • A string matching the name of a module - all elements that match the module name will be returned
  • A string representing a selector that will be passed to a document.querySelectorAll call
  • An HTML Element - only this element will be returned
  • A NodeList - all element nodes in the list will be returned
  • An array where the first value will be the query
  • An object which contains a name key to be treated as the module name - all elements that match the module name will be returned
Examples
<div class="foo" id="bar">...</div>

The below queries would all return the above HTML Element (learn more about the DOMNode method):

sQuery('foo').DOMNode;
sQuery('.foo').DOMNode;
sQuery(document.getElementById('bar')).DOMNode;
sQuery(document.querySelectorAll('.foo')).DOMNode;
sQuery(['foo']).DOMNode;
sQuery({name: 'foo'}).DOMNode;
Overriding Module Name

In the above example, the module name is foo. This means that foo will be used as the namespace for sQuery operations:

sQuery('foo', function(element) {
    sQuery(element).addModifier('buzz');
});

Resulting in:

<div class="foo foo-buzz" id="bar">...</div>

If you wanted to achieve the following result:

<div class="foo fizz-buzz" id="bar">...</div>

...you can override the module name like so:

  • target the element by passing an array with the first value as the Synergy Query
  • choose a new module name by passing it as the second value in the array
sQuery(['foo', 'fizz'], function(element) {
    sQuery(element).addModifier('buzz');
});

Callback

This parameter should be used to pass a reference to a function that will be called upon each HTML element matched by the query parameter.

callback(element, options)
Param Type Info
element HTMLElement Each HTML Element returned from the query parameter
options Object Object containing deeply merged defaults + custom objects
High-Level Example
<div id="myModule">...</div>
window.someOtherConfigObject = {
    someProperty: true;
}
var defaults = {
    someProperty: false;
}

sQuery(document.getElementById('myModule'), function(element, options) {
    if (options.someProperty) {
        element.style.color = red;
    }
}, defaults, someOtherConfigObject);
Result
<div id="myModule" style="color: red;">...</div>

Defaults

This parameter should be used to pass any default configuration for your module - it will be merged with any custom values passed via the optional custom parameter and passed to the callback parameter.

High-Level Example
<div class="myModule">...</div>
<div class="myModule">...</div>
var defaults = {
    someProperty = false;
}

function myModule(custom) {
    sQuery('myModule', function(element, options) {
        if (options.someProperty) {
            element.style.color = red;
        }
    }, defaults, custom); 
}

Custom

This parameter should be used to pass any custom configuration for your module - it will be merged with any default values passed via the defaults parameter and passed to the callback parameter.

High-Level Example
<div class="myModule">...</div>
<div class="myModule">...</div>
var defaults = {
    someProperty = false;
}

function myModule(custom) {
    sQuery('myModule', function(element, options) {
        if (options.someProperty) {
            element.style.color = red;
        }
    }, defaults, custom); 
}
myModule({
    someProperty: true
});
Result
<div class="myModule" style="color: red;">...</div>
<div class="myModule" style="color: red;">...</div>

Parser

This parameter should be used to pass a reference to a function that will be called upon the options object to create a new object that will be sent to the callback function.

High-Level Example
// Make all strings in `options` uppercase
function parser(options) {
    for (var option in options) {
        if (typeof option === 'String') {
            options[option] = option.toUpperCase();
        }
    }

    return options;
}
var options = {
    fizz: 'buzz';
}

sQuery('myModule', function(element, options) {
    console.log(options.fizz); // 'BUZZ'
}, options, someOtherConfigObject, parser);

Properties

Namespace

sQuery(query).namespace; // returns namespace of element(s) returned by `query`

Nodes

sQuery(query).nodes; // returns elements matched by `query`

Node

sQuery(query).node; // returns first element matched by `query`

Clone this wiki locally