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