easejs/doc/integration.texi

@c  This document is part of the ease.js manual
@c  Copyright (c) 2011 Mike Gerwitz
@c    Permission is granted to copy, distribute and/or modify this document
@c    under the terms of the GNU Free Documentation License, Version 1.3
@c    or any later version published by the Free Software Foundation;
@c    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
@c    Texts.  A copy of the license is included in the section entitled ``GNU
@c    Free Documentation License''.

@node Integration
@chapter Integrating ease.js

Before diving into ease.js, let's take a moment to get you set up. How ease.js
is integrated depends on how it is being used - on the server or in the client
(web browser). You may also wish to build ease.js yourself rather than
downloading pre-built packages. Depending on what you are doing, you may not
have to build ease.js at all.

@menu
* Source Tree::  Describes the project source tree
* Building::     How to build ease.js
* Including::    Including ease.js in your own project
@end menu

@node Source Tree
@section Source Tree
Before building, you need to get a hold of the source tree. Either download an
archive (tarball, zip, etc), or clone the Git repository. We will do the latter.
Feel free to clone from your favorite source.

@example
  # to clone from GitHub (do one or the other, not both)
  $ git clone git://github.com/mikegerwitz/easejs

  # to clone from Gitorious (do one or the other, not both)
  $ git clone git://gitorious.org/easejs/easejs.git
@end example

The repository will be cloned into the @file{./easejs} directory. Let's take a
look around.

@example
  $ cd easejs
  $ ls -d */
  doc/  lib/  test/  tools/
@end example

The project contains four main directories:

@table @file
@item ./
The root directory contains basic project files, such as @file{README},
@file{Makefile} and @file{index.js}.

@item doc/
Contains documentation source files (you are currently reading part of it - the
manual).

@item lib/
Contains the actual source code for the various modules.

@item test/
Contains unit tests.

@item tools/
Various tools used during build process.
@end table

Let's take a look at each directory in more detail.

@menu
* Root Directory::   Contains basic project files
* Doc Directory::    Contains source documentation files (manual)
* Lib Directory::    Contains project source files (modules)
* Test Directory::   Contains unit tests
* Tools Directory::  Contains build tools
@end menu

@node Root Directory
@subsection Root Directory
The root directory contains basic project files for common operations.

@table @file
@item index.js
This file is loaded automatically when @samp{require( 'easejs' )} is used.

@item LICENSE
Contains the project license.

@item Makefile
Invoked by the @command{make} command. Used for building ease.js.

@item package.json
Used by @command{npm}, a package manager for Node.js, to automate installation.

@item README.md
Serves as a quick reference for the project, in markdown@footnote{See
@uref{http://en.wikipedia.org/wiki/Markdown}.} format. This format was chosen
because it is displayed nicely on GitHub.

@item TODO
Incomplete tasks. Future direction of the project. If you're looking to help
out, take a look at this file to see what needs to be done.
@end table

These files will be discussed in further detail when they are actually used.


@node Doc Directory
@subsection Doc Directory
The @file{doc/} directory contains the source files for the manual. The source
files are in Texinfo@footnote{See @uref{http://www.gnu.org/software/texinfo/}.}
format. Instructions for compiling the documentation are included later in this
chapter.

API documentation is @emph{not} included in this directory. It is generated from
the source code.


@node Lib Directory
@subsection Lib Directory
The @file{lib/} directory contains the source code for the project. Each source
file represents a single CommonJS module and is written in JavaScript.

@table @file
@item class.js
The main Class module. This contains all the functionality necessary to declare
and extend classes, implement interfaces, etc. This is the bulk of ease.js.

@item interface.js
Allows declaration and extension of Interfaces.

@item member_builder.js
Responsible for building class members.

@item propobj.js
Builds the internal property instance object that is passed around to methods of
specific class instances. This is the magic behind visibility support, and
therefore encapsulation.

@item prop_parser.js
Parses property strings. Note that the name refers to JavaScript properties,
which are any members of an object. Therefore, this module works on all members.

@item util.js
General utility functions for property parsing, object cloning, browser
fallbacks, etc.
@end table

Unless you are developing for ease.js, you needn't concern yourself with these
files. @file{index.js}, in the root directory, contains mappings to these files
where necessary, exposing the useful portions of the API for general use. You
can use ease.js without even recognizing that the @file{lib/} directory even
exists.


@node Test Directory
@subsection Test Directory
The @file{test/} directory contains all the unit tests for the project. ease.js
follows a test-driven development model. Every single aspect of the framework is
tested to ensure that features work as intended both server-side and across all
supported web browsers. The tests also ensure that bugs are not introduced for
anything that has been covered. This should also give outside developers
confidence. If a developer makes a modification to ease.js and does not cause
any failing tests, it's likely that their change didn't have negative
consequences on the integrity of the framework.

All tests are prefixed with @samp{test-}, followed by the name of the module,
followed optionally by the specific part of the module that is being tested. The
tests are written in JavaScript and use Node.js's @file{assert} module. They may
be run individually or at once during the build process.

Tests are discussed later on in this chapter.


@node Tools Directory
@subsection Tools Directory
The @file{tools/} directory contains scripts and data necessary for the build
process. The tools are shell scripts that may be run independently of the build
process if you find them to be useful. The remaining files are data to accompany
those tools.

@table @file
@item combine
Concatenates all the modules and wraps them for client-side deployment. If
requested, the tests are also wrapped and concatenated so that they may be run
in the web browser. The contents are stripped of trailing commas using the
@command{rmtrail} tool. The resulting file is @emph{not} minified; the user can
use whatever process he/she wishes to do so. In the future, minification will be
part of the build script.

@item rmtrail
Removes trailing commas from object and array definitions. Reads from standard
in. @emph{This script is not intelligent.} It was designed to work with ease.js.
It does not, for example, check to ensure that it is not removing commas from
within strings. This would not be a difficult addition, but is currently
unnecessary. Use caution when using this tool outside of ease.js.

@item browser-test.html
Skeleton page to be used after the build process. Runs ease.js unit tests in the
web browser and reports any failures. This is very important to ensure that
ease.js operates consistently between all supported browsers. The tests that are
run are the same exact tests that are run server-side.

@item combine-test.tpl
Contains a client-side implementation of any modules required for testing. This
file contains mainly assertions. It is included by the @command{combine} script
when tests are requested.

@item combine.tpl
Contains the basic functionality required to get CommonJS modules working
client-side. This is a very basic implementation, only doing what is necessary
for ease.js to work properly. It is not meant to be a solution for all of your
client-side CommonJS problems.
@end table

While the tools may be useful outside of ease.js in some regard, please note
that they have been tailored especially for ease.js. They do not contain
unnecessary features that ease.js does not need to make use of. Therefore, you
may need to adapt them to your own project and individual needs should you
decide to use them in your own projects.


@node Building
@section Building
Feel free to skip this section if you have no interest in building ease.js
yourself. The build process is fast, and is unnecessary if using ease.js
server-side.

First, we should clarify what the term ``build'' means in context of ease.js.
JavaScript is compiled on the fly. That is, we don't actually need to compile it
manually through a build process. So when we are talking about ``building''
ease.js, we are not talking about compiling the source code. Rather, we are
referring to any of the following:

@itemize
@item
Prepare the script for client-side deployment [and testing]

@item
Generate the documentation (manual and API)
@end itemize

In fact, if you're using ease.js server-side with software such as Node.js, you
do not need to build anything at all. You can simply begin using it.

The aforementioned are built using @command{make}. The process that is run will
vary depending on your system. The command will read @file{Makefile} in the root
directory and execute the associated command. The following are the targets
available to you:

@table @command
@item mkbuild
Creates the @file{build/} directory, where all output will be stored. This is run
automatically by any of the targets.

@item combine
Runs the @command{combine} @ref{Tools Directory, tool} to produce two separate
files: @file{ease.js}, which can be used to use ease.js within the web browser,
and @file{ease-full.js}, which permits both using ease.js and running the unit
tests within the browser. The output is stored in the @file{build/} directory.

The unit tests can be run by opening the @file{build/browser-test.html} file in your
web browser.

@item test
Run unit tests. This will first perform the @command{combine} process and will
also run the tests for the combined script, ensuring that it was properly
combined.

Unit tests will be covered later in the chapter.

@item doc
Generates documentation. Currently, only the manual is build. API documentation
will be added in the near future. The resulting documentation will be stored in
@file{build/doc/}. For your convenience, the manual is output in the following
forms: PDF, HTML (single page), HTML (multiple pages) and plain text.

In order to build the documentation, you must have Texinfo installed. You likely
also need LaTeX installed. If you are on a Debian-based system, for example, you
will likely be able to run the following command to get started:

@example
  $ sudo apt-get install texlive texinfo
@end example

@item all
Runs all targets, except for clean.

@item clean
Cleans up after the build process by removing the @file{build/} directory.
@end table

If you do not want to build ease.js yourself, you are welcome to download the
pre-built files.


@node Including
@section Including ease.js In Your Projects
Using ease.js in your projects should be quick and painless. We'll worry about
the details of how to actually @emph{use} ease.js in a bit. For now, let's just
worry about how to include it in your project.

@menu
* Server-Side Include::  Including ease.js server-side
* Client-Side Include::  Including ease.js in the web browser
@end menu

@node Server-Side Include
@subsection Server-Side Include
ease.js should work with any CommonJS-compliant system. The examples below have
been tested with Node.js. Support is not guaranteed with any other software.

Let's assume that you have installed ease.js somewhere that is accessible to
@code{require.paths}. If you used a tool such as @command{npm}, this should have
been done for you.

@example
/** example-include.js **/
var easejs = require( 'easejs' );
@end example

It's important to understand what exactly the above command is doing. We are
including the @file{easejs/} directory (adjust your path as needed). Inside that
directory is the @file{index.js} file, which is loaded. The exports of that
module are returned and assigned to the @var{easejs} variable. We will discuss
what to actually do with those exports later on.

That's it. You should now have ease.js available to your project.

@node Client-Side Include
@subsection Client-Side Include (Web Browser)
ease.js can also be included in the web browser. Not only does this give you a
powerful Object-Oriented framework client-side, but it also facilitates code
reuse by permitting you to reuse your server-side code that depends on ease.js.

In order for ease.js to operate within the client, you must either download
@file{ease.js} or @ref{Building, build it yourself}. Let's assume that you have
placed @file{ease.js} within the @file{scripts/} directory of your web root.

@example
  <!-- to simply use ease.js -->
  <script type="text/javascript" src="/scripts/ease.js"></script>

  <!-- to include both the framework and the unit tests -->
  <script type="text/javascript" src="/scripts/ease-full.js"></script>
@end example

Likely, you only want the first one. The unit tests can more easily be run by
loading @file{build/browser-test.html} in your web browser (@pxref{Building}).

The script will define a global @var{easejs} variable, which can be used exactly
like the server-side @code{require()} (@pxref{Server-Side Include}). Keep that
in mind when going through the examples in this manual.