All samples are using Ink.requireModules, please read how to use it at Ink.requireModules section

Ink.UI.Common.BaseUIComponent class

Ink UI Base Class

You don't use this class directly, or inherit from it directly.

See createUIComponent() (in this module) for how to create a UI component and inherit from this. It's not plain old JS inheritance, for several reasons.

Methods
Method name Description
new BaseUIComponent(element, [options]) Constructor
.createUIComponent(theConstructor, [options]) Take a constructor, and make it an Ink UI component.
.getElement() Get the element associated with an UI component (IE the one you used in the constructor)
.getOption(name) Get an UI component's option's value.
.getOption(name, value) Sets an option's value.

new Ink.UI.Common.BaseUIComponent(element, [options])

Accepts

  • element

    Element to associate this UI component with. It's the element you can get later using `comp.getElement()`
  • options

    Options to pass to the component. You should see your specific UI component for this information.

.createUIComponent(theConstructor, [options]) method

Take a constructor, and make it an Ink UI component.

Makes it inherit BaseUIComponent, makes sure it has the basic properties Ink.UI.Common needs it to have, adds the necessary static methods, sets its options, etc.

Accepts

  • theConstructor

    UI component constructor. It should have an _init function in its prototype, an _optionDefinition object, and a _name property indicating its name.
  • options

    Options hash, containing:
  • options.elementIsOptional

    falseWhether the element argument is optional (For example, when the component might work on existing markup or create its own).

.getElement() method

Get the element associated with an UI component (IE the one you used in the constructor)

Example

            var myUIComponent = new Modal('#element'); // or anything else inheriting BaseUIComponent
            myUIComponent.getElement();  // -> The '#element' (not the selector string, mind you).
            
            

.getOption(name) method

Get an UI component's option's value.

Accepts

  • name

    The option's name.

Example

            
            var myUIComponent = new Modal('#element', { trigger: '#trigger' }); // or anything else inheriting BaseUIComponent
            myUIComponent.getOption('trigger');  // -> The trigger element (not the selector string, mind you)
            
            

.getOption(name, value) method

Sets an option's value.

Accepts

  • name

    Name of the option.
  • value

    New option value.

Example

            
            var myUIComponent = new Modal(...);
            myUIComponent.setOption('trigger', '#some-element');
            

Ink.UI.Common_1 class

Functions
Function name Description
.ajaxJSON(endpoint, params, cb) AJAX JSON request shortcut method
.childIndex(childEl) deprecated Gets an element's one-base index relative to its parent.
.cleanChildren(parentEl) Removes children nodes from a given object.
.clone(o) deprecated Deep copy (clone) an object.
.currentLayout() Gets the current Ink layout.
.destroyComponent() Boilerplate method to destroy a component.
.elOrSelector(elOrSelector, fieldName) Gets a DOM Element.
.elsOrSelector(elsOrSelector, [fieldName], required) Like elOrSelector but returns an array of elements.
.getInstance(el, [UIComponent]) Gets an UI component instance from an element.
.getInstanceFromSelector(selector) Gets an instance based on a selector.
.getInstanceIds() Gets all the instance ids
.getInstances() Gets all the instances
.hashSet(o) Sets the location's hash (window.location.hash).
.isDOMElement(o) Checks if an item is a valid DOM Element.
.isInteger(n) Checks if an item is a valid integer.
.options([fieldId], defaults, overrides, [element]) Gets options an object and element's metadata.
.registerInstance(inst, el) Saves an object (which should inherit BaseUIComponent) in the registry, associated with an element. You can retrieve it later by calling getInstance.
.restoreIdAndClasses(toEl, inObj) Sets the id and className properties of an element based
.storeIdAndClasses(fromEl, inObj) Stores the id and/or classes of an element in an object.
.unregisterInstance(inst) Unregisters (removes from the registry) a UI component instance from whatever element it's on.
Properties
Property name Description
.Layouts Supported Ink Layouts

.ajaxJSON(endpoint, params, cb) method

AJAX JSON request shortcut method
It provides a more convenient way to do an AJAX request and expect a JSON response.It also offers a callback option, as third parameter, for better async handling.

Accepts

  • endpoint

    Valid URL to be used as target by the request.
  • params

    This field is used in the thrown Exception to identify the parameter.
  • cb

    Callback for the request.

Example

                // In case there are several .myInput, it will retrieve the first found
                var el = Ink.UI.Common.elOrSelector('.myInput','My Input');
            

.childIndex(childEl) method

Gets an element's one-base index relative to its parent.

Deprecated. Use Ink.Dom.Element.parentIndexOf instead.

Accepts

  • childEl

    Valid DOM Element.

Example

                <!-- Imagine the following HTML: -->
                <ul>
                  <li>One</li>
                  <li>Two</li>
                  <li id="test">Three</li>
                  <li>Four</li>
                </ul>
            
                <script>
                    var testLi = Ink.s('#test');
                    Ink.UI.Common.childIndex( testLi ); // Returned value: 3
                </script>
            

.cleanChildren(parentEl) method

Removes children nodes from a given object.
This method was initially created to help solve a problem in Internet Explorer(s) that occurred when trying to set the innerHTML of some specific elements like 'table'.

Accepts

  • parentEl

    Valid DOM Element

Example

                <!-- Imagine the following HTML: -->
                <ul id="myUl">
                  <li>One</li>
                  <li>Two</li>
                  <li>Three</li>
                  <li>Four</li>
                </ul>
            
                <script>
                Ink.UI.Common.cleanChildren( Ink.s( '#myUl' ) );
                </script>
            
                <!-- After running it, the HTML changes to: -->
                <ul id="myUl"></ul>
            

.clone(o) method

Deep copy (clone) an object.
Note: The object cannot have referece loops.

Accepts

  • o

    The object to be cloned/copied.

Example

                var originalObj = {
                    key1: 'value1',
                    key2: 'value2',
                    key3: 'value3'
                };
                var cloneObj = Ink.UI.Common.clone( originalObj );
            

.currentLayout() method

Gets the current Ink layout.

Example

                 var inkLayout = Ink.UI.Common.currentLayout();
                 if (inkLayout === 'small') {
                     // ...
                 }
            

.destroyComponent() method

Boilerplate method to destroy a component.
Components should copy this method as its destroy method and modify it.

.elOrSelector(elOrSelector, fieldName) method

Gets a DOM Element.

Accepts

  • elOrSelector

    DOM Element or CSS Selector
  • fieldName

    The name of the field. Commonly used for debugging.

Example

                // In case there are several .myInput, it will retrieve the first found
                var el = Ink.UI.Common.elOrSelector('.myInput','My Input');
            

.elsOrSelector(elsOrSelector, [fieldName], required) method

Like elOrSelector but returns an array of elements.

Accepts

  • elsOrSelector

    DOM Element, array of DOM Elements, or CSS Selector
  • fieldName

    The name of the field. Used for the error shown when no elements are found.
  • required

    If this is true, throw an error instead of returning an empty array.

Example

                var elements = Ink.UI.Common.elsOrSelector('input.my-inputs', 'My Input');
            

.getInstance(el, [UIComponent]) method

Gets an UI component instance from an element.

This function is already available in the UI components' classes themselves. You can call Modal.getInstance() and retrieve a modal.

Accepts

  • el

    Element from which we want the instances. A selector is okay.
  • UIComponent

    If you pass an Ink UI component class (Like Ink.UI.Modal or Ink.UI.Carousel), this won't return an array of all instances associated with the element. Instead it will return only the object which is an instance of that class.

.getInstanceFromSelector(selector) method

Gets an instance based on a selector.

Accepts

  • selector

    CSS selector to get the instances from. This function will only use the *first* element.

.getInstanceIds() method

Gets all the instance ids

.getInstances() method

Gets all the instances

.hashSet(o) method

Sets the location's hash (window.location.hash).

Accepts

  • o

    Object with the info to be placed in the location's hash.

Example

                // It will set the location's hash like: <url>#key1=value1&key2=value2&key3=value3
                Ink.UI.Common.hashSet({
                    key1: 'value1',
                    key2: 'value2',
                    key3: 'value3'
                });
            

.isDOMElement(o) method

Checks if an item is a valid DOM Element.

Accepts

  • o

    The object to be checked.

Example

                var el = Ink.s('#element');
                if( Ink.UI.Common.isDOMElement( el ) === true ){
                    // It is a DOM Element.
                } else {
                    // It is NOT a DOM Element.
                }
            

.isInteger(n) method

Checks if an item is a valid integer.

Accepts

  • n

    The value to be checked.

Example

                var value = 1;
                if( Ink.UI.Common.isInteger( value ) === true ){
                    // It is an integer.
                } else {
                    // It is NOT an integer.
                }
            

.options([fieldId], defaults, overrides, [element]) method

Gets options an object and element's metadata.

The element's data attributes take precedence. Values from the element's data-atrributes are coerced into the required type.

Accepts

  • fieldId

    Name to be used in error reports.
  • defaults

    Object with the options' types and defaults.
  • overrides

    Options to override the defaults. Usually passed when instantiating an UI module.
  • element

    Element with data-attributes

Example

            
                 this._options = Ink.UI.Common.options('MyComponent', {
                     'anobject': ['Object', null],  // Defaults to null
                     'target': ['Element', null],
                     'stuff': ['Number', 0.1],
                     'stuff2': ['Integer', 0],
                     'doKickFlip': ['Boolean', false],
                     'targets': ['Elements'], // Required option since no default was given
                     'onClick': ['Function', null]
                 }, options || {}, elm)
            
            
            
            ### Note about booleans
            
            Here is how options are read from the markup
            data-attributes, for several values`data-a-boolean`.
            
            Options considered true:
            
              - `data-a-boolean="true"`
              - (Every other value which is not on the list below.)
            
            Options considered false:
            
              - `data-a-boolean="false"`
              - `data-a-boolean=""`
              - `data-a-boolean`
            
            Options which go to default:
            
              - (no attribute). When `data-a-boolean` is ommitted, the
              option is not considered true nor false, and as such
              defaults to what is in the `defaults` argument.
            
            

.registerInstance(inst, el) method

Saves an object (which should inherit BaseUIComponent) in the registry, associated with an element. You can retrieve it later by calling getInstance.

This won't allow two instances of the same class to be created on a single element. It will fail and print a warning to the console if you try to do it. That is a common error when using Ink.

Accepts

  • inst

    Object that holds the instance.
  • el

    Element to associate with `inst`.

.restoreIdAndClasses(toEl, inObj) method

Sets the id and className properties of an element based

Accepts

  • toEl

    Valid DOM Element to set the id and classes on.
  • inObj

    Object where the id and classes to be set are. This method uses the same format as the one given in `storeIdAndClasses`

Example

                <div></div>
            
                <script>
                    var storageObj = {
                      _id: 'myDiv',
                      _classes: 'aClass'
                    };
            
                    Ink.UI.Common.storeIdAndClasses( Ink.s('div'), storageObj );
                </script>
            
                <!-- After the code runs the div element changes to: -->
                <div id="myDiv" class="aClass"></div>
            

.storeIdAndClasses(fromEl, inObj) method

Stores the id and/or classes of an element in an object.

Accepts

  • fromEl

    Valid DOM Element to get the id and classes from.
  • inObj

    Object where the id and classes will be saved.

Example

                <div id="myDiv" class="aClass"></div>
            
                <script>
                    var storageObj = {};
                    Ink.UI.Common.storeIdAndClasses( Ink.s('#myDiv'), storageObj );
                    // storageObj changes to:
                    {
                      _id: 'myDiv',
                      _classes: 'aClass'
                    }
                </script>
            

.unregisterInstance(inst) method

Unregisters (removes from the registry) a UI component instance from whatever element it's on.

Accepts

  • inst

    Instance to be unregistered.

.Layouts attribute

Object

Supported Ink Layouts