You will need to consider the following:

  1. Getting the ACE package into your project
  2. Loading ACE CSS & JS into your views
  3. Which templates to use
  4. Using ACE Debugger for QA

Loading package

ACE is distributed from a private repository in Bitbucket, usually through Bower or NPM. Because ACE is in a private repo, you will need to ensure your build has sufficient access privileges to load the repo. This has been solved for Bamboo and Bitbucket Pipelines, contact Interface for assistance if required.

To add ACE to your dependencies, use the git URL and tag hash. Both Bower and NPM use the same syntax:

"dependencies": {
  "ace": "[email protected]:ansarada/ace.git#"
}

Note that in some cases a -DEV version may show in these docs, in which case refer to the Changelog or view the tags in Bitbucket to check the latest release. ACE follows SemVer so the numbers should be predictable. ACE can also be manually downloaded (as .zip files) from Bitbucket.

The files required to use ACE are located in /dist/ inside /bower_components/ or the extracted .zip contents.

Bower vs NPM

The choice comes down to developer preference. NPM means one less dependency and build step, while Bower is marginally faster.

  • Both NPM and Bower take about a minute (+/- 10 sec) to install ACE on an average connection.
  • Bower is slower, but downloads fewer files and ends up being 20% faster.
  • NPM is faster, but installs the deep dependency tree and ends up being 20% slower.
  • NPM is ~20% slower and tends to run without user feedback for a significant period.
  • After accounting for the few seconds it takes to install Bower, there is very little saving using Bower.

Yarn

Although not offically supported Yarn does work. Install with the ignore engines flag:

yarn add git+ssh://[email protected]/ansarada/ace.git# --ignore-engines

Loading ACE assets

Background

The assets you load depend on the type of project you are working on. Some projects will need the ACE DOM script package and others will not. Additionally, you may opt to load optional extensions.

ACE is designed to handle both traditional rendering and single page application (SPA) rendering. ACE defines UI states, but it is not opinionated about how you implement those states.

For example ACE defines form inputs in both resting (normal) and error states:

  • In a traditional application the error state may be achieved on first load from server-side templates.
  • The error state could be set with jQuery in response to user input, using the ACE DOM scripting package.
  • In an SPA, the app simply reflects the state it needs and does not need the jQuery package at all.

Choosing assets

All projects require:

  • The viewport META tag to enable responsive rendering
  • The ACE CSS file, plus the /fonts/ and /images/ subdirectories to support them
  • The ACE base JavaScript file

The DOM package is listed on this page and extensions document their asset requirements on their individual pages.

Loading from static

Ansarada has a static file server: static.ansarada.com. There are a few ways to make use of this with ACE.

The simplest way is to use the pre-built copy of the CSS which loads the web fonts from static. They are heavy files which very rarely change, so loading them from static is high-value, but you retain normal package management workflow.

To enable the pre-built static CSS, either:

  1. change any reference to ace.min.css to ace-static.min.css
  2. if you are building SCSS from source, set the variable $font-file-path: "https://static.ansarada.com/fonts/20171005/"; before importing ACE (this overrides the default local asset path).

Alternatively you can load entire version-bound copies of ACE from Static, including the pre-built static CSS. Check the URLs are available at static.ansarada.com before relying on them in production. Releases for this option are not yet fully automated and the manual check won't be required in future.

If in doubt, the static font payload is recommended.

Resource profiles

Project type Dependencies Code
Single Page Apps (managed state payload) None

In the HEAD, loading all resources locally:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace.min.css" media="all">
                                                                    <script src="dist/ace-base.min.js"></script>

In the HEAD, loading font files from static:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace-static.min.css" media="all">
                                                                    <script src="dist/ace-base.min.js"></script>
Traditional rendering (DOM scripting payload) jQuery

In the HEAD, loading all resources locally:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace.min.css" media="all">
                                                                    <script src="dist/ace-base.min.js"></script>

In the HEAD, loading font files from static:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace-static.min.css" media="all">
                                                                    <script src="dist/ace-base.min.js"></script>

Note that the base js is very small and should be inlined if possible.

In #hidden (or at the end of the document):


                                                                    <script src="dist/lib/jquery.min.js"></script>
                                                                    <script src="dist/ace-dom.min.js"></script>
Single-file DOM payload - note some user agents may get a rendering flicker as the browser classes are applied later in the load cycle. jQuery

In the HEAD, loading all resources locally:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace.min.css" media="all">

In the HEAD, loading fonts from static:


                                                                    <meta name="viewport" content="width=device-width, initial-scale=1">
                                                                    <link rel="stylesheet" href="dist/ace-static.min.css" media="all">

In #hidden (or at the end of the document):


                                                                    <script src="dist/lib/jquery.min.js"></script>
                                                                    <script src="dist/ace.min.js"></script>

Templates

The core API of ACE is the HTML and JavaScript patterns, so philosophically it can be used anywhere you can use the web trinity of HTML, CSS and JS.

More practically, templates are provided to make using ACE efficient and easy. The following formats are available:

  • Classic ASP - used for the legacy code base.
  • Pug (formerly Jade) - used for NodeJS applications and static sites. Note the Pug templates are used to generate the ACE docs but remain undocumented (Pug 1.0 has not yet been defined). To use them you will need to view the template source code and keep an eye on release notes for changes.
  • React - incoming template set, to support SPAs.

ACE Debugger

The ACE Debugger is an optional dev tool recommended only for your dev environment. It can be used in all project types - in traditional projects it should be run once on each page load, while SPAs should call the debugger after each DOM update.

In the HEAD:

<link rel="stylesheet" href="dist/debug/ace-debug.css" media="all">

In #hidden as the last possible resource:

<script src="dist/debug/ace-debug.js"></script>