Nagare Tutorial, learning concepts

The main goal of Nagare is to develop a web application like any standard python application. There are three steps to reach this goal:

• Do everything in python (no sql, no templating language, avoid hand-written javascript as much as possible)
• Hide the request/response connectionless nature of HTTP: no manual handling of the session
• Use aggregation as the shortest way to transform any python object into a Nagare component

Part 2. Modify the default application

1. With nagare-admin create-app a complete setuptools compatible package is created. Some Nagare specific files are also created:

   • conf/tutorial.cfg: application configuration file
   • data: folder where read/write datas are expected (sqlite database, csv files, etc.)
   • static: folder where html static files are stored (css, images and javascripts)
   • tutorial/models.py: module where the database models are defined using Elixir/SQLAlchemy ORM
   • tutorial/app.py: code of your application

2. Let's start with a pure python class. Replace the whole content of tutorial/app.py with:

class Counter(object):

    def __init__(self):
        self.val = 0

    def increase(self):
        self.val += 1

    def decrease(self):
        self.val -= 1

3. Now, add an HTML view for the Counter class:

from nagare import presentation
...
@presentation.render_for(Counter)
def render(counter, h, *args):
       return "Hello"

For Nagare, a view is just a function that takes a renderer (h) as a parameter and returns a DOM tree. In this example, we return a simple DOM tree with only one text node. To bind the view to the Counter class, we import the Nagare presentation service and use the render_for decorator.

4. Define the Nagare application:

For Nagare, an application is just an object factory (i.e. a callable that returns an object graph), and obviously a class is, so we just have to add the following to our app.py file:

...
# define app
app = Counter

5. You can now view your new web application in your browser (go to http://localhost:8080/tutorial).

If you take a look at the page source, you could see that Nagare has wrapped the text node into a valid html structure. By default, the DOM tree is serialized as HTML4. This can be changed in the application configuration file, to use XHTML if the browser accepts it.

6. A more complex DOM tree:

Replace the Counter view with the following one:

...
@presentation.render_for(Counter)
def render(counter, h, *args):
       return h.div("Value: ", counter.val)
...

As you can see the h HTML renderer can be used as a factory for all the HTML tags.

As we build a server-side DOM tree, we are protected against code injection. For example, if counter.val contains something like:

"<script>alert('Hello World');</script>"

This string would be escaped and no javascript will ever be executed.

Go to part 1 of this tutorial | Go to part 3 of this tutorial