Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
178 lines (125 sloc) 6.15 KB

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:

$ 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:

$ 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 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:

<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:

Further reading