Building your URLs in cubicweb

Aim

In cubicweb, you often have to build url's that redirect the current view to a specific entity view or allow the execution of a given action. Moreover, you often want also to fallback to the previous view once the specific action or edition is done, or redirect also to another entity's specific view.

To do so, cubicweb provides you with a set of powerful tools, however as there is often more than one way to do it, this blog entry is here to help you in choosing the preferred way.

Tools at your disposal

The universal URL builder: `build_url()`

build_url is accessible in any context, so for instance in the rendering of a given entity view you can call self._cw.build_url to build you URLs easily, which is the most common case. In class methods (for instance, when declaring the rendering methods of an EntityTableView), you can access it through the context of instantiated appobject which are usually given as argument, e.g. entity._cw.build_url. For test purposes you can also call session.build_url in cubicweb shells.

build_url basically take a first optional, the path, relative to the base url of the site, and arbitrary named arguments that will be encoded as url parameters. Unless you wish to direct to a custom controller, or to match an URL rewrite url, you don't have to specify the path.

Extra parameters given to build_url will vary according to your needs, however most common arguments understood by default cubicweb views are the followings:

vid: the built view regid;
rql: the RQL query used to retreive data on which the view should be applied;
eid: the identifier of an entity, which you should use instead of rql when the view apply to a single entity (most often);
__message: an information message to display inside the view;
__linkto: in case of an entity creation url, will allow to set some specific relations between both entities;
__redirectpath: the URL of the entity of the redirection;
__redirectvid: the view id of the redirection.

__redirectvid and __redirectpath are used to control redirection after posting a form and are more detailed in the cubicweb documentation, chapter related to the edition control (http://docs.cubicweb.org/devweb/edition/editcontroller.html).

Exploring entities associated URLs

Generally, an entity has two important methods that retrieve its absolute or relative urls:

entity.rest_path() will return something like <type>/<eid> where <type> corresponds to the entity type and <eid> the entity eid;
entity.absolute_url() will return the full url of the entity http://<baseurl>/<type>/<eid>. In case you want to access a specific view of the entity, just pass the vid='myviewid' argument. You can give arbitrary arguments to this method that will be encoded as url parameters.

Getting a proper RQL

Passing the rql to the build_url method requires to have a proper RQL expression. To do so, there is a convenience method, printable_rql(), that is accessible in rset resulting from RQL queries. This allows to apply a view to the same result set as the one currently process, simply using rql = self.cw_rset.printable_rql().

Getting URLs from the current view

There are several ways to get URL of the current view, the canonical one being to use self._cw.relative_path(includeparams=True) which will return the path of the current view relative to the base url of the site (otherwise use self._cw.url(), including parameters or not according to value given as includeparams).

You can also retrieve values given to individual parameters using self._cw.form, eg:

self._cw.form.get('vid', '') will return only the view id;
self._cw.form.get('rql', '') will return only the RQL;
self._cw.form.get('__redirectvid', '') will return the redirection view if defined;
self._cw.form.get('__redirectpath', '') will return the redirection path if defined.

How to redirect to non-entity view?

This case often appears when you want to create a link to a startup view or a controller. It the first case, you simply build you URL like this:

self._cw.build_url('view', vid='my_view_id')

The latter case appears when you want to call a controller directly without having to define a form in your view. This can happen for instance when you want to create a URL that will set a relation between 2 objects and do not need any confirmation for that. The URL construction is done like this:

self._cw.build_url('my_controller_id', arg1=value1, arg2=value2, ...)

Any extra arguments passed to the build_url method will be available in the controller as key, values pairs of the self._cw.forms dictionary. This is especially useful when you want to define some kind of hidden attributes but there is not form to put them into.

And, last but not least, a convenient way to get the root URL of the instance:

self._cw.base_url()

How to link to a registered action?

There are other ways to create a link to registered actions than using build_url, mostly by accessing them via the registry vreg.

For instance, the action registry holds effectively all possible actions in a given context: a specific action can be selected using the select_or_none() method, or even using the possible_action() method which will return a list of categorized actions. The url of the action is then available as action.url(). For contextual components (e.g. boxes), you can even directly get a link to the selected action(s) using the self.action_link(this_action) method.

If the action corresponds to the creation of a new entity, there is an even faster and elegant way to do it, using the schema of your cube:

url = self._cw.vreg["etypes"].etype_class('MyEntity').cw_create_url(self._cw)

Some concrete cases

Get the URL of the outofcontext view of an entity:

link = entity.absolute_url(vid='outofcontext')

Create a link to a given controller then fall back to the current view:

In your entity view:

self.w(u'&lt;a href="%s"&gt;Click me&lt;/a&gt;' % xml_escape(
        self._cw.build_url('mycontrollerid',
                arg1=value1, arg2=value2,
                rql=self.cw_rset.printable_rql(),
                __redirectvid=self._cw.form.get('vid',''))))

In your controller:

def publish(self, rset):
     value1, value2 = self._cw.form['arg1'], self._cw.form['arg2']
     # do some stuff with value1 and value2 here...
     raise Redirect(self._cw.build_url(rql=self._cw.form['rql'],
         vid=self._cw.form['__redirectvid'],
         __message=_('you message')))

Create a link to add a given entity and relate this entity to the current one with a relation 'child_of', then go back to the current entity's view:

entity = self.cw_rset.get_entity(0,0)
self.w(u'&lt;a href="%s"&gt;Click me&lt;/a&gt;' % xml_escape(
        self._cw.build_url('add/Mychildentity',
                __linkto='child_of:%s:object' % entity.eid,
                __redirectpath=entity.rest_path(),
                __redirectvid=self._cw.form.get('vid', ''))))

Same example, but we suppose that we are in a multiple rset entity view, and we want to go back afterwards to this view:

entity = self.cw_rset.get_entity(0,0)
self.w(u'&lt;a href="%s"&gt;Click me&lt;/a&gt;' % xml_escape(
        self._cw.build_url('add/Mychildentity',
                rql=self.cw_rset.printable_rql(),
                __linkto='child_of:%s:object' % entity.eid,
                __redirectvid=self._cw.form.get('vid', ''))))

Create links to all 'menuactions' in a view:

actions = self._cw.vreg['actions'].possible_actions(self._cw, rset=self.cw_rset)
action_links = [unicode(self.action_link(x)) for x in actions.get('menuactions', ())]
self.w( u'  |  '.join(action_links))