[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: context-access-admin.inc,v 1.7.2.2 2010/07/14 23:32:08 merlinofchaos Exp $
   3  
   4  /**
   5   * @file
   6   * Contains administrative screens for the access control plugins.
   7   *
   8   * Access control can be implemented by creating a list of 0 or more access
   9   * plugins, each with settings. This list can be ANDed together or ORed
  10   * together. When testing access, each plugin is tested until success
  11   * or failure can be determined. We use short circuiting techniques to
  12   * ensure we are as efficient as possible.
  13   *
  14   * Access plugins are part of the context system, and as such can require
  15   * contexts to work. That allows the use of access based upon visibility
  16   * of an object, or even more esoteric things such as node type, node language
  17   * etc. Since a lot of access depends on the logged in user, the logged in
  18   * user should always be provided as a context.
  19   *
  20   * In the UI, the user is presented with a table and a 'add access method' select.
  21   * When added, the user will be presented with the config wizard and, when
  22   * confirmed, table will be refreshed via AJAX to show the new access method.
  23   * Each item in the table will have controls to change the settings or remove
  24   * the item. Changing the settings will invoke the modal for update.
  25   *
  26   * Currently the modal is not degradable, but it could be with only a small
  27   * amount of work.
  28   *
  29   * A simple radio
  30   * control is used to let the user pick the and/or logic.
  31   *
  32   * Access control is stored in an array:
  33   * @code
  34   *   array(
  35   *     'plugins' => array(
  36   *       0 => array(
  37   *         'name' => 'name of access plugin',
  38   *         'settings' => array(), // These will be set by the form
  39   *       ),
  40   *       // ... as many as needed
  41   *     ),
  42   *     'logic' => 'AND', // or 'OR',
  43   *   ),
  44   * @endcode
  45   *
  46   * To add this widget to your UI, you need to do a little bit of setup.
  47   *
  48   * The form will utilize two callbacks, one to get the cached version
  49   * of the access settings, and one to store the cached version of the
  50   * access settings. These will be used from AJAX forms, so they will
  51   * be completely out of the context of this page load and will not have
  52   * knowledge of anything sent to this form (the 'module' and 'argument'
  53   * will be preserved through the URL only).
  54   *
  55   * The 'module' is used to determine the location of the callback. It
  56   * does not strictly need to be a module, so that if your module defines
  57   * multiple systems that use this callback, it can use anything within the
  58   * module's namespace it likes.
  59   *
  60   * When retrieving the cache, the cache may not have already been set up;
  61   * In order to efficiently use cache space, we want to cache the stored
  62   * settings *only* when they have changed. Therefore, the get access cache
  63   * callback should first look for cache, and if it finds nothing, return
  64   * the original settings.
  65   *
  66   * The callbacks:
  67   * - $module . _ctools_access_get($argument) -- get the 'access' settings
  68   *   from cache. Must return array($access, $contexts); This callback can
  69   *   perform access checking to make sure this URL is not being gamed.
  70   * - $module . _ctools_access_set($argument, $access) -- set the 'access'
  71   *   settings in cache.
  72   * - $module . _ctools_access_clear($argument) -- clear the cache.
  73   *
  74   * The ctools_object_cache is recommended for this purpose, but you can use
  75   * any caching mechanism you like. An example:
  76   *
  77   * @code{
  78   *   ctools_include('object-cache');
  79   *   ctools_object_cache_set("$module:argument", $access);
  80   * }
  81   *
  82   * To utilize this form:
  83   * @code
  84   *   ctools_include('context-access-admin');
  85   *   ctools_include('form'),
  86   *   $form_state = array(
  87   *     'access' => $access,
  88   *     'module' => 'module name',
  89   *     'callback argument' => 'some string',
  90   *     'contexts' => $contexts, // an array of contexts. Optional if no contexts.
  91   *     // 'logged-in-user' will be added if not present as the access system
  92   *     // requires this context.
  93   *   ),
  94   *   $output = ctools_build_form('ctools_access_admin_form', $form_state);
  95   *   if (!empty($form_state['executed'])) {
  96   *     // save $form_state['access'] however you like.
  97   *   }
  98   * @endcode
  99   *
 100   * Additionally, you may add 'no buttons' => TRUE if you wish to embed this
 101   * form into your own, and instead call
 102   *
 103   * @code{
 104   *   $form = array_merge($form, ctools_access_admin_form($form_state));
 105   * }
 106   *
 107   * You'll be responsible for adding a submit button.
 108   *
 109   * You may use ctools_access($access, $contexts) which will return
 110   * TRUE if access is passed or FALSE if access is not passed.
 111   */
 112  
 113  /**
 114   * Administrative form for access control.
 115   */
 116  function ctools_access_admin_form(&$form_state) {
 117    ctools_include('context');
 118    $argument = isset($form_state['callback argument']) ? $form_state['callback argument'] : '';
 119    $fragment = $form_state['module'];
 120    if ($argument) {
 121      $fragment .= '-' . $argument;
 122    }
 123  
 124    $contexts = isset($form_state['contexts']) ? $form_state['contexts'] : array();
 125  
 126    $form['access_table'] = array(
 127      '#value' => ctools_access_admin_render_table($form_state['access'], $fragment, $contexts),
 128    );
 129  
 130    $form['add-button'] = array(
 131      '#theme' => 'ctools_access_admin_add',
 132    );
 133    // This sets up the URL for the add access modal.
 134    $form['add-button']['add-url'] = array(
 135      '#attributes' => array('class' => "ctools-access-add-url"),
 136      '#type' => 'hidden',
 137      '#value' => url("ctools/context/ajax/access/add/$fragment", array('absolute' => TRUE)),
 138    );
 139  
 140    $plugins = ctools_get_relevant_access_plugins($contexts);
 141    $options = array();
 142    foreach ($plugins as $id => $plugin) {
 143      $options[$id] = $plugin['title'];
 144    }
 145  
 146    asort($options);
 147  
 148    $form['add-button']['type'] = array(
 149      // This ensures that the form item is added to the URL.
 150      '#attributes' => array('class' => "ctools-access-add-url"),
 151      '#type' => 'select',
 152      '#options' => $options,
 153    );
 154  
 155    $form['add-button']['add'] = array(
 156      '#type' => 'submit',
 157      '#attributes' => array('class' => 'ctools-use-modal'),
 158      '#id' => "ctools-access-add",
 159      '#value' => t('Add'),
 160    );
 161  
 162    $form['logic'] = array(
 163      '#type' => 'radios',
 164      '#options' => array(
 165        'and' => t('All criteria must pass.'),
 166        'or' => t('Only one criteria must pass.'),
 167      ),
 168      '#default_value' => isset($form_state['access']['logic']) ? $form_state['access']['logic'] : 'and',
 169    );
 170  
 171    if (empty($form_state['no buttons'])) {
 172      $form['buttons']['save'] = array(
 173        '#type' => 'submit',
 174        '#value' => t('Save'),
 175        '#submit' => array('ctools_access_admin_form_submit'),
 176      );
 177    }
 178  
 179    return $form;
 180  }
 181  
 182  /**
 183   * Render the table. This is used both to render it initially and to rerender
 184   * it upon ajax response.
 185   */
 186  function ctools_access_admin_render_table($access, $fragment, $contexts) {
 187    ctools_include('ajax');
 188    ctools_include('modal');
 189    $rows = array();
 190  
 191    if (empty($access['plugins'])) {
 192      $access['plugins'] = array();
 193    }
 194  
 195    foreach ($access['plugins'] as $id => $test) {
 196      $row    = array();
 197      $plugin = ctools_get_access_plugin($test['name']);
 198      $title  = isset($plugin['title']) ? $plugin['title'] : t('Broken/missing access plugin %plugin', array('%plugin' => $test['name']));
 199  
 200      $row[] = array('data' => $title, 'class' => 'ctools-access-title');
 201  
 202      $description = ctools_access_summary($plugin, $contexts, $test);
 203      $row[] = array('data' => $description, 'class' => 'ctools-access-description');
 204  
 205      $operations = ctools_modal_image_button(ctools_image_path('icon-configure.png'), "ctools/context/ajax/access/configure/$fragment/$id", t('Configure settings for this item.'));
 206      $operations .= ctools_ajax_image_button(ctools_image_path('icon-delete.png'), "ctools/context/ajax/access/delete/$fragment/$id", t('Remove this item.'));
 207  
 208      $row[] = array('data' => $operations, 'class' => 'ctools-access-operations', 'align' => 'right');
 209  
 210      $rows[] = $row;
 211    }
 212  
 213    $header = array(
 214      array('data' => t('Title'), 'class' => 'ctools-access-title'),
 215      array('data' => t('Description'), 'class' => 'ctools-access-description'),
 216      array('data' => '', 'class' => 'ctools-access-operations', 'align' => 'right'),
 217    );
 218  
 219    if (empty($rows)) {
 220      $rows[] = array(array('data' => t('No criteria selected, this test will pass.'), 'colspan' => count($header)));
 221    }
 222  
 223    ctools_modal_add_js();
 224    return theme('table', $header, $rows, array('id' => 'ctools-access-table'));
 225  }
 226  
 227  /**
 228   * Theme the 'add' portion of the access form into a table.
 229   */
 230  function theme_ctools_access_admin_add($form) {
 231    $rows = array(array(drupal_render($form)));
 232    $output = '<div class="container-inline">';
 233    $output .= theme('table', array(), $rows);
 234    $output .= '</div>';
 235    return $output;
 236  }
 237  
 238  function ctools_access_admin_form_submit($form, &$form_state) {
 239    $form_state['access']['logic'] = $form_state['values']['logic'];
 240  
 241    $function = $form_state['module'] . '_ctools_access_clear';
 242    if (function_exists($function)) {
 243      $function($form_state['argument']);
 244    }
 245  }
 246  
 247  // --------------------------------------------------------------------------
 248  // AJAX menu entry points.
 249  
 250  /**
 251   * AJAX callback to add a new access test to the list.
 252   */
 253  function ctools_access_ajax_add($fragment = NULL, $name = NULL) {
 254    ctools_include('ajax');
 255    ctools_include('modal');
 256    ctools_include('context');
 257  
 258    if (empty($fragment) || empty($name)) {
 259      ctools_ajax_render_error();
 260    }
 261  
 262    $plugin = ctools_get_access_plugin($name);
 263    if (empty($plugin)) {
 264      ctools_ajax_render_error();
 265    }
 266  
 267    // Separate the fragment into 'module' and 'argument'
 268    if (strpos($fragment, '-') === FALSE) {
 269      $module = $fragment;
 270      $argument = NULL;
 271    }
 272    else {
 273      list($module, $argument) = explode('-', $fragment, 2);
 274    }
 275  
 276    $function = $module . '_ctools_access_get';
 277    if (!function_exists($function)) {
 278      ctools_ajax_render_error(t('Missing callback hooks.'));
 279    }
 280  
 281    list($access, $contexts) = $function($argument);
 282  
 283    // Make sure we have the logged in user context
 284    if (!isset($contexts['logged-in-user'])) {
 285      $contexts['logged-in-user'] = ctools_access_get_loggedin_context();
 286    }
 287  
 288    if (empty($access['plugins'])) {
 289      $access['plugins'] = array();
 290    }
 291  
 292    $test = ctools_access_new_test($plugin);
 293  
 294    $id = $access['plugins'] ? max(array_keys($access['plugins'])) + 1 : 0;
 295    $access['plugins'][$id] = $test;
 296  
 297    $form_state = array(
 298      'plugin' => $plugin,
 299      'id' => $id,
 300      'test' => &$access['plugins'][$id],
 301      'access' => &$access,
 302      'contexts' => $contexts,
 303      'title' => t('Add criteria'),
 304      'ajax' => TRUE,
 305    );
 306  
 307    $output = ctools_modal_form_wrapper('ctools_access_ajax_edit_item', $form_state);
 308    if (empty($output)) {
 309      $function = $module . '_ctools_access_set';
 310      if (function_exists($function)) {
 311        $function($argument, $access);
 312      }
 313  
 314      $table    = ctools_access_admin_render_table($access, $fragment, $contexts);
 315      $output   = array();
 316      $output[] = ctools_ajax_command_replace('table#ctools-access-table', $table);
 317      $output[] = ctools_modal_command_dismiss();
 318    }
 319  
 320    ctools_ajax_render($output);
 321  }
 322  
 323  /**
 324   * AJAX callback to edit an access test in the list.
 325   */
 326  function ctools_access_ajax_edit($fragment = NULL, $id = NULL) {
 327    ctools_include('ajax');
 328    ctools_include('modal');
 329    ctools_include('context');
 330  
 331    if (empty($fragment) || !isset($id)) {
 332      ctools_ajax_render_error();
 333    }
 334  
 335    // Separate the fragment into 'module' and 'argument'
 336    if (strpos($fragment, '-') === FALSE) {
 337      $module = $fragment;
 338      $argument = NULL;
 339    }
 340    else {
 341      list($module, $argument) = explode('-', $fragment, 2);
 342    }
 343  
 344    $function = $module . '_ctools_access_get';
 345    if (!function_exists($function)) {
 346      ctools_ajax_render_error(t('Missing callback hooks.'));
 347    }
 348  
 349    list($access, $contexts) = $function($argument);
 350  
 351    if (empty($access['plugins'][$id])) {
 352      ctools_ajax_render_error();
 353    }
 354  
 355    // Make sure we have the logged in user context
 356    if (!isset($contexts['logged-in-user'])) {
 357      $contexts['logged-in-user'] = ctools_access_get_loggedin_context();
 358    }
 359  
 360    $plugin = ctools_get_access_plugin($access['plugins'][$id]['name']);
 361    $form_state = array(
 362      'plugin' => $plugin,
 363      'id' => $id,
 364      'test' => &$access['plugins'][$id],
 365      'access' => &$access,
 366      'contexts' => $contexts,
 367      'title' => t('Edit criteria'),
 368      'ajax' => TRUE,
 369    );
 370  
 371    $output = ctools_modal_form_wrapper('ctools_access_ajax_edit_item', $form_state);
 372    if (empty($output)) {
 373      $function = $module . '_ctools_access_set';
 374      if (function_exists($function)) {
 375        $function($argument, $access);
 376      }
 377  
 378      $table    = ctools_access_admin_render_table($access, $fragment, $contexts);
 379      $output   = array();
 380      $output[] = ctools_ajax_command_replace('table#ctools-access-table', $table);
 381      $output[] = ctools_modal_command_dismiss();
 382    }
 383  
 384    ctools_ajax_render($output);
 385  }
 386  
 387  /**
 388   * Form to edit the settings of an access test.
 389   */
 390  function ctools_access_ajax_edit_item(&$form_state) {
 391    $test = &$form_state['test'];
 392    $plugin = &$form_state['plugin'];
 393  
 394    if (isset($plugin['required context'])) {
 395      $form['context'] = ctools_context_selector($form_state['contexts'], $plugin['required context'], $test['context']);
 396    }
 397    $form['settings'] = array('#tree' => TRUE);
 398    if ($function = ctools_plugin_get_function($plugin, 'settings form')) {
 399      $function($form, $form_state, $test['settings']);
 400    }
 401  
 402    $form['not'] = array(
 403      '#type' => 'checkbox',
 404      '#title' => t('Reverse (NOT)'),
 405      '#default_value' => !empty($test['not']),
 406    );
 407  
 408    $form['save'] = array(
 409      '#type' => 'submit',
 410      '#value' => t('Save'),
 411    );
 412  
 413    return $form;
 414  }
 415  
 416  /**
 417   * Validate handler for argument settings.
 418   */
 419  function ctools_access_ajax_edit_item_validate(&$form, &$form_state) {
 420    if ($function = ctools_plugin_get_function($form_state['plugin'], 'settings form validate')) {
 421      $function($form, $form_state);
 422    }
 423  }
 424  
 425  /**
 426   * Submit handler for argument settings.
 427   */
 428  function ctools_access_ajax_edit_item_submit(&$form, &$form_state) {
 429    if ($function = ctools_plugin_get_function($form_state['plugin'], 'settings form submit')) {
 430      $function($form, $form_state);
 431    }
 432  
 433    $form_state['test']['settings'] = $form_state['values']['settings'];
 434    if (isset($form_state['values']['context'])) {
 435      $form_state['test']['context'] = $form_state['values']['context'];
 436    }
 437    $form_state['test']['not'] = !empty($form_state['values']['not']);
 438  }
 439  
 440  /**
 441   * AJAX command to remove an access control item.
 442   */
 443  function ctools_access_ajax_delete($fragment = NULL, $id = NULL) {
 444    ctools_include('ajax');
 445    ctools_include('modal');
 446    ctools_include('context');
 447  
 448    if (empty($fragment) || !isset($id)) {
 449      ctools_ajax_render_error();
 450    }
 451  
 452    // Separate the fragment into 'module' and 'argument'
 453    if (strpos($fragment, '-') === FALSE) {
 454      $module = $fragment;
 455      $argument = NULL;
 456    }
 457    else {
 458      list($module, $argument) = explode('-', $fragment, 2);
 459    }
 460  
 461    $function = $module . '_ctools_access_get';
 462    if (!function_exists($function)) {
 463      ctools_ajax_render_error(t('Missing callback hooks.'));
 464    }
 465  
 466    list($access, $contexts) = $function($argument);
 467  
 468    if (isset($access['plugins'][$id])) {
 469      unset($access['plugins'][$id]);
 470    }
 471  
 472    // re-cache
 473    $function = $module . '_ctools_access_set';
 474    if (function_exists($function)) {
 475      $function($argument, $access);
 476    }
 477  
 478    $table    = ctools_access_admin_render_table($access, $fragment, $contexts);
 479    $output   = array();
 480    $output[] = ctools_ajax_command_replace('table#ctools-access-table', $table);
 481  
 482    ctools_ajax_render($output);
 483  }