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.
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
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:
$ 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
to describe it. To do this, you can simply use:
$ npm init
Then answer the prompts. To add Apres as a dependency to your package, you can then run:
$ 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:
$ 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 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
<script> tag to load Apres, and a
attribute on the
that is loaded as the controller for the page. In this case we load
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:
<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
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
From the tag we just added, we can glean two important rules about widget declarations:
- The widget element must be assigned the class "widget".
- The widget module is specified using the
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.
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: