[doc] Initial translation of first two section in installation chapter.
.. -*- 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.