Starting from CubicWeb version 4.0 all code related to generating html views has been moved to the Cube cubicweb_web.

If you want to migrate a project from 3.38 to 4.* while still using all the html views you need to both install the cubicweb_web cube AND add it to your dependencies and run add_cube('web').

cubicweb_web can be installed from pypi this way:

pip install cubicweb_web

We don’t plan to maintain the features in cubicweb_web in the long run; we are moving to a full javascript frontend using both cubicweb_api (which exposes a HTTP API) and @cubicweb/client as a frontend javascript toolkit.

In the long run cubicweb_api will be merged inside of CubicWeb.



Controllers are responsible for taking action upon user requests (loosely following the terminology of the MVC meta pattern).

The following controllers are provided out-of-the box in CubicWeb. We list them by category. They are all defined in (cubicweb_web.views.basecontrollers).


  • the View controller is associated with most browsing actions within a CubicWeb application: it always instantiates a TheMainTemplate and lets the ResultSet/Views dispatch system build up the whole content; it handles ObjectNotFound and NoSelectableObject errors that may bubble up to its entry point, in an end-user-friendly way (but other programming errors will slip through)

  • the JSonpController is a wrapper around the ViewController that provides jsonp services. Padding can be specified with the callback request parameter. Only jsonexport / ejsonexport views can be used. If another vid is specified, it will be ignored and replaced by jsonexport. Request is anonymized to avoid returning sensitive data and reduce the risks of CSRF attacks;

  • the Login/Logout controllers make effective user login or logout requests


  • the Edit controller (see The edit controller) handles CRUD operations in response to a form being submitted; it works in close association with the Forms, to which it delegates some of the work

  • the Form validator controller provides form validation from Ajax context, using the Edit controller, to implement the classic form handling loop (user edits, hits submit/apply, validation occurs server-side by way of the Form validator controller, and the UI is decorated with failure information, either global or per-field , until it is valid)


  • the SendMail controller (web/views/basecontrollers.py) is reponsible for outgoing email notifications

  • the MailBugReport controller (web/views/basecontrollers.py) allows to quickly have a reportbug feature in one’s application

  • the cubicweb_web.views.ajaxcontroller.AjaxController (cubicweb_web.views.ajaxcontroller) provides services for Ajax calls, typically using JSON as a serialization format for input, and sometimes using either JSON or XML for output. See Ajax chapter for more information.


All controllers (should) live in the ‘controllers’ namespace within the global registry.

Concrete controllers#

Most API details should be resolved by source code inspection, as the various controllers have differing goals. See for instance the The edit controller chapter.

cubicweb_web.controller contains the top-level abstract Controller class and its unimplemented entry point publish(rset=None) method.

A handful of helpers are also provided there:

  • process_rql builds a result set from an rql query typically issued from the browser (and available through _cw.form[‘rql’])

  • validate_cache will force cache validation handling with respect to the HTTP Cache directives (that were typically originally issued from a previous server -> client response); concrete Controller implementations dealing with HTTP (thus, for instance, not the SendMail controller) may very well call this in their publication process.