doc/book/MERGE_ME-tut-create-app.en.txt
changeset 10491 c67bcee93248
parent 1398 5fe84a5f7035
child 12792 e2cdb1be6bd9
equal deleted inserted replaced
10490:76ab3c71aff2 10491:c67bcee93248
       
     1 .. -*- coding: utf-8 -*-
       
     2 
       
     3 
       
     4 Tutoriel : créer votre première application web pour Google AppEngine
       
     5 =====================================================================
       
     6 
       
     7 [TRANSLATE ME TO FRENCH]
       
     8 
       
     9 This tutorial will guide you step by step to build a blog application 
       
    10 and discover the unique features of `LAX`. It assumes that you followed
       
    11 the :ref:`installation` guidelines and that both the `AppEngine SDK` and the
       
    12 `LAX` framework are setup on your computer.
       
    13 
       
    14 Creating a new application
       
    15 --------------------------
       
    16 
       
    17 We choosed in this tutorial to develop a blog as an example of web application
       
    18 and will go through each required steps/actions to have it running with `LAX`.
       
    19 When you installed `LAX`, you saw a directory named ``skel``. Make a copy of
       
    20 this directory and call it ``BlogDemo``.
       
    21 
       
    22 The location of this directory does not matter. But once decided, make sure your ``PYTHONPATH`` is properly set (:ref:`installation`).
       
    23 
       
    24 
       
    25 Defining a schema
       
    26 -----------------
       
    27 
       
    28 With `LAX`, the schema/datamodel is the core of the application. This is where
       
    29 you will define the type of content you have to hanlde in your application.
       
    30 
       
    31 Let us start with something simple and improve on it iteratively. 
       
    32 
       
    33 In schema.py, we define two entities: ``Blog`` and ``BlogEntry``.
       
    34 
       
    35 ::
       
    36 
       
    37   class Blog(EntityType):
       
    38       title = String(maxsize=50, required=True)
       
    39       description = String()
       
    40 
       
    41   class BlogEntry(EntityType):
       
    42       title = String(maxsize=100, required=True)
       
    43       publish_date = Date(default='TODAY')
       
    44       text = String(fulltextindexed=True)
       
    45       category = String(vocabulary=('important','business'))
       
    46       entry_of = SubjectRelation('Blog', cardinality='?*')
       
    47 
       
    48 A Blog has a title and a description. The title is a string that is
       
    49 required by the class EntityType and must be less than 50 characters. 
       
    50 The description is a string that is not constrained.
       
    51 
       
    52 A BlogEntry has a title, a publish_date and a text. The title is a
       
    53 string that is required and must be less than 100 characters. The
       
    54 publish_date is a Date with a default value of TODAY, meaning that
       
    55 when a BlogEntry is created, its publish_date will be the current day
       
    56 unless it is modified. The text is a string that will be indexed in
       
    57 the full-text index and has no constraint.
       
    58 
       
    59 A BlogEntry also has a relationship ``entry_of`` that link it to a
       
    60 Blog. The cardinality ``?*`` means that a BlogEntry can be part of
       
    61 zero or one Blog (``?`` means `zero or one`) and that a Blog can
       
    62 have any number of BlogEntry (``*`` means `any number including
       
    63 zero`). For completeness, remember that ``+`` means `one or more`.
       
    64 
       
    65 Running the application
       
    66 -----------------------
       
    67 
       
    68 Defining this simple schema is enough to get us started. Make sure you
       
    69 followed the setup steps described in detail in the installation
       
    70 chapter (especially visiting http://localhost:8080/_load as an
       
    71 administrator), then launch the application with the command::
       
    72 
       
    73    python dev_appserver.py BlogDemo
       
    74 
       
    75 and point your browser at http://localhost:8080/ (if it is easier for
       
    76 you, use the on-line demo at http://lax.appspot.com/).
       
    77 
       
    78 .. image:: images/lax-book.00-login.en.png
       
    79    :alt: login screen
       
    80 
       
    81 After you log in, you will see the home page of your application. It
       
    82 lists the entity types: Blog and BlogEntry. If these links read
       
    83 ``blog_plural`` and ``blogentry_plural`` it is because
       
    84 internationalization (i18n) is not working for you yet. Please ignore
       
    85 this for now.
       
    86 
       
    87 .. image:: images/lax-book.01-start.en.png
       
    88    :alt: home page
       
    89 
       
    90 Creating system entities
       
    91 ------------------------
       
    92 You can only create new users if you decided not to use google authentication.
       
    93 
       
    94 
       
    95 [WRITE ME : create users manages permissions etc]
       
    96 
       
    97 
       
    98 
       
    99 Creating application entites
       
   100 ----------------------------
       
   101 
       
   102 Create a Blog
       
   103 ~~~~~~~~~~~~~
       
   104 
       
   105 Let us create a few of these entities. Click on the [+] at the right
       
   106 of the link Blog.  Call this new Blog ``Tech-blog`` and type in
       
   107 ``everything about technology`` as the description, then validate the
       
   108 form by clicking on ``Validate``.
       
   109 
       
   110 .. image:: images/lax-book.02-create-blog.en.png
       
   111    :alt: from to create blog
       
   112 
       
   113 Click on the logo at top left to get back to the home page, then
       
   114 follow the Blog link that will list for you all the existing Blog.
       
   115 You should be seeing a list with a single item ``Tech-blog`` you
       
   116 just created.
       
   117 
       
   118 .. image:: images/lax-book.03-list-one-blog.en.png
       
   119    :alt: displaying a list of a single blog
       
   120 
       
   121 Clicking on this item will get you to its detailed description except
       
   122 that in this case, there is not much to display besides the name and
       
   123 the phrase ``everything about technology``.
       
   124 
       
   125 .. image:: images/lax-book.04-detail-one-blog.en.png
       
   126   :alt: displaying the detailed view of a blog
       
   127 
       
   128 Now get back to the home page by clicking on the top-left logo, then
       
   129 create a new Blog called ``MyLife`` and get back to the home page
       
   130 again to follow the Blog link for the second time. The list now
       
   131 has two items.
       
   132 
       
   133 .. image:: images/lax-book.05-list-two-blog.en.png
       
   134    :alt: displaying a list of two blogs
       
   135 
       
   136 
       
   137 Create a BlogEntry
       
   138 ~~~~~~~~~~~~~~~~~~
       
   139 
       
   140 Get back to the home page and click on [+] at the right of the link
       
   141 BlogEntry. Call this new entry ``Hello World`` and type in some text
       
   142 before clicking on ``Validate``. You added a new blog entry without
       
   143 saying to what blog it belongs. There is a box on the left entitled
       
   144 ``actions``, click on the menu item ``modify``. You are back to the form
       
   145 to edit the blog entry you just created, except that the form now has
       
   146 another section with a combobox titled ``add relation``. Chose
       
   147 ``entry_of`` in this menu and a second combobox appears where you pick
       
   148 ``MyLife``. 
       
   149 
       
   150 You could also have, at the time you started to fill the form for a
       
   151 new entity BlogEntry, hit ``Apply`` instead of ``Validate`` and the 
       
   152 combobox titled ``add relation`` would have showed up.
       
   153 
       
   154 .. image:: images/lax-book.06-add-relation-entryof.en.png
       
   155    :alt: editing a blog entry to add a relation to a blog
       
   156 
       
   157 Validate the changes by clicking ``Validate``. The entity BlogEntry
       
   158 that is displayed now includes a link to the entity Blog named
       
   159 ``MyLife``.
       
   160 
       
   161 .. image:: images/lax-book.07-detail-one-blogentry.en.png
       
   162    :alt: displaying the detailed view of a blogentry
       
   163 
       
   164 Remember that all of this was handled by the framework and that the
       
   165 only input that was provided so far is the schema. To get a graphical
       
   166 view of the schema, run the ``laxctl genschema BlogDemo`` command as
       
   167 explained in the installation section and point your browser to the
       
   168 URL http://localhost:8080/schema
       
   169 
       
   170 .. image:: images/lax-book.08-schema.en.png
       
   171    :alt: graphical view of the schema (aka data-model)
       
   172 
       
   173 Site configuration
       
   174 ------------------
       
   175 
       
   176 .. image:: images/lax-book.03-site-config-panel.en.png
       
   177 
       
   178 This panel allows you to configure the appearance of your application site.
       
   179 Six menus are available and we will go through each of them to explain how
       
   180 to use them.
       
   181 
       
   182 Navigation
       
   183 ~~~~~~~~~~
       
   184 This menu provides you a way to adjust some navigation options depending on
       
   185 your needs, such as the number of entities to display by page of results.
       
   186 Follows the detailled list of available options:
       
   187   
       
   188 * navigation.combobox-limit: maximum number of entities to display in related
       
   189   combo box (sample format: 23)
       
   190 * navigation.page-size: maximum number of objects displayed by page of results 
       
   191   (sample format: 23)
       
   192 * navigation.related-limit: maximum number of related entities to display in 
       
   193   the primary view (sample format: 23)
       
   194 * navigation.short-line-size: maximum number of characters in short description
       
   195   (sample format: 23)
       
   196 
       
   197 UI
       
   198 ~~
       
   199 This menu provides you a way to customize the user interface settings such as
       
   200 date format or encoding in the produced html.
       
   201 Follows the detailled list of available options:
       
   202 
       
   203 * ui.date-format : how to format date in the ui ("man strftime" for format description)
       
   204 * ui.datetime-format : how to format date and time in the ui ("man strftime" for format
       
   205   description)
       
   206 * ui.default-text-format : default text format for rich text fields.
       
   207 * ui.encoding : user interface encoding
       
   208 * ui.fckeditor : should html fields being edited using fckeditor (a HTML WYSIWYG editor).
       
   209   You should also select text/html as default text format to actually get fckeditor.
       
   210 * ui.float-format : how to format float numbers in the ui
       
   211 * ui.language : language of the user interface
       
   212 * ui.main-template : id of main template used to render pages
       
   213 * ui.site-title	: site title, which is displayed right next to the logo in the header
       
   214 * ui.time-format : how to format time in the ui ("man strftime" for format description)
       
   215 
       
   216 
       
   217 Actions
       
   218 ~~~~~~~
       
   219 This menu provides a way to configure the context in which you expect the actions
       
   220 to be displayed to the user and if you want the action to be visible or not. 
       
   221 You must have notice that when you view a list of entities, an action box is 
       
   222 available on the left column which display some actions as well as a drop-down 
       
   223 menu for more actions. 
       
   224 
       
   225 The context available are:
       
   226 
       
   227 * mainactions : actions listed in the left box
       
   228 * moreactions : actions listed in the `more` menu of the left box
       
   229 * addrelated : add actions listed in the left box
       
   230 * useractions : actions listed in the first section of drop-down menu 
       
   231   accessible from the right corner user login link
       
   232 * siteactions : actions listed in the second section of drop-down menu
       
   233   accessible from the right corner user login link
       
   234 * hidden : select this to hide the specific action
       
   235 
       
   236 Boxes
       
   237 ~~~~~
       
   238 The application has already a pre-defined set of boxes you can use right away. 
       
   239 This configuration section allows you to place those boxes where you want in the
       
   240 application interface to customize it. 
       
   241 
       
   242 The available boxes are:
       
   243 
       
   244 * actions box : box listing the applicable actions on the displayed data
       
   245 
       
   246 * boxes_blog_archives_box : box listing the blog archives 
       
   247 
       
   248 * possible views box : box listing the possible views for the displayed data
       
   249 
       
   250 * rss box : RSS icon to get displayed data as a RSS thread
       
   251 
       
   252 * search box : search box
       
   253 
       
   254 * startup views box : box listing the configuration options available for 
       
   255   the application site, such as `Preferences` and `Site Configuration`
       
   256 
       
   257 Components
       
   258 ~~~~~~~~~~
       
   259 [WRITE ME]
       
   260 
       
   261 Contextual components
       
   262 ~~~~~~~~~~~~~~~~~~~~~
       
   263 [WRITE ME]
       
   264 
       
   265 Set-up a workflow
       
   266 -----------------
       
   267 
       
   268 Before starting, make sure you refresh your mind by reading [link to
       
   269 definition_workflow chapter].
       
   270 
       
   271 We want to create a workflow to control the quality of the BlogEntry 
       
   272 submitted on your application. When a BlogEntry is created by a user
       
   273 its state should be `submitted`. To be visible to all, it needs to
       
   274 be in the state `published`. To move from `submitted` to `published`
       
   275 we need a transition that we can name `approve_blogentry`.
       
   276 
       
   277 We do not want every user to be allowed to change the state of a 
       
   278 BlogEntry. We need to define a group of user, `moderators`, and 
       
   279 this group will have appropriate permissions to approve BlogEntry
       
   280 to be published and visible to all.
       
   281 
       
   282 There are two ways to create a workflow, form the user interface,
       
   283 and also by defining it in ``migration/postcreate.py``. This script
       
   284 is executed each time a new ``./bin/laxctl db-init`` is done. 
       
   285 If you create the states and transitions through the user interface
       
   286 this means that next time you will need to initialize the database
       
   287 you will have to re-create all the entities. 
       
   288 We strongly recommand you create the workflow in ``migration\postcreate.py``
       
   289 and we will now show you how.
       
   290 The user interface would only be a reference for you to view the states 
       
   291 and transitions but is not the appropriate interface to define your
       
   292 application workflow.
       
   293 
       
   294 Update the schema
       
   295 ~~~~~~~~~~~~~~~~~
       
   296 To enable a BlogEntry to have a State, we have to define a relation
       
   297 ``in_state`` in the schema of BlogEntry. Please do as follows, add
       
   298 the line ``in_state (...)``::
       
   299 
       
   300   class BlogEntry(EntityType):
       
   301       title = String(maxsize=100, required=True)
       
   302       publish_date = Date(default='TODAY')
       
   303       text_format = String(meta=True, internationalizable=True, maxsize=50,
       
   304                            default='text/rest', constraints=[format_constraint])
       
   305       text = String(fulltextindexed=True)
       
   306       category = String(vocabulary=('important','business'))
       
   307       entry_of = SubjectRelation('Blog', cardinality='?*')
       
   308       in_state = SubjectRelation('State', cardinality='1*')
       
   309 
       
   310 As you updated the schema, you will have re-execute ``./bin/laxctl db-init``
       
   311 to initialize the database and migrate your existing entities.
       
   312 [WRITE ABOUT MIGRATION]
       
   313 
       
   314 Create states, transitions and group permissions
       
   315 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       
   316 
       
   317 At the time the ``postcreate.py`` script is executed, several methods
       
   318 can be used. They are all defined in the ``class ServerMigrationHelper``.
       
   319 We will only discuss the method we use to create a wrokflow here.
       
   320 
       
   321 To define our workflow for BlogDemo, please add the following lines
       
   322 to ``migration/postcreate.py``::
       
   323   
       
   324   _ = unicode
       
   325 
       
   326   moderators      = add_entity('CWGroup', name=u"moderators")
       
   327 
       
   328   submitted = add_state(_('submitted'), 'BlogEntry', initial=True)
       
   329   published = add_state(_('published'), 'BlogEntry')
       
   330 
       
   331   add_transition(_('approve_blogentry'), 'BlogEntry', (submitted,), published, ('moderators', 'managers'),)
       
   332 
       
   333   checkpoint()
       
   334 
       
   335 ``add_entity`` is used here to define the new group of users that we
       
   336 need to define the transitions, `moderators`.
       
   337 If this group required by the transition is not defined before the
       
   338 transition is created, it will not create the relation `transition 
       
   339 require the group moderator`.
       
   340 
       
   341 ``add_state`` expects as the first argument the name of the state you are
       
   342 willing to create, then the entity type on which the state can be applied, 
       
   343 and an optionnal argument to set if the state is the initial state
       
   344 of the entity type or not.
       
   345 
       
   346 ``add_transition`` expects as the first argument the name of the 
       
   347 transition, then the entity type on which we can apply the transition,
       
   348 then the list of possible initial states from which the transition
       
   349 can be applied, the target state of the transition, and the permissions
       
   350 (e.g. list of the groups of users who can apply the transition).
       
   351 
       
   352 .. image:: images/lax-book.03-transitions-view.en.png
       
   353 
       
   354 You can now notice that in the actions box of a BlogEntry, the state
       
   355 is now listed as well as the possible transitions from this state
       
   356 defined by the workflow. This transition, as defined in the workflow,
       
   357 will only being displayed for the users belonging to the group
       
   358 moderators of managers.
       
   359 
       
   360 Change view permission
       
   361 ~~~~~~~~~~~~~~~~~~~~~~
       
   362 
       
   363 
       
   364 
       
   365 Conclusion
       
   366 ----------
       
   367 
       
   368 Exercise
       
   369 ~~~~~~~~
       
   370 
       
   371 Create new blog entries in ``Tech-blog``.
       
   372 
       
   373 What we learned
       
   374 ~~~~~~~~~~~~~~~
       
   375 
       
   376 Creating a simple schema was enough to set up a new application that
       
   377 can store blogs and blog entries. 
       
   378 
       
   379 What is next ?
       
   380 ~~~~~~~~~~~~~~
       
   381 
       
   382 Although the application is fully functionnal, its look is very
       
   383 basic. In the following section we will learn to create views to
       
   384 customize how data is displayed.
       
   385 
       
   386