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


Creating your first application
===============================

This tutorial will guide you step by step to build a blog application 
and 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 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 iteratively. 

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`.

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

Defining this simple schema is enough to get us started. Make sure you
followed the setup steps described in detail in the installation
chapter (especially visiting http://localhost:8080/_load as an
administrator), then launch the application with the command::

   python dev_appserver.py BlogDemo

and point your browser at http://localhost:8080/ (if it is easier for
you, use the on-line demo at http://lax.appspot.com/).

.. image:: images/lax-book.00-login.en.png
   :alt: login screen

After you log in, you will see the home page of your application. It
lists the entity types: Blog and BlogEntry. If these links read
``blog_plural`` and ``blogentry_plural`` it is because
internationalization (i18n) is not working for you yet. Please ignore
this for now.

.. image:: images/lax-book.01-start.en.png
   :alt: home page

Let us create a few of these entities. 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``.

.. image:: images/lax-book.02-create-blog.en.png
   :alt: from to create blog

Click on the logo at top left to get back to the home page, then
follow the Blog link.  You should be seeing a list with a single item
``Tech-blog``.

.. image:: images/lax-book.03-list-one-blog.en.png
   :alt: displaying a list of a single 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``.

.. image:: images/lax-book.04-detail-one-blog.en.png
   :alt: displaying the detailed view of a blog

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.

.. image:: images/lax-book.05-list-two-blog.en.png
   :alt: displaying a list of two blogs

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``. 

.. image:: images/lax-book.06-add-relation-entryof.en.png
   :alt: editing a blog entry to add a relation to a blog

Validate the changes by clicking ``button_ok``. The entity BlogEntry
that is displayed now includes a link to the entity Blog named
``MyLife``.

.. image:: images/lax-book.07-detail-one-blogentry.en.png
   :alt: displaying the detailed view of a blogentry

Remember that all of this was handled by the framework and that the
only input that was provided so far is the schema. To get a graphical
view of the schema, run the ``laxctl genschema BlogDemo`` command as
explained in the installation section and point your browser to the
URL http://localhost:8080/schema

.. image:: images/lax-book.08-schema.en.png
   :alt: graphical view of the schema (aka data-model)

Set-up a workflow
-----------------

Before starting, make sure you refresh your mind by reading [link to
definition_workflow chapter].

We want to create a workflow to control the quality of the BlogEntry 
submitted on your application. When a BlogEntry is created by a user
its state should be `submitted`. To be visible to all, it needs to
be in the state `published`. To move from `submitted` to `published`
we need a transition that we can name `approve_blogentry`.

We do not want every user to be allowed to change the state of a 
BlogEntry. We need to define a group of user, `moderators`, and 
this group will have appropriate permissions to approve BlogEntry
to be published and visible to all.

Create states and transitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let us create a state `submitted`. Click on the [+] at the right
of the link States.  Call this new Blog ``submitted`` and type in
``Initial State of a BlogEntry`` as the description, then validate the
form by clicking on ``Apply``. This will leave us in the editing form
with an additional section to create the relations related to the
entity State we juste created. Select the relation ``initial_state_of``
and select the entity type ``BlogEntry``.

.. image:: images/lax-book.03-state-submitted.en.png




Create group and set permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



Change view permission
~~~~~~~~~~~~~~~~~~~~~~


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 ?
~~~~~~~~~~~~~~

Although the application is fully functionnal, its look is very
basic. In the following section we will learn to create views to
customize how data is displayed.