From b9a1879a7477bbb4a8cb6616fcefc4f44bd18904 Mon Sep 17 00:00:00 2001
From: Xavier Morel <xmo@openerp.com>
Date: Mon, 14 Apr 2014 14:57:12 +0200
Subject: [PATCH] [IMP] step through *working* instructions in the first
section
---
doc/howto/howto_website.rst | 89 +++++++++++++++----------
doc/howto/howto_website/basic-page | 2 +-
doc/howto/howto_website/ta-controller | 3 +-
doc/howto/howto_website/templates-basic | 4 +-
4 files changed, 59 insertions(+), 39 deletions(-)
diff --git a/doc/howto/howto_website.rst b/doc/howto/howto_website.rst
index f4c2c7f6f472..e6494bea1383 100644
--- a/doc/howto/howto_website.rst
+++ b/doc/howto/howto_website.rst
@@ -43,33 +43,62 @@ right next to your server's directory:
└── security
└── ir.model.access.csv
+* ``academy`` is the root directory of your module
+* ``__init__.py`` tells Python that it is a valid package, and imports
+ sub-packages and sub-modules
+* ``__openerp__.py`` provides various meta-information about your module to
+ OpenERP (a short description, the module's dependencies, its author, its
+ version, ...)
+* ``controllers`` holds the object responding to web (browser) requests
+ - ``academy.py`` is where a default controller has been created for you
+* ``models`` holds OpenERP stored objects, ignore it for now, we'll dive into
+ it when `storing data in OpenERP`
+* ``ir.model.access.csv`` defines basic access rights to the models, you can
+ also ignore it for now
+
.. patch::
:hidden:
-.. todo::
+Now we can create a database, start your OpenERP server and install your new
+module in it:
- * instructions for start & install
- * db handling
+.. code-block:: console
- - if existing db, automatically selected
- - if no existing db, nodb -> login -> login of first db
- - dbfilter
+ $ createdb academy
+ $ ./openerp-server --addons-path=../web/addons,../addons,../my-modules \
+ -d academy -i academy --db-filter=academy
-Now start your OpenERP server and install your module in it, open a web
-browser and navigate to http://localhost:8069. A page should appear with just
-the words "Hello, world!" on it.
+* ``--addons-path`` tells OpenERP where it can find its modules. By default it
+ will only look into ``openerp/addons``, this adds the web client modules,
+ the "standard" business modules (not needed yet) and the place where your
+ own ``academy`` module lives.
+* ``-i`` installs the provided module name in the database specified via
+ ``-d``
+* ``--db-filter`` means the specified database will be selected by default in
+ the web interface, and will be the only one selectable (makes starting
+ things up simpler)
-.. todo:: screenshot?
+Once the installation is finished you should see ``HTTP service (werkzeug)
+running on 0.0.0.0:8069`` and nothing more happening in the log. You can now
+open a web browser and navigate to http://localhost:8069. A page should
+appear with just the words "Hello, world!" on it:
-Let's prettify things a bit: instead of returning just a bit of text,
-we can return a page, and use a tool like bootstrap_ to get a
-nicer rendering than the default.
+.. image:: howto_website/helloworld.png
-Go to :file:`academy/controllers/academy.py` and change the string
-returned by the ``index`` method to get a more page-ish output:
+This page is generated by the ``index`` method in
+:file:`academy/controllers/academy.py`, which just returns some text. Let's
+make it prettier by returning HTML and using bootstrap_ to get a nicer default
+rendering:
.. patch::
+Restart the server, refresh the page
+
+.. image:: howto_website/hellobootstrap.png
+
+Although it is subtle for so little text and markup, the font has changed and
+margins have been added to the page.
+
.. note::
this example requires internet access as we're accessing a :abbr:`CDN
@@ -77,23 +106,13 @@ returned by the ``index`` method to get a more page-ish output:
and trying to provide high-performance and high-availability of these
files)`-hosted file.
-.. todo:: screenshot
-
Controller Parameters
=====================
-Being able to build a static page in code is nice, but makes for limited
-usefulness (you could do that with static files).
-
-You can also create dynamic pages which use data provided in the URL,
-for instance so a single controller generates multiple pages. Any
-query parameter (``?name=value``) is passed as a string parameter to the
-controller method.
-
-For instance, the index page can display a list of teaching assistants linking
-to a page for each assistant through their index in a global array. Each
-assistant's page will simply print their name by applying the index to the
-array:
+For dynamic pages, query parameters are passed as string parameters to the
+controller method. For instance the index page can display a list of teaching
+assistants, and link to each assistant's page using an index (in a global
+array for now):
.. patch::
@@ -103,15 +122,15 @@ formatted. For this reason, query parameters are generally used to provide
"options" to a given page, and "required" data tends (when possible) to be
inserted directly in the URL.
-This can be done by adding `converter patterns`_ to the URL in
-``@http.route``:
+This we can do by adding `converter patterns`_ to the URL in ``@http.route``:
.. patch::
-These patterns can perform conversions directly (in this case the conversion
-from a string URL section to a python integer) and will perform a some
-validation (if the ``id`` is not a valid integer, the converter will return a
-``404 Not Found`` instead of a 500 server error when the conversion fails).
+These patterns will generally do some validation (e.g. if the ``id`` is not
+a valid integer the converter will result in a ``404 Not Found`` page instead
+of a 500 server error when the conversion failed in our own code) and may
+perform some parsing or type conversion (in this case the conversion from a
+URL section — a string — to a Python integer).
Basic templates
===============
diff --git a/doc/howto/howto_website/basic-page b/doc/howto/howto_website/basic-page
index 5e053dcdea21..d3179145542c 100644
--- a/doc/howto/howto_website/basic-page
+++ b/doc/howto/howto_website/basic-page
@@ -12,6 +12,6 @@ diff --git a/controllers/academy.py b/controllers/academy.py
+ return """<!doctype html>
+<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
+<body class="container">
-+ <h1>Introduction to a thing</h1>
++ Hello, world!
+</body>
+"""
diff --git a/doc/howto/howto_website/ta-controller b/doc/howto/howto_website/ta-controller
index e3fef6d3486a..64de1dae17b1 100644
--- a/doc/howto/howto_website/ta-controller
+++ b/doc/howto/howto_website/ta-controller
@@ -27,7 +27,8 @@ diff --git a/controllers/academy.py b/controllers/academy.py
return """<!doctype html>
<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
<body class="container">
- <h1>Introduction to a thing</h1>
+- Hello, world!
++ <h1>Introduction to something</h1>
+ <h2>Teaching Assistants</h2>
+ <ul>
+ %(tas)s
diff --git a/doc/howto/howto_website/templates-basic b/doc/howto/howto_website/templates-basic
index b857b214f945..2fb934bdbb0e 100644
--- a/doc/howto/howto_website/templates-basic
+++ b/doc/howto/howto_website/templates-basic
@@ -1,5 +1,5 @@
# HG changeset patch
-# Parent 93586905ed9663bf48ef33ca6476a537a8f96ac8
+# Parent c6916a09fd20a67c210369676c78f23704870c8e
diff --git a/__openerp__.py b/__openerp__.py
--- a/__openerp__.py
@@ -32,7 +32,7 @@ diff --git a/controllers/academy.py b/controllers/academy.py
- return """<!doctype html>
-<link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet">
-<body class="container">
-- <h1>Introduction to a thing</h1>
+- <h1>Introduction to something</h1>
- <h2>Teaching Assistants</h2>
- <ul>
- %(tas)s
--
GitLab