Introduction

Our JavaScript library has a modular architecture and is organized into namespaces:

Ink - The core module. Provides common methods used by all other modules.
Ink.Dom - Provides DOM manipulation methods, event management, form serialization, etc
Ink.Net - Ajax and JsonP request handling
Ink.UI - User interface components.
Ink.Util - Utility methods.
Ink.Ext - Reserved for community contributions.

Ink UI Components

The UI namespace (Ink.UI.*) contains visual components that allow you to enhance your pages with interactivity, like carousels, modal windows, tooltips, etc. UI components can be used in two ways:

Using Autoload

Recommended for people less comfortable with javascript. This method is the easiest, but gives you a bit less flexibility. You can use Ink.Autoload to create the UI components by adding classes to the DOM, and data-attributes to pass options.

All configuration options, except callback functions, are available as data-attributes but are prefixed with data- and are written in lowercase and hyphen separated: someOption = data-some-option.

Code

<!-- Load the js files -->
<script type="text/javascript" src="https://ink.freetls.fastly.net/3.1.10/js/ink-all.js"></script>
<script type="text/javascript" src="https://ink.freetls.fastly.net/3.1.10/js/autoload.js"></script><!-- required -->
...
<!-- Set the init options on the component markup with data-attributes -->
<div id="carousel" class="ink-carousel" data-pagination="#carousel-pagination">
  <ul class="stage column-group">
    <li class="slide">...</li>
    <li class="slide">...</li>
    <li class="slide">...</li>
  </ul>
</div>
<nav id="carousel-pagination" class="ink-navigation">
  <ul class="pagination black">
  </ul>
</nav>

Using raw JavaScript

Code

<script>
Ink.requireModules(['Ink.UI.Carousel_1'], function(Carousel) {
    new Carousel('#carousel', {pagination: '#carousel-pagination'});
});
</script>

CDN

If you don't want or need to host Inks code you can use our CDN (generously provided by Fastly). All of our releases are available:

<link rel="stylesheet" type="text/css" href="https://ink.freetls.fastly.net/x.x.x/">

If you need SSL get the files from:

<link rel="stylesheet" type="text/css" href="https://ink.global.ssl.fastly.net/x.x.x/">

x.x.x will be the version number and inside each version the CDN mimicks the distibution bundle:

<link rel="stylesheet" type="text/css" href="https://ink.freetls.fastly.net/3.1.10/css/ink.css"> <!-- inks css file -->
<script type="text/javascript" src="https://ink.freetls.fastly.net/3.1.10/js/ink-all.js"></script> <!-- inks js bundle -->

ink.js - Contains: Ink, Ink.Dom, Ink.Net and Ink.Util modules. Minified version available: ink.min.js
ink-ui.js - Contains the Ink.UI module. Minified version available: ink-ui.min.js
ink-all.js - ink.js and ink-ui.js bundled together. Minified version available: ink-all.min.js
autoload.js - UI component automatic initialization. Use with ink-all.js.
modernizr.js - Used for browser feature detection, mainly useful if you intend to use our flex grid.

Ink.requireModules

The Ink.requireModules() method is our implementation of AMDs require pattern. It handles dependency loading, provides aliases for modules and a callback function that gets executed. We recommend that you use it.

As you'll see throughout our documentation, the provided examples use Ink.requireModules(). Don't worry you don't have to use with every method invocation, but wrapping you code in its callback function will keep your code isolated and the DOMs global scope clean of clutter.

Example

/* Start of my_project.js file */
Ink.requireModules([
            'Ink.Dom.Loaded_1',
            'Ink.Dom.Element_1',
            'Ink.Dom.Event_1',
            'Ink.Dom.Css_1',
            'Ink.Net.Ajax_1',
            'Ink.UI.Modal_1',
            'Ink.UI.Carousel_1'
    ], function(Loaded, InkElement, InkEvent, InkCss, Ajax, Modal, Carousel){

    var body = Ink.s('body');
    var container = Ink.ss('#container')[0];

    function onClickBody() {
        InkCss.addClassName(body, 'body-class');

        var newElm = InkElement.create('div', {
                className:'some-class',
                id: 'newdiv',
                setTextContent: 'Element text content',
                insertBottom: container
            });
    }

    function addEvents() {
        InkEvent.on(body, 'click touchstart', onClickBody);
    }

    /* ... more code ... */

    function initProject() {
        addEvents();
        new Modal('#project-modal', {trigger: '#open-modal'});
        new Carousel('#project-carousel', {pagination: '#carousel-pagination'})
    }

    Loaded.run(function() { // will run on DOMContentLoaded
        initProject();
    });

});
/* End of my_project.js file */

Ink.Ext

The Ink.Ext is a special namespace. It was created to allow the community to contribute with new modules or components. These contributions may eventually be integrated into Inks core. Read more on how to contribute on our Github repository.

To create your own extension use the Ink.createExt(). Your extension will become available under the Ink.Ext namespace.

Code

Ink.createExt('myExtension', 1, ['Ink.Dom.Event_1'], function(InkEvent) {

    var myExtension = function() {
        this._init();
    };

    myExtension.prototype = {
        _init: function() {
            this._doStuff();
        },

        _doStuff: function() {
            alert('Doing stuff in myExtension');
            /* ... */
        }
    };

    return myExtension;
});


Ink.requireModules(['Ink.Ext.myExtension_1'], function(myExtension) {
    new myExtension();
});

Creating your own Ink UI components

You can create your own components using Ink.createExt and Ink.UI.Common.createUIComponent. See the code below, replacing "Donut" with your own component name.

Note: this only applies to UI-related javascript components, such as the ones you find in the Ink.UI namespace. The remaining components are created just with Ink.createExt, as seen above.

Code

Ink.createExt('Donut', 1, ['Ink.UI.Common_1'], function(Common) {
    'use strict';

    var Donut = function( ) {
        Common.BaseUIComponent.apply( this , arguments );
    };

    Donut._name = 'Donut';

    Donut._optionDefinition = {
        // optionName:  ['OptionType', defaultValueIfAny]
        flavor:         ['String', 'simple'],
        calories:       ['Number', 9000],
        hole:           ['Boolean', true],
        onEat:          ['Function', null]
    };

    Donut.prototype = {
        _init: function( ) { }
    };

    Common.createUIComponent( Donut );

    return Donut;
});

And now your component is ready to use!

Code

Ink.requireModules(['Ink.Ext.Donut_1'], function(Donut) {
    'use strict';

    var donutElement = document.getElementById('donut-element');

    new Donut(donutElement, {
        // See `Donut._optionDefinition` for what you can pass as options
        // Options can also be passed as data-attributes in the element.
        flavor: 'chocolate'
    });
});