# Apres Overview #

Apres is designed to make client-side web development more reasonable and less
frustrating. Apres is a framework, and suite of tools written in Javascript
designed to make your life easier. To introduce Apres, we''ll go over a few key
concepts:

- Modules
- Views
- Controllers 
- Widgets 
- Skins

## Getting Started ##

Although you can serve Apres anyway you like, one of the easiest ways to get
up and running is to use `npm` to install apres into a directory for your
application, then use node.js as a local static web server. Apres includes
a simple middleware adapter that makes this extremely easy. The first step
is to install `npm` and node on your system.

If you are running Debian, or Ubuntu Linux you can use `apt-get install npm`.
For other platforms, you can download the node.js installer from 
http://nodejs.org/download/

Once you have node, and npm installed, make a directory for your app and
create a `package.json` file inside with the following contents:

``` javascript
{
    "name": "my-first-app",
    "dependencies": {"apres": "*"}
}
```

## Modules ##

A module is the unit of code used by Apres. Since Javascript does not include
native support for modules, Apres uses [requirejs][1], which is an excellent
implementation of the AMD Javascript module standard.

If you are familiar with other Javascript environments, such as node.js, you
may be wondering why Apres uses a different module system than the CommonJS
API employed by node. The reason is that AMD modules are expressly designed
for completely asynchronous enviroments, such as a web browser. Although
node.js is touted as an async environment, it''s module system uses a
synchronous blocking model. This makes the CommonJS/node module system
unsuitable for the browser, and Apres.*

When developing, modules are typically each created in separate files. When
running your app, modules are loaded on demand. Modules can readily depend
on each other to allow you to organize your app into components as you see
fit. Apres has conventions for modules that define components such as
controllers, widgets, and skins. Library modules can follow any api convention
desired.

Apres comes bundled with many useful libraries, and components for you to use.
It is also easy for you to add additional libraries and components for your app
via modules. The section on [modules][modules.md] provides additional details.

* **Note there are projects that attempt to make CommonJS modules work in the
browser, but they require an additional build system, which is incompatible with
Apres'' "code then reload" development philosophy**

[1]: http://requirejs.org/

## Views ##

An Apres view is simply an HTML page. Apres itself has no opinion whether your
app is contained in a single page, or many different pages. It is possible to
create single page apps in Apres, but it is generally better to divide more
complex apps into several different page views for improved modularity.
Ultimately this is up to the app developer, however, and Apres requires no
particular URL structure for specifying views. Apres is also agnostic about
the server used to deliver its views. Any web server that can deliver an HTML
page in response to a URL can serve an Apres app.

An Apres view is a bit more than a vanilla static HTML page, however. Apres
utilizes HTML5''s `data-` attributes to designate where in the view
components, such as a controller, widgets, or skins should be employed. When
the HTML view is loaded into the browser, Apres is activated and it scans the
page DOM for component declarations. These declarations cause the view, and
the app, to come to life.

To activate Apres, for a given page, turning it into an Apres view, you must
include a single `<script>` tag to your markup. The `<script>` tag actually
loads requirejs first, then includes Apres as the main module to load and run.
If you are serving the Apres modules along with your view, you
could use something like this:

``` html
<script data-main="/js/lib/apres-dev.js" src="/js/lib/require.js"></script>
```

This uses the current development version of Apres. Once versioned releases
are made, you will be able to target a particular release version.

Although that's all you need to turn an HTML page into an Apres view, it
doesn't do anything special yet because the view doesn't use any components.
Next, we'll see how to do that.

## Controllers ##

Controllers are a simple type of Apres component that can be plugged into
a view. A controller is defined in a Javascript module.