Interactive Patterns

Calcite Web includes a small (5KB gzipped) JavaScript library. calcite-web.js is a lightweight and dependency-free library made to enable interactive behaviors for certain patterns and components.

Currently, the following components and patterns rely on calcite-web.js:

The JavaScript library also includes helpers for "sticky" positioning and scroll events. You can read more about these in the interactive layout helpers section of the documentation.

Import calcite-web.js

Calcite Web can be imported using ES6 modules, CommonJS, AMD, or just a plain IIFE.

ES6 Module

If your bundler supports the ES6 module syntax you can import calcite as an ES6 module with named exports:

import * as calcite from 'calcite-web/es6';
calcite.init();

If your bundler uses the module field in package.json (Rollup, Webpack 2) leave off the es6:

import * as calcite from 'calcite-web';
calcite.init();

With named imports you can also just import what you need:

import {drawer} from 'calcite-web';
drawer(); // initialize only instances of the drawer pattern

This is a great way to cut down on the size of your build!

CommonJS

var calcite = require('calcite-web');
calcite.init();

AMD

require(['path/to/calcite-web.js'], function(calcite){
  // use calcite
  calcite.init();
});

IIFE

If calcite-web.js is used on a page with no module syntax, it will just attach itself to window.calcite. Here is an example which initializes Calcite from a self-hosted CDN location:

<body>
  ...
  <script src="https://<self-hosted-url>/files/calcite-web/1.2.5/js/calcite-web.min.js"></script>
  <script>
     calcite.init()
  </script>
</body>

Initializing

While all of the examples above use the main init() method, you can also initialize individual patterns. For example, initialize only instances of the tab pattern like this:

calcite.tabs();

Event Bus

The event bus is used to help interactive patterns communicate with each other and the rest of your application.

Along with a set of common bus events, each pattern has a set of channels that it emits on and listens for. These events can be emitted or listened for by the larger application.

You can trigger or react to events by using the on and emit methods on the bus:

// assuming calcite-web.js is available as calcite

// do something when a drawer opens
calcite.bus.on('drawer:open', function (options) {
  console.log(options.id) // => "top-nav"
})

// open a drawer (must pass data-drawer name as "id")
calcite.bus.emit('drawer:open', {id: "top-nav"})

Common Event Channels

Event Description Emits
keyboard:return The return key was pressed n/a
keyboard:escape The escape key was pressed n/a
keyboard:space The space key was pressed n/a
keyboard:arrow:up The key was pressed n/a
keyboard:arrow:down The key was pressed n/a
keyboard:arrow:left The key was pressed n/a
keyboard:arrow:right The key was pressed n/a
scrolling:at The page is scrolling ScrollYOffset

Pattern-Specific Event Channels

Accordions

Event Description Emits Function
accordion:bind Binds Dom nodes on the page to their listeners n/a bindToggles()
accordion:toggle Toggles an accordion section open and closed. {node: domNode} handleToggle()

Drawers

Event Description Emits Function
drawer:bind Binds dom to event listeners n/a bindDrawers()
drawer:open Opens a drawer specified by data-drawer attribute {id: drawerid} openDrawer()
drawer:close Closes a drawer specified by data-drawer attribute {id: drawerid} closeDrawer()
keyboard:escape Closes all drawers on escape n/a closeDrawer()

Dropdown

Event Description Emits Function
dropdown:bind Binds dom to event listeners n/a bindDropdowns()
dropdown:toggle Toggles a dropdown open and closed {node: domNode} toggleDropdown()
dropdown:close Closes all the dropdowns n/a closeAllDropdowns()
keyboard:escape Closes all the dropdowns when the escape key is pressed. n/a closeAllDropdowns()

Filter Dropdown

Many of the filter dropdown channels emit and listen for the following options object:

{
  parent: domNode,
  id: filterDropdownId,
  item: domNode
}
Event Description Emits Function
filterDropdown:bind Binds the dom to event listeners n/a bindFilterDropdowns()
filterDropdown:select An item in the dropdown list has been selected. Options Object toggleItem(), emitActive()
filterDropdown:select:remove Removes a specific selection from the list of active items. Options Object removeItem()
filterDropdown:active Emits all the currently selected items from the component. Options Object. Replaces item with active Array of items. drawActive()
filterDropdown:active:clear Clear all active items from the dropdown Options Object clearActive()
filterDropdown:toggle Toggle a dropdown open and closed Options Object toggleDropdown()
filterDropdown:open Open a specific dropdown Options Object openList()
filterDropdown:close Closes all dropdowns n/a closeList()
keyboard:escape Closes all dropdowns n/a closeList()

Modal

Event Description Emits Function
modal:bind Binds dom to event listeners n/a bindModals()
modal:open Opens a modal specified by data-modal attribute {id: modalid} openModal()
modal:close Closes open modal n/a closeModal()
keyboard:escape Closes all modals n/a closeModal()

Sticky

Event Description Emits Function
sticky:stick Dom Node to stick in place Dom Node stickItem()
sticky:unstick Dom Node to unstick and return to normal Dom Node unstickItem()
scrolling:at Current offset y position on scroll OffsetY Number scrollHandler()

Tabs

Tab events emit and listen for an Options Object.

{
  id: tabId // data-tab attribute
  active: domNode
}
Event Description Emits Function
tabs:bind Binds dom to event listeners n/a bindTabs()
tabs:active A tab to set as active Options Object setTab()

Utility Functions

calcite-web.js also has methods for DOM traversal and manipulation. If the needs of a project are not too complex it can be used in place of jQuery, Dojo, or other large frameworks.

function action
calcite.click() Returns standard interaction event (click). Touch support will be added soon.
calcite.addEvent(domNode, event, fn) Adds a callback function to an event on an element.
calcite.removeEvent(domNode, event, fn) Removes a callback function from an event on an element.
calcite.eventTarget() Returns the target element of an event.
calcite.preventDefault(event) Prevents default behavior of an event.
calcite.stopPropagation(event) Stops an event from bubbling up the DOM tree.
calcite.hasClass(event) Checks if an element has a specific class. Returns boolean.
calcite.addClass(domNode, className) Adds one or more classes to an element.
calcite.removeClass(domNode, classes) Removes one or more classes from an element.
calcite.toggleClass(domNode, className) Toggles one class on an element.
calcite.closest(domNode, classes) Returns closest element up the DOM tree matching a given class. Returns DOM node.
calcite.nodeListToArray(domNodeList) Takes a DOM node list and returns an array.

DOM Utilities

The following functions allow for basic DOM manipulation and traversal. These helpers are used by JavaScript dependent patterns, and can be included in any custom JavaScript in Calcite Web projects.

Events

calcite.click()

Returns interaction event for the current browser environment. Currently only returns 'click'. Will be more useful when touch support is added.

var click = calcite.click(); // => 'click'

calcite.addEvent(domNode, event, fn)

Adds a callback function to an event on an element.

var click = calcite.click();
var node = document.querySelector('body');

function action (event) {
  console.log('hola');
};

calcite.addEvent(node, click, action); // action will now fire when body is clicked

calcite.removeEvent(domNode, event, fn)

Removes a callback function from an event on an element.

var click = calcite.click();
var node = document.querySelector('body');

function action (event) {
  console.log('hola');
};

calcite.addEvent(node, click, action); // action will now fire when body is clicked
calcite.removeEvent(node, event, action); // action has been removed from body click event

calcite.eventTarget(event)

Returns the target DOM node of an event.

var click = calcite.click();
var node = document.querySelector('body');

function action (event) {
  var target = calcite.eventTarget(event);
  console.log(target);
};

calcite.addEvent(node, click, action);

Clicking the body will now log the contents of the <body> DOM node.

calcite.preventDefault(event)

Prevents default behavior of an event.

var click = calcite.click();
var node = document.getElementsByTagName('a')[0];

function action (event) {
  calcite.preventDefault(event);
};

calcite.addEvent(node, click, action);

This will prevent the first <a> DOM node in the document from performing its default behavior (sending the user to the link in its href attribute).

calcite.stopPropagation(event)

Stops an event from bubbling up the DOM tree. This is useful if events have been bound to both a parent DOM node and a child DOM node.

var click = calcite.click();
var node = document.getElementsByTagName('a')[0];

function action (event) {
  calcite.stopPropagation(event);
};

calcite.addEvent(node, click, action);

If, for example, the <body> DOM node also has a function bound to a click event, this will prevent a user's click from triggering it.

Manipulation & Traversal

calcite.hasClass(node, class)

Checks if the node currently has the provided class. For example, given the following html:

<div class="apple" id="test"></div>

The hasClass utility can be used as follows:

var node = document.getElementById('test');
var isApple = calcite.hasClass(node, 'apple');
console.log(isApple); // true

calcite.addClass(domNode, classes)

Adds one or more classes to a given element. Multiple classes should be passed as a space-separated string, like this:

var node = document.getElementById('test');
calcite.addClass(node, 'apples bananas oranges');

calcite.removeClass(domNode, classes)

Removes one or more classes from an element. Like addClass, multiple classes should be separated with a space and passed as a single string:

var node = document.getElementById('test');
calcite.removeClass(node, 'apples bananas oranges');

calcite.toggleClass(domNode, className)

Adds the class to the element if it doesn't have the class, otherwise, remove it:

var node = document.querySelector('.test');
calcite.toggleClass(node, 'test'); // remove test class
calcite.toggleClass(node, 'test'); // add test class

calcite.closest(class, element)

Searches up the DOM tree to find the closest parent element with a given class.

var nodes = document.querySelector('.child-element');

function clickHandler (event) {
  var closestNode = calcite.closest('parent-class', event.target);
}

for (var i = 0; i < nodes.length; i++) {
  calcite.addEvent(nodes[i], calcite.click(), clickHandler);
}

calcite.nodeListToArray(domNodeList)

Turn a node list (usually returned from a query) into an array.

var nodes = document.getElementsByTagName('a');
var nodeArray = calcite.nodeListToArray(nodes);