|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 |
|
4 Creating your first application |
|
5 =============================== |
|
6 |
|
7 XXXFIXME KEEP WHAT IS SPECIFIC TO APPENGINE AND MERGE THE REST WITH OVERVIEW OR |
|
8 MAKE A NEW CHAPTER |
|
9 |
|
10 This tutorial will guide you step by step to build a blog application |
|
11 and discover the unique features of `LAX`. It assumes that you followed |
|
12 the installation guidelines and that both the `AppEngine SDK` and the |
|
13 `LAX` framework are setup on your computer. |
|
14 |
|
15 Creating a new application |
|
16 -------------------------- |
|
17 |
|
18 When you installed `LAX`, you saw a directory named ``skel``. Make a copy of |
|
19 this directory and call it ``BlogDemo``. |
|
20 |
|
21 Defining a schema |
|
22 ----------------- |
|
23 |
|
24 With `LAX`, the schema/datamodel is the core of the application. |
|
25 |
|
26 Let us start with something simple and improve on it iteratively. |
|
27 |
|
28 In schema.py, we define two entities : ``Blog`` and ``BlogEntry``. |
|
29 |
|
30 :: |
|
31 |
|
32 class Blog(EntityType): |
|
33 title = String(maxsize=50, required=True) |
|
34 description = String() |
|
35 |
|
36 class BlogEntry(EntityType): |
|
37 title = String(maxsize=100, required=True) |
|
38 publish_date = Date(default='TODAY') |
|
39 text = String(fulltextindexed=True) |
|
40 category = String(vocabulary=('important','business')) |
|
41 entry_of = SubjectRelation('Blog', cardinality='?*') |
|
42 |
|
43 A Blog has a title and a description. The title is a string that is |
|
44 required and must be less than 50 characters. The description is a |
|
45 string that is not constrained. |
|
46 |
|
47 A BlogEntry has a title, a publish_date and a text. The title is a |
|
48 string that is required and must be less than 100 characters. The |
|
49 publish_date is a Date with a default value of TODAY, meaning that |
|
50 when a BlogEntry is created, its publish_date will be the current day |
|
51 unless it is modified. The text is a string that will be indexed in |
|
52 the full-text index and has no constraint. |
|
53 |
|
54 A BlogEntry also has a relationship ``entry_of`` that link it to a |
|
55 Blog. The cardinality ``?*`` means that a BlogEntry can be part of |
|
56 zero or one Blog (``?`` means `zero or one`) and that a Blog can |
|
57 have any number of BlogEntry (``*`` means `any number including |
|
58 zero`). For completeness, remember that ``+`` means `one or more`. |
|
59 |
|
60 Using the application |
|
61 --------------------- |
|
62 |
|
63 Defining this simple schema is enough to get us started. Make sure you |
|
64 followed the setup steps described in detail in the installation |
|
65 chapter (especially visiting http://localhost:8080/_load as an |
|
66 administrator), then launch the application with the command:: |
|
67 |
|
68 python dev_appserver.py BlogDemo |
|
69 |
|
70 and point your browser at http://localhost:8080/ (if it is easier for |
|
71 you, use the on-line demo at http://lax.appspot.com/). |
|
72 |
|
73 .. image:: images/lax-book.00-login.en.png |
|
74 :alt: login screen |
|
75 |
|
76 After you log in, you will see the home page of your application. It |
|
77 lists the entity types: Blog and BlogEntry. If these links read |
|
78 ``blog_plural`` and ``blogentry_plural`` it is because |
|
79 internationalization (i18n) is not working for you yet. Please ignore |
|
80 this for now. |
|
81 |
|
82 .. image:: images/lax-book.01-start.en.png |
|
83 :alt: home page |
|
84 |
|
85 Let us create a few of these entities. Click on the [+] at the right |
|
86 of the link Blog. Call this new Blog ``Tech-blog`` and type in |
|
87 ``everything about technology`` as the description, then validate the |
|
88 form by clicking on ``button_ok``. |
|
89 |
|
90 .. image:: images/lax-book.02-create-blog.en.png |
|
91 :alt: from to create blog |
|
92 |
|
93 Click on the logo at top left to get back to the home page, then |
|
94 follow the Blog link. You should be seeing a list with a single item |
|
95 ``Tech-blog``. |
|
96 |
|
97 .. image:: images/lax-book.03-list-one-blog.en.png |
|
98 :alt: displaying a list of a single blog |
|
99 |
|
100 Clicking on this item will get you to its detailed description except |
|
101 that in this case, there is not much to display besides the name and |
|
102 the phrase ``everything about technology``. |
|
103 |
|
104 .. image:: images/lax-book.04-detail-one-blog.en.png |
|
105 :alt: displaying the detailed view of a blog |
|
106 |
|
107 Now get back to the home page by clicking on the top-left logo, then |
|
108 create a new Blog called ``MyLife`` and get back to the home page |
|
109 again to follow the Blog link for the second time. The list now |
|
110 has two items. |
|
111 |
|
112 .. image:: images/lax-book.05-list-two-blog.en.png |
|
113 :alt: displaying a list of two blogs |
|
114 |
|
115 Get back to the home page and click on [+] at the right of the link |
|
116 BlogEntry. Call this new entry ``Hello World`` and type in some text |
|
117 before clicking on ``button_ok``. You added a new blog entry without |
|
118 saying to what blog it belongs. There is a box on the left entitled |
|
119 ``actions``, click on the menu item ``modify``. You are back to the form |
|
120 to edit the blog entry you just created, except that the form now has |
|
121 another section with a combobox titled ``add relation``. Chose |
|
122 ``entry_of`` in this menu and a second combobox appears where you pick |
|
123 ``MyLife``. |
|
124 |
|
125 .. image:: images/lax-book.06-add-relation-entryof.en.png |
|
126 :alt: editing a blog entry to add a relation to a blog |
|
127 |
|
128 Validate the changes by clicking ``button_ok``. The entity BlogEntry |
|
129 that is displayed now includes a link to the entity Blog named |
|
130 ``MyLife``. |
|
131 |
|
132 .. image:: images/lax-book.07-detail-one-blogentry.en.png |
|
133 :alt: displaying the detailed view of a blogentry |
|
134 |
|
135 Remember that all of this was handled by the framework and that the |
|
136 only input that was provided so far is the schema. To get a graphical |
|
137 view of the schema, run the ``laxctl genschema BlogDemo`` command as |
|
138 explained in the installation section and point your browser to the |
|
139 URL http://localhost:8080/schema |
|
140 |
|
141 .. image:: images/lax-book.08-schema.en.png |
|
142 :alt: graphical view of the schema (aka data-model) |
|
143 |
|
144 Set-up a workflow |
|
145 ----------------- |
|
146 |
|
147 Before starting, make sure you refresh your mind by reading [link to |
|
148 definition_workflow chapter]. |
|
149 |
|
150 We want to create a workflow to control the quality of the BlogEntry |
|
151 submitted on your application. When a BlogEntry is created by a user |
|
152 its state should be `submitted`. To be visible to all, it needs to |
|
153 be in the state `published`. To move from `submitted` to `published` |
|
154 we need a transition that we can name `approve_blogentry`. |
|
155 |
|
156 We do not want every user to be allowed to change the state of a |
|
157 BlogEntry. We need to define a group of user, `moderators`, and |
|
158 this group will have appropriate permissions to approve BlogEntry |
|
159 to be published and visible to all. |
|
160 |
|
161 Create states and transitions |
|
162 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
163 Let us create a state `submitted`. Click on the [+] at the right |
|
164 of the link States. Call this new Blog ``submitted`` and type in |
|
165 ``Initial State of a BlogEntry`` as the description, then validate the |
|
166 form by clicking on ``Apply``. This will leave us in the editing form |
|
167 with an additional section to create the relations related to the |
|
168 entity State we juste created. Select the relation ``initial_state_of`` |
|
169 and select the entity type ``BlogEntry``. |
|
170 |
|
171 .. image:: images/lax-book.03-state-submitted.en.png |
|
172 |
|
173 |
|
174 |
|
175 |
|
176 Create group and set permissions |
|
177 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
178 |
|
179 |
|
180 |
|
181 Change view permission |
|
182 ~~~~~~~~~~~~~~~~~~~~~~ |
|
183 |
|
184 |
|
185 Conclusion |
|
186 ---------- |
|
187 |
|
188 Exercise |
|
189 ~~~~~~~~ |
|
190 |
|
191 Create new blog entries in ``Tech-blog``. |
|
192 |
|
193 What we learned |
|
194 ~~~~~~~~~~~~~~~ |
|
195 |
|
196 Creating a simple schema was enough to set up a new application that |
|
197 can store blogs and blog entries. |
|
198 |
|
199 What is next ? |
|
200 ~~~~~~~~~~~~~~ |
|
201 |
|
202 Although the application is fully functionnal, its look is very |
|
203 basic. In the following section we will learn to create views to |
|
204 customize how data is displayed. |