Examples
--------

(Automatic) Entity form
~~~~~~~~~~~~~~~~~~~~~~~

Looking at some cubes available on the `cubicweb forge`_ we find some
with form manipulation. The following example comes from the the
`conference`_ cube. It extends the change state form for the case
where a ``Talk`` entity is getting into ``submitted`` state. The goal
is to select reviewers for the submitted talk.

.. _`cubicweb forge`: http://www.cubicweb.org/view?rql=Any+P+ORDERBY+N+WHERE+P+name+LIKE+%22cubicweb-%25%22%2C+P+is+Project%2C+P+name+N
.. _`conference`: http://www.cubicweb.org/project/cubicweb-conference

.. sourcecode:: python

 from cubicweb.web import formfields as ff, formwidgets as fwdgs
 class SendToReviewerStatusChangeView(ChangeStateFormView):
     __select__ = (ChangeStateFormView.__select__ &
                   is_instance('Talk') &
                   rql_condition('X in_state S, S name "submitted"'))

     def get_form(self, entity, transition, **kwargs):
         form = super(SendToReviewerStatusChangeView, self).get_form(entity, transition, **kwargs)
         relation = ff.RelationField(name='reviews', role='object',
                                     eidparam=True,
                                     label=_('select reviewers'),
                                     widget=fwdgs.Select(multiple=True))
         form.append_field(relation)
         return form

Simple extension of a form can be done from within the `FormView`
wrapping the form. FormView instances have a handy ``get_form`` method
that returns the form to be rendered. Here we add a ``RelationField``
to the base state change form.

One notable point is the ``eidparam`` argument: it tells both the
field and the ``edit controller`` that the field is linked to a
specific entity.

It is hence entirely possible to add ad-hoc fields that will be
processed by some specialized instance of the edit controller.


Ad-hoc fields form
~~~~~~~~~~~~~~~~~~

We want to define a form doing something else than editing an entity. The idea is
to propose a form to send an email to entities in a resultset which implements
:class:`IEmailable`.  Let's take a simplified version of what you'll find in
:mod:`cubicweb.web.views.massmailing`.

Here is the source code:

.. sourcecode:: python

    def sender_value(form):
	return '%s <%s>' % (form._cw.user.dc_title(), form._cw.user.get_email())

    def recipient_choices(form, field):
	return [(e.get_email(), e.eid)
                 for e in form.cw_rset.entities()
		 if e.get_email()]

    def recipient_value(form):
	return [e.eid for e in form.cw_rset.entities()
                if e.get_email()]

    class MassMailingForm(forms.FieldsForm):
	__regid__ = 'massmailing'

	needs_js = ('cubicweb.widgets.js',)
	domid = 'sendmail'
	action = 'sendmail'

	sender = ff.StringField(widget=TextInput({'disabled': 'disabled'}),
				label=_('From:'),
				value=sender_value)

	recipient = ff.StringField(widget=CheckBox(),
	                           label=_('Recipients:'),
				   choices=recipient_choices,
				   value=recipients_value)

	subject = ff.StringField(label=_('Subject:'), max_length=256)

	mailbody = ff.StringField(widget=AjaxWidget(wdgtype='TemplateTextField',
						    inputid='mailbody'))

	form_buttons = [ImgButton('sendbutton', "javascript: $('#sendmail').submit()",
				  _('send email'), 'SEND_EMAIL_ICON'),
			ImgButton('cancelbutton', "javascript: history.back()",
				  stdmsgs.BUTTON_CANCEL, 'CANCEL_EMAIL_ICON')]

Let's detail what's going on up there. Our form will hold four fields:

* a sender field, which is disabled and will simply contains the user's name and
  email

* a recipients field, which will be displayed as a list of users in the context
  result set with checkboxes so user can still choose who will receive his mailing
  by checking or not the checkboxes. By default all of them will be checked since
  field's value return a list containing same eids as those returned by the
  vocabulary function.

* a subject field, limited to 256 characters (hence we know a
  :class:`~cubicweb.web.formwidgets.TextInput` will be used, as explained in
  :class:`~cubicweb.web.formfields.StringField`)

* a mailbody field. This field use an ajax widget, defined in `cubicweb.widgets.js`,
  and whose definition won't be shown here. Notice though that we tell this form
  need this javascript file by using `needs_js`

Last but not least, we add two buttons control: one to post the form using
javascript (`$('#sendmail')` being the jQuery call to get the element with DOM id
set to 'sendmail', which is our form DOM id as specified by its `domid`
attribute), another to cancel the form which will go back to the previous page
using another javascript call. Also we specify an image to use as button icon as a
resource identifier (see :ref:`uiprops`) given as last argument to
:class:`cubicweb.web.formwidgets.ImgButton`.

To see this form, we still have to wrap it in a view. This is pretty simple:

.. sourcecode:: python

    class MassMailingFormView(form.FormViewMixIn, EntityView):
	__regid__ = 'massmailing'
	__select__ = is_instance(IEmailable) & authenticated_user()

	def call(self):
	    form = self._cw.vreg['forms'].select('massmailing', self._cw,
	                                         rset=self.cw_rset)
	    form.render(w=self.w)

As you see, we simply define a view with proper selector so it only apply to a
result set containing :class:`IEmailable` entities, and so that only users in the
managers or users group can use it. Then in the `call()` method for this view we
simply select the above form and call its `.render()` method with our output
stream as argument.

When this form is submitted, a controller with id 'sendmail' will be called (as
specified using `action`). This controller will be responsible to actually send
the mail to specified recipients.

Here is what it looks like:

.. sourcecode:: python

   class SendMailController(Controller):
       __regid__ = 'sendmail'
       __select__ = (authenticated_user() &
                     match_form_params('recipient', 'mailbody', 'subject'))

       def publish(self, rset=None):
           body = self._cw.form['mailbody']
           subject = self._cw.form['subject']
           eids = self._cw.form['recipient']
           # eids may be a string if only one recipient was specified
           if isinstance(eids, basestring):
               rset = self._cw.execute('Any X WHERE X eid %(x)s', {'x': eids})
           else:
               rset = self._cw.execute('Any X WHERE X eid in (%s)' % (','.join(eids)))
           recipients = list(rset.entities())
           msg = format_mail({'email' : self._cw.user.get_email(),
                              'name' : self._cw.user.dc_title()},
                             recipients, body, subject)
           if not self._cw.vreg.config.sendmails([(msg, recipients]):
               msg = self._cw._('could not connect to the SMTP server')
           else:
               msg = self._cw._('emails successfully sent')
           raise Redirect(self._cw.build_url(__message=msg))


The entry point of a controller is the publish method. In that case we simply get
back post values in request's `form` attribute, get user instances according
to eids found in the 'recipient' form value, and send email after calling
:func:`format_mail` to get a proper email message. If we can't send email or
if we successfully sent email, we redirect to the index page with proper message
to inform the user.

Also notice that our controller has a selector that deny access to it
to anonymous users (we don't want our instance to be used as a spam
relay), but also checks if the expected parameters are specified in
forms. That avoids later defensive programming (though it's not enough
to handle all possible error cases).

To conclude our example, suppose we wish a different form layout and that existent
renderers are not satisfying (we would check that first of course :). We would then
have to define our own renderer:

.. sourcecode:: python

    class MassMailingFormRenderer(formrenderers.FormRenderer):
        __regid__ = 'massmailing'

        def _render_fields(self, fields, w, form):
            w(u'<table class="headersform">')
            for field in fields:
                if field.name == 'mailbody':
                    w(u'</table>')
                    w(u'<div id="toolbar">')
                    w(u'<ul>')
                    for button in form.form_buttons:
                        w(u'<li>%s</li>' % button.render(form))
                    w(u'</ul>')
                    w(u'</div>')
                    w(u'<div>')
                    w(field.render(form, self))
                    w(u'</div>')
                else:
                    w(u'<tr>')
                    w(u'<td class="hlabel">%s</td>' %
                      self.render_label(form, field))
                    w(u'<td class="hvalue">')
                    w(field.render(form, self))
                    w(u'</td></tr>')

        def render_buttons(self, w, form):
            pass

We simply override the `_render_fields` and `render_buttons` method of the base form renderer
to arrange fields as we desire it: here we'll have first a two columns table with label and
value of the sender, recipients and subject field (form order respected), then form controls,
then a div containing the textarea for the email's content.

To bind this renderer to our form, we should add to our form definition above:

.. sourcecode:: python

    form_renderer_id = 'massmailing'