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');
            

.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.