How to create your own forms and controllers?

Aim

Sometimes you need to associate to a given view your own specific form and the associated controller. We will see in this blog entry how it can be done in cubicweb on a concrete case.

The case

Let's suppose you're working on a social network project where you have to develop friend-of-a-frient (foaf) relationships between persons. For that purpose, we use the cubicweb-person cube and create in our scheme relations between persons like X in_contact_with Y:

class in_contact_with(RelationDefinition):
      subject = 'Person'
      object = 'Person'
      cardinality = '**'
      symmetric = True

We will also assume that a given Person corresponds to a unique CWUser through the relation is_user.

Although it is not evident, we would like that any connected person can chose to disconnect himself from another person at any time. For that, we will create a table view that will display the list of connected users, with a custom column giving the ability to "disconnect" with the person.

Before disconnecting with this particular person, we would like also to have a confirmation form.

How to proceed

The following steps were defined to address the above issue:

Define a "contact view" that will display the list of known contacts of the connected user ;
In this contact view, allow the user to click on a specific contact so as to remove him ;
Create a deletion confirmation view, that will contain:
- A form holding the buttons for deletion confirmation or cancel;
- A controller responsible for the actual deletion or the cancelling.

The contact view

Rendering a table view of connected persons

To display the list of connected persons to the current person, but also to add custom columns that do not refer specifically to attributes of a given entity, the best choice is to use EntityTableView (see here for more information):

class ContactView(EntityTableView):
    __regid__ = 'contacts_tableview'
    __select__ = is_instance('Person')
    columns = ['person', 'firstname', 'surname', 'email', 'phone', 'remove']
    layout_args = \{'display_filter': 'top', 'add_view_actions': None\}

    def cell_remove(w, entity):
        """link to the suppression of the relation between both contacts"""
        icon_url = entity._cw.data_url('img/user_delete.png')
        action_url = entity._cw.build_url(eid=entity.eid,
                vid='suppress_contact_view',
                __redirectpath=entity._cw.relative_path(),
                __redirectvid=entity._cw.form.get('__redirectvid', ''))
        w(u'&lt;a href="%(actionurl)s" title="%(title)s"&gt;'
                u'&lt;img alt="%(title)s" src="%(url)s" /&gt;&lt;/a&gt;'
                % \{'actionurl': xml_escape(action_url),
                   'title': _('remove from contacts'),
                   'url':icon_url\})

    column_renderers = \{
            'person': MainEntityColRenderer(),
            'email': RelatedEntityColRenderer(
                getrelated=lambda x:x.primary_email and x.primary_email[0] \
                        or None),
            'phone': RelatedEntityColRenderer(
                getrelated=lambda x:x.phone and x.phone[0] or None),
            'remove': EntityTableColRenderer(
                renderfunc=cell_remove,
                header=''),\}

A few explanations about the above view:

By default, the column attribute contains a list of displayable attributes of the entity. If one element of the list does not correspond to an attribute, which is the case for 'remove' here, it has to have rendering function defined in the dictionnary column_renderers.
However, when the column header refers to a related entity attribute, we can easily use the rendering function RelatedEntityColRenderer, as it is the case for the email and phone display.
As for concerns the 'remove' column, we render a clickable image in the cell_remove method. Here we have chosen an icon from famfamsilk that is putted in our data/ directory, but feel free to chose a predefined icon in the cubicweb shared data directory.

The redirection URL associated to each image has to be a link to a specific action allowing the user to remove the selected person from its contacts. It is built using the self._cw.build_url() convenience function. The redirection view, 'suppress_contact_view', will be defined later on. The eid argument passed refers to the id of the contact person the user wants to remove.

Calling the contact view

The above view has to be called with a given rset which corresponds to the list of known contacts for the connected user. In our case, we have defined a StartupView for the contact management, in which in the call function we have added the following piece of code:

person = self._cw.user.related('is_user', 'object').get_entity(0,0)
rset = self._cw.execute(
        'Any X WHERE X is Person, X in_contact_with Y, '
        'Y eid %(eid)s', \{'eid': person.eid\})
self.w(u'&lt;h3&gt;' + _('Number of contacts in my network:'))
self.w(unicode(len(rset)) + u'&lt;/h3&gt;')
if len(rset) != 0:
    self.wview('contacts_tableview', rset)

The Person corresponding to the connected user is retrieved thanks to the use of the related method and the is_user relation. The contact table view is displayed inside the parent StartupView.

Creation of the deletion confirmation view

Defining the confirmation view for contact deletion

The corresponding view is a simple View class instance, that will display a confirmation message and the related buttons. It could be defined as follows:

class SuppressContactView(View):
    __regid__ = 'suppress_contact_view'

    def cell_call(self, row, col):
        entity = self.cw_rset.get_entity(row, col)
        msg = self._cw._('Are you sure you want to remove %(name)s from your contacts?')
        self.w(u'&lt;p&gt;' + msg % \{'name': entity.dc_long_title()\} + u'&lt;/p&gt;')
        form = self._cw.vreg['forms'].select('suppress_contact_form',
                self._cw, rset=self.cw_rset)
        form.add_hidden(u'eidto', entity.eid)
        form.add_hidden(u'eidfrom', self._cw.user.related('is_user',
            'object').get_entity(0,0).eid)
        form.render(w=self.w)

Inside the cell_call() method of this view, we will have to render a form which aims at displaying both buttons (confirm deletion or cancel deletion). This form will be described later on.

The Person contact to remove is retrieved easily thanks to cw_rset. The Person corresponding to the connected user is here also retrieved thanks to the is_user relation. To make both of them available in the form, we add them at the instanciation of the form using the convenience function add_hidden(key,val).

Defining the deletion form

The deletion form as mentioned previously is only here to hold both buttons for the deletion confirmation or the cancelling. Both buttons are declared thanks to the form_buttons attribute of the form, which is instanciated from forms.FieldsForm:

class SuppressContactForm(forms.FieldsForm):
    __regid__ = 'suppress_contact_form'
    domid = 'delete_contact_form'
    form_renderer_id = 'base'

    @property
    def action(self):
        return self._cw.build_url('suppress_contact_controller')

    form_buttons = [
            fw.Button(stdmsgs.BUTTON_DELETE, cwaction='delete'),
            fw.Button(stdmsgs.BUTTON_CANCEL, cwaction='cancel')]

Specifying a given domid will ensure that your form will have a specific DOM identifier,the controller defined in the action method will be called without any ambiguity. The form_renderer_id is precised here so as to avoid additional display of informations which don't make sense here.

Defining the controller

The custom controller is instanciated from the Controller class in cubicweb.web.controller. The declaration of the controller should have the same domid than the calling form, as mentioned previously. The related actions are described in the publish() method of the controller:

class SuppressContactController(Controller):
    __regid__ = 'suppress_contact_controller'
    domid = 'delete_contact_form'

    def publish(self, rset=None):
        if '__action_cancel' in self._cw.form.keys():
            msg = self._cw._('Deletion canceled')
            raise Redirect(self._cw.build_url(
                vid='contact_management_view',
                __message=msg))
        elif '__action_delete' in self._cw.form.keys():
            xid = self._cw.form['eidfrom']
            dead_contact = self._cw.entity_from_eid(xid)
            yid = self._cw.form['eidto']
            self._cw.execute(
                    'DELETE X in_contact_with Y'
                    '  WHERE X eid %(xid)s, Y eid %(yid)s',
                    \{'xid': xid, 'yid': yid\})
            msg = self._cw._('%s removed from your contacts') %\
                dead_contact.dc_long_title()
            raise Redirect(self._cw.build_url(
                vid='contact_management_view',
                __message=msg))

Retrieving of the user action is performed by testing if the '_action<action>', where <action> refers to the cwaction in the button declaration, is present in the form keys. In the case of a cancelling, we simply redirect to the contact management view with a message specifying that the deletion has been cancelled. In the case of a deletion confirmation, both Person id's for the connected user and for the contact to remove are retrieved from the form hidden arguments.

The deletion is performed using an RQL request on the relation in_contact_with. We also redirect the view to the contact management view, this time with another message confirming the deletion of the contact link.