.. -*- coding: utf-8 -*-

=============
LAX Tutorial
=============

Introduction
============

LAX stands for Logilab App engine eXtension. It is a web framework
running on top of the Google AppEngine datastore.

Distinctive features include a data-model driven engine, a query
language, a selection/view mechanism for HTML/XML/text generation,
reuseable components, etc. It all sums up to very fast and efficient
development.

This tutorial will guide you to build a blog application step by step
to discover the unique features of LAX. It assumes that you followed
the installation guidelines and that both the AppEngine SDK and the
LAX framework are setup on your computer.

Creating a very simple application
==================================

Creating a new application
--------------------------

When you installed lax, you saw a directory named skel. Make a copy of
this directory and call it BlogDemo.

Defining a schema
-----------------

With LAX, the schema/datamodel is the core of the application.

Let us start with something simple and improve on it later. First, we
make sure that in appconfig.py we have a line ::

  schema_type = 'yams'

Then, in schema.py, we define two entities : ``Blog`` and ``BlogEntry``.

::
				   
  class Blog(EntityType):
      title = String(maxsize=50, required=True)
      description = String()

  class BlogEntry(EntityType):
      title = String(maxsize=100, required=True)
      publish_date = Date(default='TODAY')
      text = String(fulltextindexed=True)
      category = String(vocabulary=('important','business'))
      entry_of = SubjectRelation('Blog', cardinality='?*')

A Blog has a title and a description. The title is a string that is
required and must be less than 50 characters. The description is a
string that is not constrained.

A BlogEntry has a title, a publish_date and a text. The title is a
string that is required and must be less than 100 characters. The
publish_date is a Date with a default value of TODAY, meaning that
when a BlogEntry is created, its publish_date will be the current day
unless it is modified. The text is a string that will be indexed in
the full-text index and has no constraint.

A BlogEntry also has a relationship ``entry_of`` that link it to a
Blog. The cardinality ``?*`` means that a BlogEntry can be part of
zero or one Blog (``?`` means `zero or one`) and that a Blog can
have any number of BlogEntry (``*`` means `any number including
zero`). For completeness, remember that ``+`` means `one or more`.

:note: in lax-0.3.0, cardinality checking is not fully ported to
AppEngine, so cardinality limits are not enforced. This should be
fixed in lax-0.4.0 available at the beginning of June.

Using the application
---------------------

Defining this simple schema is enough to get us started. Launch the
application with the command::

   python dev_appserver.py BlogDemo

and point your browser at localhost:8080

You will see the home page of your application. It lists the entity
types: Blog and BlogEntry.

Let us create a few of these. Click on the [+] at the right of the
link Blog. Call this new Blog ``Tech-blog`` and type in
``everything about technology`` as the description, then validate the
form by clicking on ``button_ok``.

Click on the logo at top left to get back to the home page, then
follow the Blog link. If this link reads ``blog_plural`` it is because
i18n is not working for you yet. Let us ignore this for a while. After
following the link, you should be seeing a list with a single item
``Tech-blog``. Clicking on this item will get you to its detailed
description except that in this case, there is not much to display
besides the name and the phrase ``everything about technology``.

Now get back to the home page by clicking on the top-left logo, then
create a new Blog called ``MyLife`` and get back to the home page
again to follow the Blog link for the second time. The list now
has two items.

Get back to the home page and click on [+] at the right of the link
BlogEntry. Call this new entry ``Hello World`` and type in some text
before clicking on ``button_ok``. You added a new blog entry without
saying to what blog it belongs. There is a box on the left entitled
``actions``, click on the menu item ``modify``. You are back to the form
to edit the blog entry you just created, except that the form now has
another section with a combobox titled ``add relation``. Chose
``entry_of`` in this menu and a second combobox appears where you pick
``MyLife``. Validate the changes by clicking
``button_ok``. The entity BlogEntry that is displayed now includes a link
to the entity Blog named ``MyLife``.

Conclusion
----------

Exercise
~~~~~~~~

Create new blog entries in ``Tech-blog``.

What we learned
~~~~~~~~~~~~~~~

Creating a simple schema was enough to set up a new application that
can store blogs and blog entries. 

What is next ?
--------------

Althought the application is fully functionnal, its look is very
basic. We will now improve how information is displayed by writing
views.


Developing the user interface with Views
========================================

[WRITE ME]

* Defining views with selection/views

* implementing interfaces, calendar for blog entries.

* show that a calendar view can export data to ical. 

* create view "blogentry table" with title, publish_date, category.

* in view blog, select blogentries and apply view "blogentry table"

* demo ajax by filtering blogentry table on category

Components
===========

[WRITE ME]

* explain the component architecture

* add comments to the blog by importing the comments component

Boxes
======

[WRITE ME]

* explain how to build a box

* add an blogentry archives box

Preferences
============

[WRITE ME]

* talk about the user preferences

* add an example on how to hide / display / move a component or a box

MainTemplate
============

[WRITE ME]

* customize MainTemplate and show that everything in the user
  interface can be changed


RSS Channel
===========

[WRITE ME]

* show that the RSS view can be used to display an ordered selection
  of blog entries, thus providing a RSS channel

* show that a different selection (by category) means a different channel

RQL
====

[WRITE ME]

* talk about the Relation Query Language

URL Rewriting
=============

[WRITE ME]

* show how urls are mapped to selections and views and explain URLRewriting 

Security
=========

[WRITE ME]

* talk about security access rights and show that security is defined
  using RQL