From b9a1879a7477bbb4a8cb6616fcefc4f44bd18904 Mon Sep 17 00:00:00 2001 From: Xavier Morel 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 f4c2c7f6f47..e6494bea138 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 5e053dcdea2..d3179145542 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 """ + + -+

Introduction to a thing

++ Hello, world! + +""" diff --git a/doc/howto/howto_website/ta-controller b/doc/howto/howto_website/ta-controller index e3fef6d3486..64de1dae17b 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 """ -

Introduction to a thing

+- Hello, world! ++

Introduction to something

+

Teaching Assistants

+