[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: mollom.api.php,v 1.1.2.7 2010/09/12 23:44:14 dries Exp $
   3  
   4  /**
   5   * @file
   6   * API documentation for Mollom module.
   7   */
   8  
   9  /**
  10   * @defgroup mollom_api Mollom API
  11   * @{
  12   * Functions to integrate with Mollom form protection.
  13   *
  14   * In general, there are two different kinds of form submissions:
  15   * - Entities created out of form submissions, which can be edited or deleted
  16   *   afterwards; whereas "entity" just refers to a uniquely identifiable data
  17   *   record.
  18   * - Form submissions that do not store any data, such as contact form mail
  19   *   messages and similar forms. While there may be an entity type (e.g.,
  20   *   "contact_mail"), there is no unique id for the post, which could be
  21   *   referred to later on.
  22   *
  23   * The Mollom API therefore supports two types of integration:
  24   * - Entity form integration: Mollom integrates with the add/edit form for an
  25   *   entity, and additionally with the delete confirmation form of the entity
  26   *   to send feedback to Mollom. Almost everything happens in an automated way,
  27   *   solely based on the information provided via Mollom's info hooks, as
  28   *   explained below.
  29   * - Free integration: Mollom integrates with a given form_id without 'entity'.
  30   *   Allowing users to send feedback requires to manually add "report to Mollom"
  31   *   links. Additionally requires to specify a 'report access [callback]' and
  32   *   'report delete callback' to correctly handle access to report and delete
  33   *   a posted piece of content. An example for this kind of integration can be
  34   *   found in contact_mollom_form_list(), mollom_mail_alter(), and related
  35   *   functions. This kind of integration is discouraged; it is recommended to
  36   *   implement and integrate with entity forms.
  37   *
  38   * Considering a very simple Instant Messaging module ("IM") that implements a
  39   * "im_message_form" allowing to send or edit an instant message, which should
  40   * be possible to be protected by Mollom:
  41   * @code
  42   * function im_message_form(&$form_state, $im) {
  43   *   // To allow other modules to extend this form more easily and simplify our
  44   *   // own form submission handling, we use the dedicated parent key "im" for
  45   *   // all message properties (allows for easy casting from array to object).
  46   *   // Also helps us to explain handling of hierarchical sub-keys. :)
  47   *   $form['#tree'] = TRUE;
  48   *
  49   *   // This is the stored message id (or 'post_id'), if any:
  50   *   // @see im_message_form_submit()
  51   *   $form['im']['id'] = array(
  52   *     '#type' => 'value',
  53   *     '#value' => isset($im->id) ? $im->id : NULL,
  54   *   );
  55   *   $form['im']['subject'] = array(
  56   *     '#type' => 'textfield',
  57   *     '#title' => t('Subject'),
  58   *     '#default_value' => isset($im->subject) ? $im->subject : '',
  59   *   );
  60   *   $form['im']['body'] = array(
  61   *     '#type' => 'textfield',
  62   *     '#title' => t('Message'),
  63   *     '#default_value' => isset($im->body) ? $im->body : '',
  64   *   );
  65   *   $form['actions']['submit'] = array(
  66   *     '#type' => 'submit',
  67   *     '#value' => t('Send'),
  68   *   );
  69   *   return $form;
  70   * }
  71   * @endcode
  72   *
  73   * "entity" refers to an entity type. For example, "node", "user", "comment",
  74   * but also "webform_submission". It is not necessarily the name of a database
  75   * table, but most often it actually is. The string is only used internally to
  76   * identify to which module a form submission belongs. Once in use, it should
  77   * not be changed.
  78   *
  79   * Our form accepts an argument $im, which we assume is the entity being created
  80   * or edited, so we can also assume the following submit handler:
  81   * @code
  82   * function im_message_form_submit($form, &$form_state) {
  83   *   // Do whatever we need to do to insert or update the message.
  84   *   $im = (object) $form_state['values']['im'];
  85   *   im_save($im);
  86   *   // Ensure subsequent submit handlers have an entity id to work with, as
  87   *   // newly created messages will not have an id in the form values.
  88   *   $form_state['values']['im']['id'] = $im->id;
  89   * }
  90   * @endcode
  91   *
  92   * The form values will not contain an entity id for a newly created message,
  93   * which is usually an auto_increment column value returned from the database.
  94   * Whenever a form submission is related to the entity (e.g., leads to a stored
  95   * entity being created, updated, or deleted) the form should *always* contain
  96   * the entity id in the same location of the submitted form values.
  97   * Above example therefore purposively assigns the new id after inserting it.
  98   *
  99   * @code
 100   * function im_message_delete_confirm_form(&$form_state, $im) {
 101   *   $form['#im'] = $im;
 102   *
 103   *   // Always provide entity id in the same form key as in the entity edit form.
 104   *   $form['im']['id'] = array('#type' => 'value', '#value' => $im->id);
 105   *
 106   *   // In our case, we also need to enable #tree, so that above value ends up
 107   *   // in 'im][id' where we expect it.
 108   *   $form['#tree'] = TRUE;
 109   *
 110   *   return confirm_form($form,
 111   *     t('Are you sure you want to delete %title?', array('%title' => $im->subject)),
 112   *     'im/' . $im->id,
 113   *     NULL,
 114   *     t('Delete')
 115   *   );
 116   * }
 117   * @endcode
 118   *
 119   * The same applies to the delete confirmation form for the entity: it also
 120   * provides the entity id for form submit handlers.
 121   *
 122   * After ensuring these basics, the first step is to register the basic form_id
 123   * along with its title, entity type, as well as the form_id of the
 124   * corresponding delete confirmation form via hook_mollom_form_list():
 125   *
 126   * @code
 127   * function im_mollom_form_list() {
 128   *   $forms['im_message_form'] = array(
 129   *     'title' => t('Instant messaging form'),
 130   *     'entity' => 'im',
 131   *     // Specify the $form_id of the delete confirmation form that allows
 132   *     // privileged users to delete a stored message. Mollom will automatically
 133   *     // add form elements to send feedback to Mollom to this form.
 134   *     'delete form' => 'im_message_delete_confirm_form',
 135   *   );
 136   *   return $forms;
 137   * }
 138   * @endcode
 139   *
 140   * Since modules can provide many forms, only minimal information is returned
 141   * via hook_mollom_form_list(). All details about the form are only required and
 142   * asked for, if the site administrator actually enables Mollom's protection for
 143   * the form. Therefore, everything else is registered via
 144   * hook_mollom_form_info():
 145   *
 146   * @code
 147   * function im_mollom_form_info($form_id) {
 148   *   switch ($form_id) {
 149   *     case 'im_message_form':
 150   *       $form_info = array(
 151   *         // Optional: User permission list to skip Mollom's protection for.
 152   *         'bypass access' => array('administer instant messages'),
 153   *         // Optional: To allow textual analysis of the form values, the form
 154   *         // elements needs to be registered individually. The keys are the
 155   *         // field keys in $form_state['values']. Sub-keys are noted using "]["
 156   *         // as delimiter.
 157   *         'elements' => array(
 158   *           'im][subject' => t('Subject'),
 159   *           'im][body' => t('Message body'),
 160   *         ),
 161   *         // Required when either specifying 'entity' or 'elements': the keys
 162   *         // are predefined data properties sent to Mollom (see full list in
 163   *         // hook_mollom_form_info()), the values refer to field keys in
 164   *         // $form_state['values']. Sub-keys are noted using "][" as delimiter.
 165   *         'mapping' => array(
 166   *           // Required when specifying 'entity' above: Where to find the id of
 167   *           // the entity being posted, edited, or deleted.
 168   *           // Important: The following assignment means that Mollom is able to
 169   *           // find the message id of the created, edited, or deleted message
 170   *           // in $form_state['values']['im']['id'].
 171   *           'post_id' => 'im][id',
 172   *           // Required if the form or entity contains a title-alike field:
 173   *           'post_title' => 'im][subject',
 174   *           // Optional: If our instant message form was accessible for
 175   *           // anonymous users and would contain form elements to enter the
 176   *           // sender's name, e-mail address, and web site, then those fields
 177   *           // should be additionally specified. Otherwise, information from
 178   *           // the global user session would be automatically taken over.
 179   *           'author_name' => 'im][sender][name',
 180   *           'author_mail' => 'im][sender][mail',
 181   *           'author_url' => 'im][sender][homepage',
 182   *         ),
 183   *       );
 184   *       break;
 185   *   }
 186   *   return $form_info;
 187   * }
 188   * @endcode
 189   *
 190   * "elements" is a list of form elements, in which users can freely type text.
 191   * The elements should not contain numeric or otherwise predefined option
 192   * values, only text actually coming from user input. Only by registering
 193   * "elements", Mollom is able to perform textual analysis. Without registered
 194   * form elements, Mollom can only provide a CAPTCHA.
 195   *
 196   * "mapping" is a mapping of form elements to predefined XML-RPC data properties
 197   * of the Mollom web service. For example, "post_title", "author_name",
 198   * "author_id", "author_mail", etc. Normally, all form elements specified in
 199   * "elements" would be merged into the "post_body" data property. By specifying
 200   * a "mapping", certain form element values are sent for the specified data
 201   * property instead. In our case, the form submission contains something along
 202   * the lines of a title in the "subject" field, so we map the "post_title" data
 203   * property to the "subject" field.
 204   *
 205   * Additionally, the "post_id" data property always needs to be mapped to a form
 206   * element that holds the entity id.
 207   *
 208   * @see mollom_node
 209   * @see mollom_comment
 210   * @see mollom_user
 211   * @see mollom_contact
 212   */
 213  
 214  /**
 215   * Return information about forms that can be protected by Mollom.
 216   *
 217   * Mollom invokes this hook for all modules to gather information about forms
 218   * that can be protected. Only forms that have been registered via this hook are
 219   * configurable in Mollom's administration interface.
 220   *
 221   * @return
 222   *   An associative array containing information about the forms that can be
 223   *   protected, keyed by $form_id:
 224   *   - title: The human-readable name of the form.
 225   *   - entity: (optional) The internal name of the entity type the form is for,
 226   *     e.g. 'node' or 'comment'. This is required for all forms that will store
 227   *     the submitted content persistently. It is only optional for forms that do
 228   *     not permanently store the submitted form values, such as contact forms
 229   *     that only send an e-mail, but do not store it in the database.
 230   *     Note that forms that specify 'entity' also need to specify 'post_id' in
 231   *     the 'mapping' (see below).
 232   *   - report access callback: (optional) A function name to invoke to check
 233   *     access to Mollom's dedicated "report to Mollom" form, which should return
 234   *     either TRUE or FALSE (like any other menu "access callback").
 235   *   - report access: (optional) A list containing user permission strings, from
 236   *     which the current user needs to have at least one. Should only be used if
 237   *     no "report access callback" was defined.
 238   *   - report delete callback: (optional) A function name to invoke to delete an
 239   *     entity after reporting it to Mollom.
 240   *
 241   * @see hook_mollom_form_info()
 242   */
 243  function hook_mollom_form_list() {
 244    // Mymodule's comment form.
 245    $forms['mymodule_comment_form'] = array(
 246      'title' => t('Comment form'),
 247      'entity' => 'mymodule_comment',
 248      'report access callback' => 'mymodule_comment_report_access',
 249      'report delete callback' => 'mymodule_comment_report_delete',
 250    );
 251    // Mymodule's user registration form.
 252    $forms['mymodule_user_register'] = array(
 253      'title' => t('User registration form'),
 254      'entity' => 'user',
 255      'report access' => array('administer comments', 'bypass node access'),
 256      // Make it private, so it's not a hook_user_delete() implementation.
 257      'report delete callback' => '_mymodule_user_delete',
 258    );
 259    return $forms;
 260  }
 261  
 262  /**
 263   * Return information about a form that can be protected by Mollom.
 264   *
 265   * @param $form_id
 266   *   The form id to return information for.
 267   *
 268   * @return
 269   *   An associative array describing the form identified by $form_id:
 270   *   - mode: (optional) The default protection mode for the form, which can be
 271   *     one of:
 272   *     - MOLLOM_MODE_ANALYSIS: Text analysis of submitted form values with
 273   *       fallback to CAPTCHA.
 274   *     - MOLLOM_MODE_CAPTCHA: CAPTCHA-only protection.
 275   *   - bypass access: (optional) A list of user permissions to check for the
 276   *     current user to determine whether to protect the form with Mollom or do
 277   *     not validate submitted form values. If the current user has at least one
 278   *     of the listed permissions, the form will not be protected.
 279   *   - mail ids: (optional) An array of mail IDs that will be sent as a result
 280   *     of this form being submitted. When these mails are sent, a 'report to
 281   *     Mollom' link will be included at the bottom of the mail body. Be sure to
 282   *     include only user-submitted mails and not any mails sent by Drupal since
 283   *     they should never be reported as spam.
 284   *   - elements: (optional) An associative array of elements in the form that
 285   *     can be configured for Mollom's text analysis. The site administrator can
 286   *     only select the form elements to process (and exclude certain elements)
 287   *     when a form registers elements. Each key is a form API element #parents
 288   *     string representation of the location of an element in the form. For
 289   *     example, a key of "myelement" denotes a form element value on the
 290   *     top-level of submitted form values. For nested elements, a key of
 291   *     "parent][child" denotes that the value of 'child' is found below 'parent'
 292   *     in the submitted form values. Each value contains the form element label.
 293   *     If omitted, Mollom can only provide a CAPTCHA protection for the form.
 294   *   - mapping: (optional) An associative array to explicitly map form elements
 295   *     (that have been specified in 'elements') to the data structure that is
 296   *     sent to Mollom for validation. The submitted form values of all mapped
 297   *     elements are not used for the post's body, so Mollom can validate certain
 298   *     values individually (such as the author's e-mail address). None of the
 299   *     mappings are required, but most implementations most likely want to at
 300   *     least denote the form element that contains the title of a post.
 301   *     The following mappings are possible:
 302   *     - post_id: The form element value that denotes the ID of the content
 303   *       stored in the database.
 304   *     - post_title: The form element value that should be used as title.
 305   *     - post_body: Mollom automatically assigns this property based on all
 306   *       elements that have been selected for textual analysis in Mollom's
 307   *       administrative form configuration.
 308   *     - author_name: The form element value that should be used as author name.
 309   *     - author_mail: The form element value that should be used as the author's
 310   *       e-mail address.
 311   *     - author_url: The form element value that should be used as the author's
 312   *       homepage.
 313   *     - author_id: The form element value that should be used as the author's
 314   *       user uid.
 315   *     - author_openid: Mollom automatically assigns this property based on
 316   *       'author_id', if no explicit form element value mapping was specified.
 317   *     - author_ip: Mollom automatically assigns the user's IP address if no
 318   *       explicit form element value mapping was specified.
 319   */
 320  function hook_mollom_form_info($form_id) {
 321    switch ($form_id) {
 322      // Mymodule's comment form.
 323      case 'mymodule_comment_form':
 324        $form_info = array(
 325          'mode' => MOLLOM_MODE_ANALYSIS,
 326          'bypass access' => array('administer comments'),
 327          'mail ids' => array('mymodule_comment_mail'),
 328          'elements' => array(
 329            'subject' => t('Subject'),
 330            'body' => t('Body'),
 331          ),
 332          'mapping' => array(
 333            'post_id' => 'cid',
 334            'post_title' => 'subject',
 335            'author_name' => 'name',
 336            'author_mail' => 'mail',
 337            'author_url' => 'homepage',
 338          ),
 339        );
 340        return $form_info;
 341  
 342      // Mymodule's user registration form.
 343      case 'mymodule_user_register':
 344        $form_info = array(
 345          'mode' => MOLLOM_MODE_CAPTCHA,
 346          'mapping' => array(
 347            'post_id' => 'uid',
 348            'author_name' => 'name',
 349            'author_mail' => 'mail',
 350          ),
 351        );
 352        return $form_info;
 353    }
 354  }
 355  
 356  /**
 357   * Alter registered information about a form that can be protected by Mollom.
 358   *
 359   * @param &$form_info
 360   *   An associative array describing the protectable form. See
 361   *   hook_mollom_form_info() for details.
 362   * @param $form_id
 363   *   The $form_id of the form.
 364   */
 365  function hook_mollom_form_info_alter(&$form_info, $form_id) {
 366    if ($form_id == 'comment_form') {
 367      $form_info['elements']['mymodule_field'] = t('My additional field');
 368    }
 369  }
 370  
 371  /**
 372   * @} End of "defgroup module_group".
 373   */