jComponent / 06. Scopes
Updated: 10. September 2018
Author: Peter Širka

06. Scopes

Professional Support Chat with contributors

Scopes can simplify paths in HTML declaration. In other words: scopes can reduce paths in all nested components.

Quick navigation:

How does it work?

  • first you need to implement an element with data-jc-scope attribute
  • data-jc-scope can contain path or can be empty
<!-- WITHOUT SCOPE -->
<div>
    <div data-jc="textbox__users.form.firstname">Name</div>
    <div data-jc="textbox__users.form.age">Age</div>    
</div>

<!-- WITH SCOPE -->
<div data-jc-scope="users.form">
    <div data-jc="textbox__firstname">Name</div>
    <div data-jc="textbox__age">Age</div>    
</div>

Disallow scopes for selected components

jComponent supports data-jc-noscope="true" attribute which can disallow scope for the component.

<div data-jc-scope="users.form">

    <div data-jc="textbox__firstname">Name</div>
    <!-- path will be: users.form.firstname -->

    <div data-jc="textbox__age">Age</div>    
    <!-- path will be: users.form.age -->

    <!-- DISALLOW SCOPE -->
    <div data-jc="textbox__users.search" data-jc-nocope="true"></div>
    <!-- path will be: users.search -->

</div>

Isolated/Independent scopes with ! exclamation mark

Independent scopes can rewrite current scope. Independence is enabled by adding exclamation mark ! into the scope path data-jc-scope="!products.form".

<div data-jc-scope="users.form">

    <div data-jc="textbox__name">Name</div>
    <!-- path will be: users.form.name -->

    <!-- Independent scope -->
    <div data-jc-scope="!products.form">
        <div data-jc="textbox__name">Name</div>
        <!-- path will be: products.form.name -->
    </div>

    <!-- Inherited scope -->
    <div data-jc-scope="products.form">
        <div data-jc="textbox__name">Name</div>
        <!-- path will be: users.form.products.form.name -->
    </div>

</div>

Anonymous scope with ? question mark

Anonymous scopes are very good option for creating reusable independent web parts, e.g. Contact form, Subscriber form, etc..

  • jComponent generates random path for this scope
  • path will have more than 15 chars
  • path will be stored in window object
  • example: jmhjxgietazasfazfqxqb
<div data-jc-scope="?">

    <div data-jc="textbox__name">Name</div>
    <!-- path will be: random_path.name -->

</div>

<!-- EXAMPLE -->

<div data-jc-scope="?">

    <div data-jc="textbox__name">Name</div>
    <!-- path will be: aoyhdvlmloorhzomzm.name -->

</div>

<div data-jc-scope="?">

    <div data-jc="textbox__name">Name</div>
    <!-- path will be: xsngbvdllnidnaownly.name -->

</div>

How can I obtain anonymous path?

<div data-jc-scope="?" data-jc-init="scopeinit">
    ...
</div>

<script>
    function scopeinit(path, el) {
        // path {String}
        // el {jQuery Element}

        var scope = el.scope();
        // or
        var scope = this; 

        // scope === Scope object
    }
</script>

Scope object

Properties:

path;
// returns {String}
// A scope path

elements;
// returns {Array of DOM elements}
// All scopes (parent -> children)

isolated;
// returns {Boolean}
// Determines isolated scope

element;
// returns {jQuery element}
// A scope element

Methods:

scope.FIND();
// alias to global method: FIND() but this method finds components in the scope element only

scope.SETTER();
// alias to global method: SETTER() but this method works for components in the scope element only

scope.reset([path], [delay]);
// @path {String} Optional, it's additional path to scope path
// @delay {Number} Optional
// This method performs RESET() for the scope path

scope.default([path], [delay]);
// @path {String} Optional, it's additional path to scope path
// @delay {Number} Optional
// This method performs DEFAULT() for the scope path

scope.set(path, value, [delay], [reset]);
// @path {String} It's additional path to scope path
// @value {Object}
// @delay {Number} Optional
// @reset {Boolean} Optional, performs reset
// This method performs SET() for the scope path

scope.push(path, value, [delay], [reset]);
// @path {String} It's additional path to scope path
// @value {Object}
// @delay {Number} Optional
// @reset {Boolean} Optional, performs reset
// This method performs PUSH() for the scope path

scope.update(path, [delay], [reset]);
// @path {String} It's additional path to scope path
// @delay {Number} Optional
// @reset {Boolean} Optional, performs reset
// This method performs UPDATE() for the scope path

scope.get(path);
// @path {String} It's additional path to scope path
// returns {Object}
// This method performs GET() for the scope path

scope.can([flags]);
// @flags {Array String} Selector flags
// returns {Boolean}
// This method performs CAN() for the scope path

scope.errors([flags], [highlight]);
// @flags {Array String} Selector flags
// @highlight {Boolean} Highlight invalid components
// returns {Array jComponents}
// This method performs ERRORS() for the scope path

// SELECTOR FLAGS:
// @hidden - jComponent finds all hidden components
// @visible - jComponent finds all visible components
// @disabled - jComponent finds all components which have disabled inputs
// @enabled - jComponent finds all components which have enabled inputs

Special usage with ? question mark

Scopes supports one more thing. If the component path will contain ? question mark in the path then the scope replaces this ? mark with the current scope path.

<div data-jc-scope="users">

    <div data-jc="textbox__address.?.street">Street</div>
    <!-- path will be: address.users.street -->

</div>

Good to know

  • IMPORTANT: scope must contain some jComponent
  • scopes need to be declared in HTML directly
  • scopes can have nested scopes
  • jComponent contains a list of used scopes in component.scope property
  • scope DOM element contains the whole path stored in element.$scopedata property
  • obtaining scope with help of jQuery: $('selector').scope() returns a scope instance