Mollom API

  1. 7.x mollom/mollom.api.php mollom_api
  2. 6.x mollom/mollom.api.php mollom_api

Functions to integrate with Mollom form protection.

In general, there are two different kinds of form submissions:

  • Entities created out of form submissions, which can be edited or deleted afterwards; whereas "entity" just refers to a uniquely identifiable data record.
  • Form submissions that do not store any data, such as contact form mail messages and similar forms. While there may be an entity type (e.g., "contact_mail"), there is no unique id for the post, which could be referred to later on.

The Mollom API therefore supports two types of integration:

  • Entity form integration: Mollom integrates with the add/edit form for an entity, and additionally with the delete confirmation form of the entity to send feedback to Mollom. Almost everything happens in an automated way, solely based on the information provided via Mollom's info hooks, as explained below.
  • Free integration: Mollom integrates with a given form_id without 'entity'. Allowing users to send feedback requires to manually add "report to Mollom" links. Additionally requires to specify a 'report access [callback]' and 'report delete callback' to correctly handle access to report and delete a posted piece of content. An example for this kind of integration can be found in contact_mollom_form_list(), mollom_mail_alter(), and related functions. This kind of integration is discouraged; it is recommended to implement and integrate with entity forms.

Considering a very simple Instant Messaging module ("IM") that implements a "im_message_form" allowing to send or edit an instant message, which should be possible to be protected by Mollom:

function im_message_form(&$form_state, $im) {
  // To allow other modules to extend this form more easily and simplify our
  // own form submission handling, we use the dedicated parent key "im" for
  // all message properties (allows for easy casting from array to object).
  // Also helps us to explain handling of hierarchical sub-keys. :)
  $form['#tree'] = TRUE;

  // This is the stored message id (or 'post_id'), if any:
  //   $form['im']['id'] = array(
    '#type' => 'value',
    '#value' => isset($im->id) ? $im->id : NULL,
  );
  $form['im']['subject'] = array(
    '#type' => 'textfield',
    '#title' => t('Subject'),
    '#default_value' => isset($im->subject) ? $im->subject : '',
  );
  $form['im']['body'] = array(
    '#type' => 'textfield',
    '#title' => t('Message'),
    '#default_value' => isset($im->body) ? $im->body : '',
  );
  $form['actions']['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Send'),
  );
  return $form;
}

"entity" refers to an entity type. For example, "node", "user", "comment", but also "webform_submission". It is not necessarily the name of a database table, but most often it actually is. The string is only used internally to identify to which module a form submission belongs. Once in use, it should not be changed.

Our form accepts an argument $im, which we assume is the entity being created or edited, so we can also assume the following submit handler:

function im_message_form_submit($form, &$form_state) {
  // Do whatever we need to do to insert or update the message.
  $im = (object) $form_state['values']['im'];
  im_save($im);
  // Ensure subsequent submit handlers have an entity id to work with, as
  // newly created messages will not have an id in the form values.
  $form_state['values']['im']['id'] = $im->id;
}

The form values will not contain an entity id for a newly created message, which is usually an auto_increment column value returned from the database. Whenever a form submission is related to the entity (e.g., leads to a stored entity being created, updated, or deleted) the form should *always* contain the entity id in the same location of the submitted form values. Above example therefore purposively assigns the new id after inserting it.

function im_message_delete_confirm_form(&$form_state, $im) {
  $form['#im'] = $im;

  // Always provide entity id in the same form key as in the entity edit form.
  $form['im']['id'] = array('#type' => 'value', '#value' => $im->id);

  // In our case, we also need to enable #tree, so that above value ends up
  // in 'im][id' where we expect it.
  $form['#tree'] = TRUE;

  return confirm_form($form,
    t('Are you sure you want to delete %title?', array('%title' => $im->subject)),
    'im/' . $im->id,
    NULL,
    t('Delete')
  );
}

The same applies to the delete confirmation form for the entity: it also provides the entity id for form submit handlers.

After ensuring these basics, the first step is to register the basic form_id along with its title, entity type, as well as the form_id of the corresponding delete confirmation form via hook_mollom_form_list():

function im_mollom_form_list() {
  $forms['im_message_form'] = array(
    'title' => t('Instant messaging form'),
    'entity' => 'im',
    // Specify the $form_id of the delete confirmation form that allows
    // privileged users to delete a stored message. Mollom will automatically
    // add form elements to send feedback to Mollom to this form.
    'delete form' => 'im_message_delete_confirm_form',
  );
  return $forms;
}

Since modules can provide many forms, only minimal information is returned via hook_mollom_form_list(). All details about the form are only required and asked for, if the site administrator actually enables Mollom's protection for the form. Therefore, everything else is registered via hook_mollom_form_info():

function im_mollom_form_info($form_id) {
  switch ($form_id) {
    case 'im_message_form':
      $form_info = array(
        // Optional: User permission list to skip Mollom's protection for.
        'bypass access' => array('administer instant messages'),
        // Optional: Function to invoke to put a bad form submission into a
        // moderation queue instead of discarding it.
        'moderation callback' => 'im_mollom_form_moderation',
        // Optional: To allow textual analysis of the form values, the form
        // elements needs to be registered individually. The keys are the
        // field keys in $form_state['values']. Sub-keys are noted using "]["
        // as delimiter.
        'elements' => array(
          'im][subject' => t('Subject'),
          'im][body' => t('Message body'),
        ),
        // Required when either specifying 'entity' or 'elements': the keys
        // are predefined data properties sent to Mollom (see full list in
        // hook_mollom_form_info()), the values refer to field keys in
        // $form_state['values']. Sub-keys are noted using "][" as delimiter.
        'mapping' => array(
          // Required when specifying 'entity' above: Where to find the id of
          // the entity being posted, edited, or deleted.
          // Important: The following assignment means that Mollom is able to
          // find the message id of the created, edited, or deleted message
          // in $form_state['values']['im']['id'].
          'post_id' => 'im][id',
          // Required if the form or entity contains a title-alike field:
          'post_title' => 'im][subject',
          // Optional: If our instant message form was accessible for
          // anonymous users and would contain form elements to enter the
          // sender's name, e-mail address, and web site, then those fields
          // should be additionally specified. Otherwise, information from
          // the global user session would be automatically taken over.
          'author_name' => 'im][sender][name',
          'author_mail' => 'im][sender][mail',
          'author_url' => 'im][sender][homepage',
        ),
      );
      break;
  }
  return $form_info;
}

"elements" is a list of form elements, in which users can freely type text. The elements should not contain numeric or otherwise predefined option values, only text actually coming from user input. Only by registering "elements", Mollom is able to perform textual analysis. Without registered form elements, Mollom can only provide a CAPTCHA.

"mapping" is a mapping of form elements to predefined XML-RPC data properties of the Mollom web service. For example, "post_title", "author_name", "author_id", "author_mail", etc. Normally, all form elements specified in "elements" would be merged into the "post_body" data property. By specifying a "mapping", certain form element values are sent for the specified data property instead. In our case, the form submission contains something along the lines of a title in the "subject" field, so we map the "post_title" data property to the "subject" field.

Additionally, the "post_id" data property always needs to be mapped to a form element that holds the entity id.

When registering a 'moderation callback', then the registered function needs to be available when the form is validated, and it is responsible for changing the submitted form values in a way that results in an unpublished post ending up in a moderation queue:

function im_mollom_form_moderation(&$form, &$form_state) {
  $form_state['values']['status'] = 0;
}

See also

im_message_form_submit()

mollom_node

mollom_comment

mollom_user

mollom_contact

Functions

Namesort descending Location Description
hook_mollom_form_info mollom/mollom.api.php Return information about a form that can be protected by Mollom.
hook_mollom_form_info_alter mollom/mollom.api.php Alter registered information about a form that can be protected by Mollom.
hook_mollom_form_list mollom/mollom.api.php Return information about forms that can be protected by Mollom.
hook_mollom_form_list_alter mollom/mollom.api.php Alter the list of forms that can be protected by Mollom.

File

mollom/mollom.api.php, line 8
API documentation for Mollom module.