README ====== This is the module root directory. The foremost among these files is ``modules.js``, the only real native JavaScript file that Chiron provides; all of the other scripts are modules:: modules.js There are a few common directories that contain support material for the library. These are not meant to be used in production, but rather in research, development, testing, teaching, and promotion:: test/ experiment/ demo/ learn/ Additional directories correspond to module categories. These directories to organize common functionality and submodules:: browser/ canvas/ crypt/ debug/ http/ widget/ Directories named after web domain names contain packages of module content developed by third parties. Chiron reserves domain-name directories for their owners with the exception of a few modules that we've integrated ourselves. Each of these packages is philosophically structured in the same fashion as the module root; they may each contain their own directories for tests, experiments, demos, and tutorials; files may be named in analogous ways, like ``base.js`` would be appropriate for common functionality in the package:: simile.mit.edu/ datejs.com/ del.icio.us/ google.com/ jquery.com/ Additional directories contain or are reserved for resources:: images/ icons/ styles/ locales/ themes/ doc/ ``icons/`` contains the Silk icon set. There are some additional files that exist for documentation:: README.rst preamble.rst license.rst credit.rst glossary.rst The remaining files are all JavaScript modules. They fall among several categories: * pure code utilities * parsing, formatting, and communication * drivers for browser facilities * animation tools * page controllers Base Modules ------------ ``modules.js`` is conceptually the kernel of the Chiron JavaScript library. As such, it subsumes some code that it requires to perform its job. Effectively, ``modules.js`` "primes" some modules:: modules.js http.js browser.js environment.js ``modules.js`` contains the internals of the module loader. ``http.js`` contains the code for making HTTP requests in JavaScript; this is where anything officially called AJAX or XHR happens. ``browser.js`` contains a cross-browser abstraction layer for manipulating web pages, HTML, XML, and the DOM. ``environment.js`` contains browser sniffing results and an overridable, interceptable, cross-browser logging abstraction layer. Chiron provides several core, foundation, basic modules. These modules are separated in layers to permit fine options in commitment. The "commitment stack" was originally one file. To give users the option of committing to various weights of code for short to long term web pages to application, and to balance convenience against portability, parts of ``base.js`` became ``boot.js`` and ``boost.js``. Each layer requires the previous layer:: boot.js base.js boost.js ``boot.js`` is a minimal commitment to a cadre of functions that provide basic type-sensitive functionality. These functions are named after the specific types they operate on and return. They are not tolerant of other types and provide no implicitly coercion. As a result, this small file provides a lot of common functionality with a low cost in file size and performance overhead. ``base.js`` is a very large file that contains a type system and comprehensive type-tolerant, polymorphic functions. ``boost.js`` is a small file that takes ``base.js``, provides additional esoteric functions, especially for operating on iterations, and to increase brevity in user code, engages in the dubious act of augmenting the prototypes of JavaScript's native types like Array and Function. Support Directories ------------------- The following directory names are reserved for support content: content not meant to be used in production:: test/ experiment/ demo/ learn/ test/ contains unit tests for components of the Chiron library. All test scripts can be run using ``run.html`` and ``lite.html`` with the URL of the test module in the query string (after the question mark at the end of the URL). These tests require no user interaction and display a sequence of successes and failures for deterministic behaviors. Each directory and file corresponds to a module in the root hierarchy. If there are multiple tests for a module, there is a directory with other unit tests. The most important test file is ``litmus.js`` that literally includes a sequence of other, small unit tests that in aggregate provide a heuristic for whether the library has regressed during development. All of the tests in ``litmus.js`` should pass. Sometimes it is appropriate to modify ``litmus.js`` and document a behavior change:: test/litmus.js experiment/ contains scripts and pages that reproducibly demonstrate a particular library or browser behavior. These can be viewed and verified manually. They should also contain documentation on the observed behavior and how it varies across browsers or other factors. demo/ contains scripts and pages that demonstrate particular components of the library in action. These are meant to be used to promote the library and help teach how to use the library for particular situations. learn/ contains pages that can be viewed either directly or using ``learn.html`` with the URL of the page in the query string. These files contain additional markup to provide queues to the interactive interpreter (``learn.html``) like where to pause the lesson so the user can play, and what code samples to execute for demonstration purposes. Support Scripts --------------- Some files in the module root exist for support services:: test.js run.html, run.js lite.html, lite.js learn.html, learn.js edit.html, edit.js, edit.css debug.js, debug/ help.js console.js ``test.js`` includes functions that are valuable for evaluating measuring and logging unit and performance tests. Every unit test in ``tests/`` uses this module. The ``run``, ``lite``, ``edit``, ``learn``, and ``debug`` pages, scripts, and styles provide different views into a JavaScript interactive console. ``run`` accepts a list of ampersand (``&``) delimited modules on the query string (after ``?`` on the URL) to include in the interactive context; these modules post their logs, including module loading logs. ``lite`` is like ``run`` except it does not provide an interactive console after the modules load. ``edit`` provides a means to edit a script in one pane, and interact with a JavaScript console in the other, running the script on command. ``learn`` provides an interactive console and accepts a lesson HTML file in the query string. The interactive console permits you to step through the sections of the lesson while interacting with the JavaScript console. ``debug.js`` is a Chiron module that you can include in the ``modules.js`` script header on any web page to introduce a debug and logging console that will appear if the user presses ``ctrl+shift+J``, ``ctrl+shift+L``, ``command+shift+J``, or ``command+shift+L``. ``help.js`` provides tools for interactive documentation browsing in ``run.html`` and ``learn.html``. ``help.js`` is implicitly included if you use the ``help`` function provided in ``base.js``. This module loads text from the JavaScript API documentation in the ``help/`` directory that is created as part of the build process. ``console.js`` contains common code for the interactive JavaScript consoles. ``console.js`` specializes ``widget/console.js`` which can be used for any kind of interactive console. Other Modules ------------- Chiron provides utilities that conceptually can be implemented in any language for use in any language. These provide a backbone for coding idioms and provide the essential character of Chiron APIs:: event.js cache.js format.js printf.js random.js matrix.js color.js optioned.js Chiron also provides "drivers" (to beg the kernel/driver/system analogy). These modules provide abstract, idiomatic interfaces to functionality available on the platform:: cookie.js date.js favicon.js flash.js history.js regexp.js sound.as, sound.js, sound.swf time.js Chiron has a selection of page controllers. Many of these ascribe to a different models for controlling elements of a web page and their interactions:: planes.js chiron.js csi.js form.js widget.js, widget.css, widget/ Particularly, Chiron has modules for controlling animation:: transition.js animate.js For details on any particular library, please read its API documentation. The build process constructs API documentation in a ``doc/`` directory from comments in the source code. Miscellaneous ------------- There are a couple of miscellaneous files here:: ajax.js __init__.py ``ajax.js`` exists because it's very likely the first place a developer will look when evaluating Chiron. Since AJAX code exists in almost every library, that code is often used to compare the quality of those libraries for a first impression. ``ajax.js`` contains a note on where to find that code (``http.js`` and ``modules.js``). ``__init__.py`` is merely a convenience file so that Python server-side libraries can import a module for the module root directory and thus use its ``__file__`` variable to resolve where it can find JavaScript to host without any configuration hassle.