Mercurial > libervia-web

annotate doc/web_framework/quick_start.rst @ 1185:7d6c0e5d5f34

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
server: moved generic classes definitions (only WebsocketMeta for now) to new "classes" module
author Goffi <goffi@goffi.org>
date Sun, 26 May 2019 22:14:23 +0200
parents 4648a333b33f
children fe5c282461bd
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
1 ==================================
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
2 Libervia Web Framework Quick Start
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ==================================
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
4
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
5 This documentation will help you getting started with Libervia Web Framework to create your first web site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
6
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Creating an external site
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
8 -------------------------
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
9
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
10 First let's get basic vocabulary we'll use: a "site" is all the data necessary to display a full web site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
11 A site have one or more "themes" which is a way to display it. A theme may be anything from simple style change (e.g. "dark" theme, or "high contrast"), to a complete rework of the apparence of a site, but keep the same pages structure (see below). If you want to change pages structure, you have to make a new site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
12 A site is made of pages and templates. Pages are the code which gather and manipulate the data, and templates are about the final rendering.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
13 Don't worry too much if you don't get it yet, we'll see that with a practical example.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
14
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
15 We'll create the classical "Salut à Toi le monde" site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
16
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
17 You first have to choose a location were your site will be. We name "external site" any site which is not the standard Libervia site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
18 Choose a location, for instance ``~/dev/libervia_quick_start`` then create the following hierarchy or directories inside it:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
19
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
20 - templates/
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
21 - default/
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
22 - pages/
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
23 - i18n/
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
24
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
25 ``templates`` is where you'll put… template, used to render the final pages. ``default`` is a theme name, this one is special as is it the main theme of your site and must always exist.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
26 ``pages`` is where you'll put python code to manipulate data of your site.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
27 ``i18n`` is used for translating your site in other languages, but we'll get to this later.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
28
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
29 Now we have to declare this new site to Salut à Toi and Libervia. When installing Salut à Toi, you should have created a ``sat.conf`` file, if not, just create one at ``~/.sat.conf``.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
30 Edit this file, and in the section ``[DEFAULT]``, add the following setting:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
31
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
32 .. sourcecode:: javascript
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
33
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
34 sites_path_public_dict = {
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
35 "quick_start": "~/dev/libervia_quick_start"
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
36 }
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
37
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
38 This declare the templates of your websites, you'll now be able to use them with tools like ``jp``.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
39
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
40 Now you have to add your site to Libervia. Choose a host name, and link it to the site name by adding a ``vhost_dict`` setting in your ``[libervia]`` section of ``sat.conf``:
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
41
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
42 .. sourcecode:: javascript
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
43
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
44 vhosts_dict = {"quickstart.int": "quick_start"}
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
45
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
46 That means that when you'll get to ``quickstart.int``, you'll land to your own site instead of official Libervia one.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
47
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
48 Last but not least, you have to declare this website as alias for your localhost during developments. On GNU/Linux, this is done by editing ``/etc/hosts`` (as root user), to have something like that::
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
49
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
50 127.0.0.1 localhost.localdomain localhost quickstart.int
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
51 ::1 localhost.localdomain localhost quickstart.int
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
52
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
53 To see your website, you'll have to use the specified host name, and the port used by Libervia (8080 by default). If you kept default configuration, let's go to http://quickstart.int:8080.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
54
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
55 But for now, you'll just see ``No Such Resource`` (if you see standard Libervia site, that means that something is not working, you can check for assistance in our XMPP room at `sat@chat.jabberfr.org <xmpp:sat@chat.jabberfr.org?join>`_).
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
56
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
57 All right? Good, let's start then.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
58
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
59 A first template
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
60 ----------------
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
61
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
62 For this simple page, we won't have any data to manipulate, so let's start directly with the template.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Create a ``salut.html`` file at ``templates/default/salut/salut.html`` inside your development directory, and put the following content inside:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
64
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
65 .. sourcecode:: jinja
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
66
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
67 {% if not embedded %}{% extends 'base/base.html' %}{% endif %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
68
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
69 {% block body %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
70 Salut à Toi le monde !
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
71 {% endblock body %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
72
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
73 Let's explain a bit.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
74
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
75 The template use Jinja2_ engine, which is easy to learn and powerful. You have the documentation available on the official website, you should read in particular the `Template Designer Documentation <http://jinja.pocoo.org/docs/latest/templates/>`_.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
76
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
77 .. sourcecode:: jinja
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
78
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
79 {% if not embedded %}{% extends 'base/base.html' %}{% endif %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
80
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
81 This firt line should be present on every front page, it extends the base template which handle many things for you and to facilitate integration with the backend. "But I have not written any ``base/base.html`` template" you may say. That's right, that's because SàT template engine is looking for file in several places. When you link a template, first it will check the current theme of your site, then the ``default`` theme, and finally the ``default`` theme of SàT official site. That allows you to have access to the generic features like the backend integration.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
82
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
83 .. sourcecode:: jinja
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
84
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
85 {% block body %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
86 Salut à Toi le monde !
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
87 {% endblock body %}
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
88
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
89 The ``base/base.html`` define some common blocks (check Jinja2_ documentation for the definitiion and instructions on how to use blocks). Those blocks are ``title``, ``favicon``, ``body``, ``footer``, ``main_menu``, ``confirm`` and ``category_menu``. For now, you can only take care of the first 4.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
90 The ``body`` block is, as you can guess, the main area of your page, the perfect place to say hello to the world.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
91
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
92 A first page
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
93 ------------
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
94 We have a template, but we need a page to use it.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
95 Pages are put in a directories hierarchy which correspond directly to your URL hierarchy, simple! To be used as a Libervia page, a directory must contain a file named ``page_meta.py``. So to create your first page, you just have to create the file ``pages/salut/page_meta.py`` and put this inside:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
96
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
97 .. sourcecode:: python
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
98
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
99 #!/usr/bin/env python2.7
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
100 #-*- coding: utf-8 -*-
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
101
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
102 template = "salut/salut.html"
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
103
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
104 And that's it! Note that we are still using Python 2.7, as the rest of Salut à Toi ecosystem. This will change for ``0.8`` release which will see the port of the whole project to Python 3.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
105
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
106 Now you certainly want to see your rendered page. For this you'll have to restart Libervia (automatic reloading is not yet available for pages, but it works for templates). In Libervia logs, you should see something like this::
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
107
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
108
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
109 [libervia.server.pages] [quickstart.int] Added /salut page
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
110
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
111 Now let's go to http://quickstart.int:8080/salut and admire your first Libervia page :).
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
112
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
113 But if you go to http://quickstart.int:8080 you still see this annoying ``No Such Resource``, would not it be nice to land directly to your salut page?
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
114 All you have to do for that, is to add a couple of lines in your ``sat.conf``, once again in ``[libervia]`` section:
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
115
1170
4648a333b33f doc: use "sourcecode" directive instead of "code" + small mistakes fixes:
Goffi <goffi@goffi.org>
parents: 1134
diff changeset
116 .. sourcecode:: javascript
1134
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
117
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
118 url_redirections_dict = {
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
119 "quick_start": {
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
120 "/": "/salut"
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
121 }
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
122 }
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
123
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
124 That means that the root of your ``quick_start`` site is redirected to your ``salut`` page. After restarting Libervia, you can check again http://quickstart.int:8080, you should see the welcoming message.
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
125
28789926852a doc: Libervia web framework quick_start + css_framework, first drafts
Goffi <goffi@goffi.org>
parents:
diff changeset
126 .. _Jinja2: http://jinja.pocoo.org/