Skip to content

Latest commit

 

History

History
174 lines (119 loc) · 6.52 KB

getting-started.md

File metadata and controls

174 lines (119 loc) · 6.52 KB
layout
doc-page.html

Getting started

ally.js is a JavaScript library simplifying certain accessibility features, functions and behaviors. However, simply loading ally.js will not automagically make a web application accessible. The library provides certain standard functions the "web platform" should've provided itself, so JavaScript applications be made accessible more easily. This document covers how to import ally.js in your project - see the API documentation to learn what the library actually provides.

Requirements

In order to load successfully in IE8, the es5-shim has to be loaded. Please also see Does ally.js support Internet Explorer 8 and below?.

The UMD bundle contains the following dependencies:

Downloading the UMD bundle

If you're not comfortable with package mangers, simply download the production ready UMD bundle and drop it in your project.

  • ally.min.js UMD bundle, ready for production use
  • ally.min.js.map for SourceMap support
  • ally.js.zip archive containing CommonJS, AMD and ES6 modules, as well as the UMD bundle (including SourceMap files)
  • ally.js.tar.gz archive containing CommonJS, AMD and ES6 modules, as well as the UMD bundle (including SourceMap files)

All downloads are hosted on the github release page.

Loading the UMD bundle from CDN

ally.js is made available for production use by jsDelivr:

<script src="https://cdn.jsdelivr.net/ally.js/{{pkg.version}}/ally.min.js"></script>
<script>
  console.log('loaded ally.js in version', ally.version);
  console.log('focusable elements', ally.query.focusable());
</script>

ally.js is also available for production use by cdnjs:

<script src="https://cdnjs.cloudflare.com/ajax/libs/ally.js/{{pkg.version}}/ally.min.js"></script>
<script>
  console.log('loaded ally.js in version', ally.version);
  console.log('focusable elements', ally.query.focusable());
</script>

Installing via package manager

npm install --save ally.js

Although bower can download archives, it won't be able to inform you of updates:

bower install --save https://github.com/medialize/ally.js/releases/download/{{pkg.version}}/ally.js.zip

You can use system-npm to consume ally.js from npm in SystemJS:

System.import('ally.js!npm').then(function(ally) {
  console.log('loaded ally.js in version', ally.version);
});

Using the UMD bundle via <script>

<script src="path/to/ally.min.js"></script>
<script>
  console.log('loaded ally.js in version', ally.version);
  console.log('focusable elements', ally.query.focusable());
</script>

Using CommonJS modules

The production UMD bundle contains all dependencies, allowing you to require ally.js directly:

var ally = require('ally.js');
console.log('loaded ally.js in version', ally.version);
console.log('focusable elements', ally.query.focusable());

Alternatively you can use only specific modules provided by ally.js:

var version = require('ally.js/version');
console.log('loaded version of ally.js', version);

var queryFocusable = require('ally.js/query/focusable');
console.log('focusable elements', queryFocusable());
  • NOTE: The CommonJS modules are only available through npm and ally.js.zip.

Using ES6 modules

ally.js is authored in ES6 and its modules are accessible in the src directory:

import version from 'ally.js/src/version';
console.log('loaded version of ally.js', version);

import queryFocusable from 'ally.js/src/query/focusable';
console.log('focusable elements', queryFocusable());

Using AMD modules

The production UMD bundle contains all dependencies, allowing you to require ally.js directly:

require.config({
  paths: {
    'ally.js': 'node_modules/ally.js/ally.min',
  },
});

require(['ally.js'], function(ally) {
  console.log('loaded ally.js in version', ally.version);
  console.log('focusable elements', ally.query.focusable());
});

Alternatively you can use only specific modules provided by ally.js, but need to take care of mapping dependencies first:

require.config({
  paths: {
    // map to AMD files
    'ally.js': 'node_modules/ally.js/amd',
    // provide paths to dependencies
    'array.prototype.findindex': 'node_modules/array.prototype.findindex/index',
    'css.escape': 'node_modules/css.escape/css.escape',
    'platform': 'node_modules/platform/platform',
  },
});

Now you can import specific modules using

require(['ally.js/version'], function(version) {
  console.log('loaded version of ally.js', version);
});

require(['ally.js/query/focusable'], function(queryFocusable) {
  console.log('focusable elements', queryFocusable());
});
  • NOTE: The AMD modules are only available through npm and ally.js.zip.

Continue with checking out one of the Tutorials or head on to the API documentation