diff -r 4fe4ce7e2544 -r 60faaa480f02 doc/book/en/20-03-create-app.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/20-03-create-app.en.txt Thu Nov 20 15:00:34 2008 +0100 @@ -0,0 +1,204 @@ +.. -*- coding: utf-8 -*- + + +Creating your first application +=============================== + +XXXFIXME KEEP WHAT IS SPECIFIC TO APPENGINE AND MERGE THE REST WITH OVERVIEW OR +MAKE A NEW CHAPTER + +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.