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