167 lines
5.2 KiB
ReStructuredText
167 lines
5.2 KiB
ReStructuredText
|
|
Web Controllers
|
|
===============
|
|
|
|
Web controllers are classes in OpenERP able to catch the http requests sent by any browser. They allow to generate
|
|
html pages to be served like any web server, implement new methods to be used by the Javascript client, etc...
|
|
|
|
Controllers File
|
|
----------------
|
|
|
|
By convention the controllers should be placed in the controllers directory of the module. Example:
|
|
|
|
.. code-block:: text
|
|
|
|
web_example
|
|
├── controllers
|
|
│ ├── __init__.py
|
|
│ └── my_controllers.py
|
|
├── __init__.py
|
|
└── __openerp__.py
|
|
|
|
In ``__init__.py`` you must add:
|
|
|
|
::
|
|
|
|
import controllers
|
|
|
|
And here is the content of ``controllers/__init__.py``:
|
|
|
|
::
|
|
|
|
import my_controllers
|
|
|
|
Now you can put the following content in ``controllers/my_controllers.py``:
|
|
|
|
::
|
|
|
|
import openerp.addons.web.http as http
|
|
from openerp.addons.web.http import request
|
|
|
|
|
|
Controller Declaration
|
|
----------------------
|
|
|
|
In your controllers file, you can now declare a controller this way:
|
|
|
|
::
|
|
|
|
class MyController(http.Controller):
|
|
|
|
@http.route('/my_url/some_html', type="http")
|
|
def some_html(self):
|
|
return "<h1>This is a test</h1>"
|
|
|
|
@http.route('/my_url/some_json', type="json")
|
|
def some_json(self):
|
|
return {"sample_dictionary": "This is a sample JSON dictionary"}
|
|
|
|
A controller must inherit from ``http.Controller``. Each time you define a method with ``@http.route()`` it defines a
|
|
url to match. As example, the ``some_html()`` method will be called a client query the ``/my_url/some_html`` url.
|
|
|
|
Pure HTTP Requests
|
|
------------------
|
|
|
|
You can define methods to get any normal http requests by passing ``'http'`` to the ``type`` argument of
|
|
``http.route()``. When doing so, you get the HTTP parameters as named parameters of the method:
|
|
|
|
::
|
|
|
|
@http.route('/say_hello', type="http")
|
|
def say_hello(self, name):
|
|
return "<h1>Hello %s</h1>" % name
|
|
|
|
This url could be contacted by typing this url in a browser: ``http://localhost:8069/say_hello?name=Nicolas``.
|
|
|
|
JSON Requests
|
|
-------------
|
|
|
|
Methods that received JSON can be defined by passing ``'json'`` to the ``type`` argument of ``http.route()``. The
|
|
OpenERP Javascript client can contact these methods using the JSON-RPC protocol. JSON methods must return JSON. Like the
|
|
HTTP methods they receive arguments as named parameters (except these arguments are JSON-RPC parameters).
|
|
|
|
::
|
|
|
|
@http.route('/division', type="json")
|
|
def division(self, i, j):
|
|
return i / j # returns a number
|
|
|
|
URL Patterns
|
|
------------
|
|
|
|
Any URL passed to ``http.route()`` can contain patterns. Example:
|
|
|
|
::
|
|
|
|
@http.route('/files/<path:file_path>', type="http")
|
|
def files(self, file_path):
|
|
... # return a file identified by the path store in the 'my_path' variable
|
|
|
|
When such patterns are used, the method will received additional parameters that correspond to the parameters defined in
|
|
the url. For exact documentation about url patterns, see Werkzeug's documentation:
|
|
http://werkzeug.pocoo.org/docs/routing/ .
|
|
|
|
Also note you can pass multiple urls to ``http.route()``:
|
|
|
|
|
|
::
|
|
|
|
@http.route(['/files/<path:file_path>', '/other_url/<path:file_path>'], type="http")
|
|
def files(self, file_path):
|
|
...
|
|
|
|
Contacting Models
|
|
-----------------
|
|
|
|
To use the database you must access the OpenERP models. The global ``request`` object provides the necessary objects:
|
|
|
|
::
|
|
|
|
@http.route('/my_name', type="http")
|
|
def my_name(self):
|
|
my_user_record = request.registry.get("res.users").browse(request.cr, request.uid, request.uid)
|
|
return "<h1>Your name is %s</h1>" % my_user_record.name
|
|
|
|
``request.registry`` is the registry that gives you access to the models. It is the equivalent of ``self.pool`` when
|
|
working inside OpenERP models.
|
|
|
|
``request.cr`` is the cursor object. This is the ``cr`` parameter you have to pass as first argument of every model
|
|
method in OpenERP.
|
|
|
|
``request.uid`` is the id of the current logged in user. This is the ``uid`` parameter you have to pass as second
|
|
argument of every model method in OpenERP.
|
|
|
|
Authorization Levels
|
|
--------------------
|
|
|
|
By default, all methods can only be used by users logged into OpenERP (OpenERP uses cookies to track logged users).
|
|
There are some cases when you need to enable not-logged in users to access some methods. To do so, add the ``'db'``
|
|
value to the ``auth`` parameter of ``http.route()``:
|
|
|
|
::
|
|
|
|
@http.route('/hello', type="http", auth="db")
|
|
def hello(self):
|
|
return "<div>Hello unknown user!</div>"
|
|
|
|
Please note the ``request.uid`` user id will be ``None`` inside this method call. This is due to the fact no user was
|
|
authenticated.
|
|
|
|
Overriding Controllers
|
|
----------------------
|
|
|
|
Existing routes can be overridden. To do so, create a controller that inherit the controller containing the route you
|
|
want to override. Example that redefine the home page of your OpenERP application.
|
|
|
|
::
|
|
|
|
import openerp.addons.web.controllers.main as main
|
|
|
|
class Home2(main.Home):
|
|
@http.route('/', type="http", auth="db")
|
|
def index(self):
|
|
return "<div>This is my new home page.</div>"
|
|
|
|
By re-defining the ``index()`` method, you change the behavior of the original ``Home`` class. Now the ``'/'`` route
|
|
will match the new ``index()`` method in ``Home2``.
|