186 lines
7.2 KiB
Plaintext
186 lines
7.2 KiB
Plaintext
@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
|
|
* Getting ease.js:: How to get ease.js
|
|
* Building:: How to build ease.js
|
|
* Including:: Including ease.js in your own project
|
|
@end menu
|
|
|
|
|
|
@node Getting ease.js
|
|
@section Getting ease.js
|
|
If you simply want to use ease.js in your project, you may be interested in
|
|
simply grabbing an archive (tarball, zip, etc), or installing through your
|
|
favorite package manger. More information on those options will become available
|
|
as ease.js nears its first release.
|
|
|
|
If you are interested in building ease.js, 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 in the example below. 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.
|
|
|
|
|
|
@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 min
|
|
Runs @command{combine} and minifies the resulting combined files. These files
|
|
are output in the @file{build/} directory and are useful for distribution. It is
|
|
recommended that you use the minified files in production.
|
|
|
|
@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.
|
|
|