# Apres Quick Start #

Here is a quick tutorial to get up and running quickly with Apres using
node.js. Note that Apres isn't picky about which web server you use, but it
includes a node server that is extremely easy to setup and use. So that's what
we will be using here.

First off, we need to install node.js, and npm.

### Debian Linux ###

For Debian, Ubuntu or any other Linux distribution with `apt-get`, you can
install node.js and npm using:

`apt-get install npm`

Note you may also need to use `sudo`.

### Other Systems ###

You can download node.js and npm from: http://nodejs.org/download/

## Creating An App ##

Now that we have node.js installed, we can create an Apres app. Simply create
a directory for your app and install Apres into it:

``` bash
$ mkdir myapp
$ cd myapp
$ npm install apres
```

The last command installs Apres locally *into* your app directory. This means
it is only available to this app. This is a feature of npm that allows
different apps to use different versions of their dependencies without
interfering with each other.

If you'd like to distribute your app, you can create a `package.json` file
to describe it. To do this, you can simply use:

``` bash
$ npm init
```

Then answer the prompts. To add Apres as a dependency to your package,
you can then run:

``` bash
$ npm install apres --save
```

Creating a package for your app is completely optional, but is highly
recommended if you want to be able to easily install your app elsewhere, or
distribute it to others via github or npm itself.

## Running A Local Server ##

For development, you can start Apres to run a local web server to serve files
for your application along with all of the Apres modules:

``` bash
$ npm start apres
```

This will run a local web server on port 8080 that will serve the contents
of your application directory, and the apres modules. To confirm it is working
navigate to http://localhost:8080/apres/ in your browser (Note you must
include the trailing slash in the URL).

### Choosing a Browser ###

For development, you should use a browser with an interactive debugger
installed. Google Chrome, Safari, and FireFox+FireBug are good choices.

## Making A View ##

Views are simply html pages that load Apres and declare some components. Let's
make a simple one. Create a file `index.html` in your application directory
containing this markup:

``` html
<html data-apres-controller="demo/hello">
<head>
  <title></title>
  <script data-main="apres/js/lib/apres-dev.js" src="apres/js/lib/require-1.0.8.js"></script>
</head>
<body>
</body>
</html>
```

You'll notice this is little more than an empty HTML document, save for two
things: A `<script>` tag to load Apres, and a `data-apres-controller`
attribute on the `<html>` element. This attribute declares the Javascript module
that is loaded as the controller for the page. In this case we load
the `demo/hello` controller that comes with Apres. Before we go any further
take a look at what it does by browsing to http://localhost:8080

If all goes well, in the browser you should see:

*Apres says: "Hello, World!"*

This text was inserted by the `demo/hello` controller when the page loaded.
Also notice that the title of the page is changed to "Hello World". 

### Adding A Widget ###

Controllers are interesting, but often you'll want to create code that affects
only a specific part of the page. Widgets are reusable components that are
attached to elements of a view. Let's add a widget that lets us easily look at
the source code of the components in our view. In the `<body>` of the
`index.html` document, add the following tag:

``` html
<div class="widget" data-widget="demo/sourcelinks"></div>
```

Save the file, and reload the page in your browser. You should now see some
links appear below the "Hello, World!" text. These links are generated by
the `sourcelinks` widget, which introspects the view, looking for controller
and widget declarations. It creates links to the source of each component
found, as well as the view itself, and inserts them into the widget's `<div>`.

From the tag we just added, we can glean two important rules about widget
declarations:

1. The widget element must be assigned the class "widget".
2. The widget module is specified using the `data-widget` attribute.

When Apres loads, the first thing it does is look for a controller
declaration, and load it if it find one. Next it scans the document for
elements with class *"widget"* and attaches a widget to each element where a
widget module is specified. Controllers and widgets are similar except that
controllers always load first, and are attached to the outermost element of
the document.  Widgets can load in any order, and can be attached to any
arbitrary element.

If you click on the *view controller source* link, you can see how the
`demo/hello` controller works. The most interesting thing in the *hello*
controller module is the `controller.ready()` function. This function will be
called automatically once the DOM is ready. Since the controller runs before
any widgets are loaded, it can manipulate the DOM anyway it likes, and even
create widgets dynamically if desired. This controller simply adds some
content to the view.

The *widget/sourcelinks* source link demonstrates a simple widget. Like
a controller, it can manipulate the DOM when it loads. However, typically
a widget only affects the DOM element it is attached to. In this case
a template is rendered into the widget's elements after scanning the page
and finding the controller and widgets.

## Other Examples ##

Now that you have a basic understanding of what makes Apres tick, here are
some other examples you can look at to learn more about its capabilities:

- [Markdown Example](http://apres.github.com/demo/markdown.html)

- [Include Example](http://apres.github.com/demo/include.html)

- [Handlebars Templating](http://apres.github.com/demo/handlebars.html)

- [Jade Templating](http://apres.github.com/demo/jade.html)

- [Pager Widget](http://apres.github.com/demo/pager.html)