Installation

Developers interested in working on Exhibit 3.0 Scripted can follow these directions to get their environment set up. Authors should consult the authoring documentation.

Requirements

• Any HTTP server
• Major web browsers with web development mode tools (Internet Explorer, Google Chrome, Mozilla Firefox, Safari)
• Git
• optional GitHub account
• Java
• Ant
• optional JSCoverage

Depending on your operating system, you may already have an HTTP server at your disposal. Mac OS X and many variants of Linux include one. If you are unfamiliar with how to acquire and use one, development on Exhibit may not be for you.

Acquire Code

If you are planning to contribute your work back to the project, consider getting a GitHub account so you can fork the project and issue pull requests later to fold your changes back into the main branch. You can get the code by viewing the project front page and using your preferred method of Git access to clone the main repository. E.g., for read only access:

% git clone [email protected]:simile-widgets/exhibit.git

Serving Code

The code that can be readily deployed to a web server must first be assembled. Run:

% cd scripted
% ant dist

If successful, the directory can be found at scripted/dist/. Making the entire scripted/dist/ directory available from your HTTP server is sufficient. Access your deployed Exhibit in your pages by using:

<script src="http://yourserver/scripted/dist/exhibit-api.js?bundle=false"></script>

Using the bundle=false parameter is highly recommended for development, unless you are testing the bundled mode of operation. Use shift+reload to make sure you're loading the latest scripts in your browser.

Making Changes

You'll be working in the scripted directory. As you make changes to the code, make sure to test how your changes affect the project as a whole. Use

% ant test

from the command line to run the existing unit test suite as well as lint for Javascript code style checking. To test just one module, use:

% ant -Dmodules='[space separated list]' qunit

Unit tests do not cover user interaction; we do not have a solution for integration tests at the moment. You may want to check various demos or your own work across browsers to make sure the full experience has not been negatively impacted by your changes.

All commits are run through a continuous integrator, which will alert us to any problems with unit tests on the main branch.

Localization

Note that no displayed communications should reside in scripts. All strings should be given a key and placed in the English localization file, which is the canonical set of keys. Do not add a new key to a different locale without having also added it to the English locale. Use Exhibit._ to place the string, e.g.,

// in locale file
...
"%category.newKey": "Hello, %1$s!",
...

// in any script
alert(Exhibit._("%category.newKey", "World"));

There's more on Localization if you're interested in the system and/or contributing a locale.

Documentation

We use JSDocToolkit in-code documentation to produce some of our API documents.

More Tests

We can always use more tests. Using JSCoverage, you can see how much of the code is actually tested by our test suite and find precise lines of code that still need some testing to ascertain and maintain correctness. With JSCoverage installed, you can run

% ant coverage

to generate a coverage report.

Bundling

You can bundle an extension with

% ant -Dextension=time extension-bundle

Be sure to add production ready extensions to scripted/build.xml in the target bundle-all.

Next Steps

Now that your environment is set up, you might want to get an overview of the way Exhibit fits together, or start reading either the generated API documentation or a more reader-oriented API, or the event API.