odoo
/
odoo
2
0
Fork 0
Code Pull Requests Releases Activity

[IMP] source formatting: fill-paragraph to 78 

leaves a bit of room for diff mark & a small gutter in a 80c system
This commit is contained in:
Xavier Morel 2014-01-30 10:53:41 +01:00
parent b2a7516522
commit 80f03b2604
1 changed files with 183 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

380
doc/howto/howto_website.rst
View File

@ -9,18 +9,18 @@ Howto: build a website with OpenERP
This guide assumes `basic knowledge of python This guide assumes `basic knowledge of python
<http://docs.python.org/2/tutorial/>`_. <http://docs.python.org/2/tutorial/>`_.
This guide assumes :ref:`an OpenERP installed and ready for This guide assumes :ref:`an OpenERP installed and ready for development
development <getting_started_installation_source-link>`. <getting_started_installation_source-link>`.
For production deployment, see the dedicated guides For production deployment, see the dedicated guides :ref:`using-gunicorn`
:ref:`using-gunicorn` and :ref:`using-mod-wsgi`. and :ref:`using-mod-wsgi`.
Hello, world! Hello, world!
============= =============
In OpenERP, doing things takes the form of creating modules, and these In OpenERP, doing things takes the form of creating modules, and these modules
modules customize the behavior of the OpenERP installation. The first customize the behavior of the OpenERP installation. The first step is thus to
step is thus to create a module: create a module:
.. todo:: code generator in oe? .. todo:: code generator in oe?
@ -29,15 +29,15 @@ step is thus to create a module:
* Create model (concrete/abstract? Inherit?) * Create model (concrete/abstract? Inherit?)
* Add field? * Add field?
* Create a new folder called :file:`academy` in a module directory, * Create a new folder called :file:`academy` in a module directory, inside it
inside it create an empty file called :file:`__openerp__.py` with create an empty file called :file:`__openerp__.py` with the following
the following content: content:
.. patch:: .. patch::
* Create a second file :file:`controllers.py`. This is where the code * Create a second file :file:`controllers.py`. This is where the code
interacting directly with your web browser will live. For starters, interacting directly with your web browser will live. For starters, just
just include the following in it: include the following in it:
.. patch:: .. patch::
@ -45,8 +45,8 @@ step is thus to create a module:
.. patch:: .. patch::
This makes :file:`controllers.py` "visible" to openerp (by running This makes :file:`controllers.py` "visible" to openerp (by running the code
the code it holds). it holds).
.. todo:: .. todo::
@ -56,15 +56,15 @@ step is thus to create a module:
- if no existing db, nodb -> login -> login of first db - if no existing db, nodb -> login -> login of first db
- dbfilter - dbfilter
Now start your OpenERP server and install your module in it, open a Now start your OpenERP server and install your module in it, open a web
web browser and navigate to http://localhost:8069. A page should browser and navigate to http://localhost:8069. A page should appear with just
appear with just the words "Hello, world!" on it. the words "Hello, world!" on it.
The default response type is HTML (although we only sent some text, The default response type is HTML (although we only sent some text, browsers
browsers are pretty good at finding ways to turn stuff into things are pretty good at finding ways to turn stuff into things they can
they can display). Let's prettify things a bit: instead of returning display). Let's prettify things a bit: instead of returning just a bit of
just a bit of text, we can return a page, and use a tool/library like text, we can return a page, and use a tool/library like bootstrap_ to get a
bootstrap_ to get a nicer rendering than the default. nicer rendering than the default.
Change the string returned by the ``index`` method to get a more page-ish Change the string returned by the ``index`` method to get a more page-ish
output: output:
@ -73,17 +73,17 @@ output:
.. note:: .. note::
this example requires internet access at all time, as we're this example requires internet access at all time, as we're accessing a
accessing a :abbr:`CDN (Content Delivery Network, large distributed :abbr:`CDN (Content Delivery Network, large distributed networks hosting
networks hosting static files and trying to provide static files and trying to provide high-performance and high-availability
high-performance and high-availability of these files)`-hosted of these files)`-hosted file.
file.
Data input: URL and query Data input: URL and query
========================= =========================
Being able to build a static page in code is nice, but makes for limited Being able to build a static page in code is nice, but makes for limited
usefulness (you could do that with static files in the first place, after all). usefulness (you could do that with static files in the first place, after
all).
But you can also create controllers which use data provided in the access URL, But you can also create controllers which use data provided in the access URL,
for instance so you have a single controller generating multiple pages. Any for instance so you have a single controller generating multiple pages. Any
@ -98,14 +98,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 "options" to a given page, and "required" data tends (when possible) to be
inserted directly in the URL. inserted directly in the URL.
This can be done by adding `converter patterns`_ to the URL in ``@http.route``: This can be done by adding `converter patterns`_ to the URL in
``@http.route``:
.. patch:: .. patch::
These patterns can perform conversions directly (in this case the conversion 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 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 validation (if the ``id`` is not a valid integer, the converter will return a
a ``404 Not Found`` instead of generating a server error when the conversion ``404 Not Found`` instead of generating a server error when the conversion
fails). fails).
Templating: better experience in editing Templating: better experience in editing
@ -116,171 +117,164 @@ string concatenation and formatting. It works, but is not exactly fun to edit
(and somewhat unsafe to boot) as even advanced text editors have a hard time (and somewhat unsafe to boot) as even advanced text editors have a hard time
understanding they're dealing with HTML embedded in Python code. understanding they're dealing with HTML embedded in Python code.
The usual solution is to use templates_, documents with placeholders which The usual solution is to use templates_, documents with placeholders which can
can be "rendered" to produce final pages (or others). OpenERP lets you use be "rendered" to produce final pages (or others). OpenERP lets you use any
any Python templating system you want, but bundles its own Python templating system you want, but bundles its own :doc:`QWeb
:doc:`QWeb </06_ir_qweb>` templating system which we'll later see offers </06_ir_qweb>` templating system which we'll later see offers some useful
some useful features. features.
Let's move our 2 pseudo-templates from inline strings to actual templates: Let's move our 2 pseudo-templates from inline strings to actual templates:
.. patch:: .. patch::
.. todo:: how can I access a QWeb template from a auth=none .. todo:: how can I access a QWeb template from a auth=none controller?
controller? explicitly fetch a registry using explicitly fetch a registry using request.session.db? That's a bit
request.session.db? That's a bit horrendous now innit? horrendous now innit?
This simplifies the controller code by moving data formatting out of This simplifies the controller code by moving data formatting out of it, and
it, and generally makes it simpler for designers to edit the markup. generally makes it simpler for designers to edit the markup.
.. todo:: link to section about reusing/altering existing stuff, .. todo:: link to section about reusing/altering existing stuff, template
template overriding overriding
OpenERP's Website support OpenERP's Website support
========================= =========================
OpenERP 8 is bundled with new modules dedicated specifically to OpenERP 8 is bundled with new modules dedicated specifically to building
building websites (whether it be simply sets of pages or more complex websites (whether it be simply sets of pages or more complex components such
components such as blogs). as blogs).
First, we'll install the ``website`` module: ``oe install website``. First, we'll install the ``website`` module: ``oe install website``.
.. todo:: is it possible that the page has *not* been replaced? .. todo:: is it possible that the page has *not* been replaced?
If you navigate to `your openerp`_, your basic page has now been If you navigate to `your openerp`_, your basic page has now been replaced by
replaced by the generic empty index page. Because you are not the generic empty index page. Because you are not logged-in yet, the page has
logged-in yet, the page has no content and just basic placeholders in no content and just basic placeholders in the header and footer. Click on the
the header and footer. Click on the :guilabel:`Sign In` link, fill in :guilabel:`Sign In` link, fill in your credentials (``admin``/``admin`` by
your credentials (``admin``/``admin`` by default), click default), click :guilabel:`Log in`.
:guilabel:`Log in`.
You're now in OpenERP "proper", the backend/administrative You're now in OpenERP "proper", the backend/administrative interface. We'll
interface. We'll deal with it in :ref:`a latter section deal with it in :ref:`a latter section <howto-website-administration>`, for
<howto-website-administration>`, for how click on the how click on the :menuselection:`Website` menu item, in the top-left of the
:menuselection:`Website` menu item, in the top-left of the browser browser between :menuselection:`Messaging` and :menuselection:`Settings`.
between :menuselection:`Messaging` and :menuselection:`Settings`.
You're back to your website, but are now an administrator and thus You're back to your website, but are now an administrator and thus have access
have access to the advanced edition features of an OpenERP-build to the advanced edition features of an OpenERP-build website. Let's quickly
website. Let's quickly run through them. run through them.
Mobile Preview Mobile Preview
-------------- --------------
.. todo:: insert menu bar, mobile preview icon outlined .. todo:: insert menu bar, mobile preview icon outlined
Because the OpenERP website system is built with bootstrap_, it is Because the OpenERP website system is built with bootstrap_, it is easy to
easy to build "responsive" websites reacting to the size of the screen build "responsive" websites reacting to the size of the screen and making best
and making best use of the available space. use of the available space.
The mobile preview does not give you the exact rendering of a The mobile preview does not give you the exact rendering of a smartphone (if
smartphone (if there's such a thing), but it goes some of the way and there's such a thing), but it goes some of the way and lets you know if it's
lets you know if it's completely unusable without having to actually completely unusable without having to actually switch to a smartphone and try
switch to a smartphone and try to find out how to see your site with to find out how to see your site with it (especially during edition).
it (especially during edition).
.. todo:: screenshot of page in desktop v mobile preview layout .. todo:: screenshot of page in desktop v mobile preview layout
Promote Promote
------- -------
Lets you easily configure how your page should advertise its existence Lets you easily configure how your page should advertise its existence to
to search engines: keywords matching the page's subject, nice titles search engines: keywords matching the page's subject, nice titles and
and descriptions for visitors finding the page via search engines. descriptions for visitors finding the page via search engines.
.. todo:: screenshot promote .. todo:: screenshot promote
Content Content
------- -------
The content menu provides "top level" operations: manipulation of the The content menu provides "top level" operations: manipulation of the main
main menu (creation of new links, submenus, etc...) and creation of menu (creation of new links, submenus, etc...) and creation of high-level
high-level objects. At the moment only pages (they're the top-level objects. At the moment only pages (they're the top-level object for the
object for the ``website`` module), but installing the recruitment ``website`` module), but installing the recruitment module will add an entry
module will add an entry to quick-create a new job offer, and the to quick-create a new job offer, and the events module one for a new event.
events module one for a new event.
Customize Customize
--------- ---------
The customize menu provides a number of loosely associated features, The customize menu provides a number of loosely associated features, broadly
broadly split in two sections: split in two sections:
Templates configuration Templates configuration
``````````````````````` ```````````````````````
Some templates provide alternative versions/structures. These Some templates provide alternative versions/structures. These alternative
alternative version can be toggled from the template configuration version can be toggled from the template configuration checkboxes. Two of
checkboxes. Two of these are bundled in ``website``, providing an these are bundled in ``website``, providing an alternative blank footer to
alternative blank footer to fill, and the other one replacing your fill, and the other one replacing your company's name by your company's logo
company's name by your company's logo in the navigation bar. in the navigation bar.
Theming Theming
``````` ```````
As previously mentioned, OpenERP's website module uses bootstrap_ for As previously mentioned, OpenERP's website module uses bootstrap_ for much of
much of its basic styles and layout. This, in turns, allows using its basic styles and layout. This, in turns, allows using existing bootstrap
existing bootstrap themes to alter the color scheme of your website. themes to alter the color scheme of your website.
:menuselection:`Customize --> Change Theme` opens a picker to a few :menuselection:`Customize --> Change Theme` opens a picker to a few bundled
bundled Bootstrap themes, and lets you change the look of your site Bootstrap themes, and lets you change the look of your site quickly and
quickly and on-the-fly. on-the-fly.
.. todo:: creating or installing new boostrap themes? .. todo:: creating or installing new boostrap themes?
HTML Editor HTML Editor
``````````` ```````````
Opens a full-blown code editor on the current template, and lets you Opens a full-blown code editor on the current template, and lets you easily
easily edit templates in-place, either for a quick fix which is edit templates in-place, either for a quick fix which is simpler to perform in
simpler to perform in code yet from the page, or to try things out code yet from the page, or to try things out before moving them to template
before moving them to template files. files.
Help Help
---- ----
Lists available tutorials, step-by-step lessons in using the website. Lists available tutorials, step-by-step lessons in using the website.
``website`` only provides :menuselection:`Help --> Insert a banner` ``website`` only provides :menuselection:`Help --> Insert a banner` which
which shows some basic features of the website (snippets, edition, shows some basic features of the website (snippets, edition, mobile preview)
mobile preview) while guiding the user through. Other modules can while guiding the user through. Other modules can provide additional tutorials
provide additional tutorials for their advanced features. for their advanced features.
Edit Edit
---- ----
Starts up the rich text editor, which lets you alter page text, add Starts up the rich text editor, which lets you alter page text, add links and
links and images, change colors, etc… images, change colors, etc…
Snippets Snippets
```````` ````````
:guilabel:`Insert Blocks` opens the snippets UI: pre-built layout :guilabel:`Insert Blocks` opens the snippets UI: pre-built layout blocks which
blocks which you can then fill with your own content (text, pictures, you can then fill with your own content (text, pictures, …). Simply select a
…). Simply select a snippet and drag-and-drop it on your page. Guides snippet and drag-and-drop it on your page. Guides should appear when you start
should appear when you start dragging a snippet, showing where the dragging a snippet, showing where the snippet can be dropped.
snippet can be dropped.
Building your pages with OpenERP Website Building your pages with OpenERP Website
======================================== ========================================
As we've seen, your index page has "disappeared" and been replaced by As we've seen, your index page has "disappeared" and been replaced by the one
the one provided by ``website``. The page is not lost, but because provided by ``website``. The page is not lost, but because ``website`` was
``website`` was installed after the ``academy`` module, its index installed after the ``academy`` module, its index page takes over routing (two
page takes over routing (two index pages exist, and one is picked index pages exist, and one is picked over the other).
over the other).
To fix the issue, we can simply add ``website`` as a dependency to To fix the issue, we can simply add ``website`` as a dependency to ``academy``
``academy`` (that is, tell OpenERP that ``academy`` needs ``website`` (that is, tell OpenERP that ``academy`` needs ``website`` to work right):
to work right):
.. needs -u all to update metadata .. needs -u all to update metadata
.. patch:: .. patch::
.. todo:: website dispatch overrides blows up on auth=none (implicitly .. todo:: website dispatch overrides blows up on auth=none (implicitly
inherits website's index -> ``website_enabled`` -> tries to inherits website's index -> ``website_enabled`` -> tries to access
access ``request.registry['website']`` even though ``request.registry['website']`` even though ``request.registry is
``request.registry is None`` because ``auth='none'``) None`` because ``auth='none'``)
also template issues (see above) (enabled website to "fix") also template issues (see above) (enabled website to "fix")
@ -288,139 +282,132 @@ This will cause ``academy``'s index page to overwrite ``website``'s.
Reload `your openerp`_. Your old index page is back. Reload `your openerp`_. Your old index page is back.
However, none of the website edition tools are available. That is However, none of the website edition tools are available. That is because much
because much of these tools are inserted and enabled by the website of these tools are inserted and enabled by the website layout template. Let's
layout template. Let's use that layout instead of our own page use that layout instead of our own page structure:
structure:
.. patch:: .. patch::
* ``website.layout`` is the main Website layout, it provides standard * ``website.layout`` is the main Website layout, it provides standard headers
headers and footers as well as integration with various and footers as well as integration with various customization tools.
customization tools.
* there's quite a bit of complex markup, used as hooks for various * there's quite a bit of complex markup, used as hooks for various features
features (e.g. snippets). Although technically not mandatory, some (e.g. snippets). Although technically not mandatory, some things will not
things will not work if they're not there. work if they're not there.
* if you go in the HTML editor (:menuselection:`Customize --> HTML * if you go in the HTML editor (:menuselection:`Customize --> HTML Editor`),
Editor`), you can see and edit your template you can see and edit your template
.. todo:: website template generator .. todo:: website template generator
If you try to add content to the TA pages using snippets, for instance If you try to add content to the TA pages using snippets, for instance insert
insert an :guilabel:`image-text` snippet to add a picture and a short an :guilabel:`image-text` snippet to add a picture and a short biography for a
biography for a TA, you'll notice things don't work right: because TA, you'll notice things don't work right: because snippets are added in the
snippets are added in the template itself, they're content which is template itself, they're content which is the same across all pages using that
the same across all pages using that template. template.
Thus snippets are mostly for generic content, when a given template is Thus snippets are mostly for generic content, when a given template is only
only used for a single page, or to add content in HTML fields. used for a single page, or to add content in HTML fields.
.. note:: .. note::
When creating a new page (e.g. via :menuselection:`Content --> New When creating a new page (e.g. via :menuselection:`Content --> New Page`),
Page`), OpenERP will duplicate a "source" template, and create a OpenERP will duplicate a "source" template, and create a new template for
new template for each page. As a result, it's safe to use each page. As a result, it's safe to use dedicated-content snippets for
dedicated-content snippets for "static" pages. "static" pages.
Time, then, to create more specific content. Time, then, to create more specific content.
Storing data in OpenERP Storing data in OpenERP
======================= =======================
The conceptual storage model of OpenERP is simple: there are storage The conceptual storage model of OpenERP is simple: there are storage tables,
tables, represented by OpenERP models, and inside these tables are represented by OpenERP models, and inside these tables are records. The first
records. The first step, then, is to define a model. step, then, is to define a model.
We'll start by moving our teaching assistants in the database: We'll start by moving our teaching assistants in the database:
.. patch:: .. patch::
We've also altered the index method slightly, to retrieve our teaching We've also altered the index method slightly, to retrieve our teaching
assistants from the database instead of storing them in a global list assistants from the database instead of storing them in a global list in the
in the module\ [#taprofile]_. module\ [#taprofile]_.
.. note:: :file:`ir.model.access.csv` is necessary to tell OpenERP .. note:: :file:`ir.model.access.csv` is necessary to tell OpenERP that any
that any user can *see* the teaching assistants: by default, user can *see* the teaching assistants: by default, only the
only the administrator can see, edit, create or destroy administrator can see, edit, create or destroy objects. Here, we
objects. Here, we only change the ``read`` permission to only change the ``read`` permission to allow any user to list and
allow any user to list and browse teaching assistants. browse teaching assistants.
.. todo:: command/shortcut .. todo:: command/shortcut
Update the module, reload `your openerp`_… and the Teaching Assistants Update the module, reload `your openerp`_… and the Teaching Assistants list is
list is empty since we haven't put any TA in the database. empty since we haven't put any TA in the database.
Let's add them in data files: Let's add them in data files:
.. patch:: .. patch::
Update the module again, reload `your openerp`_ and the TAs are Update the module again, reload `your openerp`_ and the TAs are back. Click on
back. Click on a TA name, and you'll see an error message. Let's fix a TA name, and you'll see an error message. Let's fix the TA view now:
the TA view now:
.. todo:: if ta template was modified in previous section, it's marked .. todo:: if ta template was modified in previous section, it's marked
noupdate and updating the module will have no effect for no noupdate and updating the module will have no effect for no known
known reason. That's really quite annoying. reason. That's really quite annoying.
.. patch:: .. patch::
There are a few non-obvious things here, so let's go through them for There are a few non-obvious things here, so let's go through them for clarity:
clarity:
* OpenERP provides a has a special `converter pattern`_, which knows * OpenERP provides a has a special `converter pattern`_, which knows how to
how to retrieve OpenERP objects by identifier. Instead of an integer retrieve OpenERP objects by identifier. Instead of an integer or other
or other similar basic value, ``ta`` thus gets a full-blown similar basic value, ``ta`` thus gets a full-blown ``academy.tas`` object,
``academy.tas`` object, without having to retrieve it by hand (as is without having to retrieve it by hand (as is done in ``index``).
done in ``index``).
* However because the ``model()`` `converter pattern`_ takes an * However because the ``model()`` `converter pattern`_ takes an identifier, we
identifier, we have to alter the creation of ``ta``'s URL to include have to alter the creation of ``ta``'s URL to include such an identifier,
such an identifier, rather than an index in an array rather than an index in an array
* Finally, ``website.render()`` wants a dict as its rendering context, * Finally, ``website.render()`` wants a dict as its rendering context, not an
not an object, which is why we wrap our ``ta`` object into one. object, which is why we wrap our ``ta`` object into one.
We're still where we started this section though: if we add snippets We're still where we started this section though: if we add snippets to or
to or edit the text of a TA's page, these editions will be visible edit the text of a TA's page, these editions will be visible across all TA
across all TA pages since they'll be stored in the shared pages since they'll be stored in the shared ``academy.ta`` template.
``academy.ta`` template.
Not only that, but we can not even edit the TA's name, even though Not only that, but we can not even edit the TA's name, even though it's not
it's not shared content. shared content.
Let's fix that first, instead of using the basic "display this Let's fix that first, instead of using the basic "display this content"
content" template tag ``t-esc``, we'll use one aware of OpenERP template tag ``t-esc``, we'll use one aware of OpenERP objects and their
objects and their fields: fields:
.. patch:: .. patch::
Update the module, go into a TA page and activate the edition mode. If Update the module, go into a TA page and activate the edition mode. If you
you move your mouse over the TA's name, it is surrounded by a yellow move your mouse over the TA's name, it is surrounded by a yellow border, and
border, and you can edit its content. If you change the name of a TA you can edit its content. If you change the name of a TA and save the page,
and save the page, the change is correctly stored in the TA's record, the change is correctly stored in the TA's record, the name is fixed when you
the name is fixed when you go to the index page but other TAs remain go to the index page but other TAs remain unaffected.
unaffected.
For the issue of customizing our TA profiles, we can expand our model For the issue of customizing our TA profiles, we can expand our model with a
with a "freeform" HTML field: "freeform" HTML field:
.. patch:: .. patch::
Then, insert the new biographical content in the template using the Then, insert the new biographical content in the template using the same
same object-aware template tag: object-aware template tag:
.. patch:: .. patch::
.. todo:: updating the ``name`` field from the RTE altered the .. todo:: updating the ``name`` field from the RTE altered the template, which
template, which locked it... locked it...
Update the module, browse to a TA's page and open the edition mode Update the module, browse to a TA's page and open the edition mode (using the
(using the :guilabel:`Edit` button in the window's top-right). The :guilabel:`Edit` button in the window's top-right). The empty HTML field now
empty HTML field now displays a big placeholder image, if you drop displays a big placeholder image, if you drop snippets in or write some
snippets in or write some content for one of the teaching assistants, content for one of the teaching assistants, you will see that other TA
you will see that other TA profiles are unaffected. profiles are unaffected.
A more complex model A more complex model
-------------------- --------------------
@ -450,9 +437,8 @@ Administration and ERP Integration
.. improve generated views .. improve generated views
.. create list & form views for events .. create list & form views for events
.. [#taprofile] the teaching assistants profile view ends up .. [#taprofile] the teaching assistants profile view ends up broken for now,
broken for now, but don't worry we'll get but don't worry we'll get around to it
around to it
.. _bootstrap: http://getbootstrap.com .. _bootstrap: http://getbootstrap.com