context-access-admin.inc in Chaos Tool Suite (ctools) 7

Same filename and directory in other branches

6 includes/context-access-admin.inc

Contains administrative screens for the access control plugins.

Access control can be implemented by creating a list of 0 or more access plugins, each with settings. This list can be ANDed together or ORed together. When testing access, each plugin is tested until success or failure can be determined. We use short circuiting techniques to ensure we are as efficient as possible.

Access plugins are part of the context system, and as such can require contexts to work. That allows the use of access based upon visibility of an object, or even more esoteric things such as node type, node language etc. Since a lot of access depends on the logged in user, the logged in user should always be provided as a context.

In the UI, the user is presented with a table and a 'add access method' select. When added, the user will be presented with the config wizard and, when confirmed, table will be refreshed via AJAX to show the new access method. Each item in the table will have controls to change the settings or remove the item. Changing the settings will invoke the modal for update.

Currently the modal is not degradable, but it could be with only a small amount of work.

A simple radio control is used to let the user pick the and/or logic.

Access control is stored in an array:


  array(
    'plugins' => array(
      0 => array(
        'name' => 'name of access plugin',
        'settings' => array(), // These will be set by the form
      ),
      // ... as many as needed
    ),
    'logic' => 'AND', // or 'OR',
  ),

To add this widget to your UI, you need to do a little bit of setup.

The form will utilize two callbacks, one to get the cached version of the access settings, and one to store the cached version of the access settings. These will be used from AJAX forms, so they will be completely out of the context of this page load and will not have knowledge of anything sent to this form (the 'module' and 'argument' will be preserved through the URL only).

The 'module' is used to determine the location of the callback. It does not strictly need to be a module, so that if your module defines multiple systems that use this callback, it can use anything within the module's namespace it likes.

When retrieving the cache, the cache may not have already been set up; In order to efficiently use cache space, we want to cache the stored settings *only* when they have changed. Therefore, the get access cache callback should first look for cache, and if it finds nothing, return the original settings.

The callbacks:

$module . _ctools_access_get($argument) -- get the 'access' settings from cache. Must return array($access, $contexts); This callback can perform access checking to make sure this URL is not being gamed.
$module . _ctools_access_set($argument, $access) -- set the 'access' settings in cache.
$module . _ctools_access_clear($argument) -- clear the cache.

The ctools_object_cache is recommended for this purpose, but you can use any caching mechanism you like. An example:

?>
<?php{
  ctools_include('object-cache');
  ctools_object_cache_set("$module:argument", $access);
}

To utilize this form:
@code
  ctools_include('context-access-admin');
  $form_state = array(
    'access' => $access,
    'module' => 'module name',
    'callback argument' => 'some string',
    'contexts' => $contexts, // an array of contexts. Optional if no contexts.
    // 'logged-in-user' will be added if not present as the access system
    // requires this context.
  ),
  $output = drupal_build_form('ctools_access_admin_form', $form_state);
  if (!empty($form_state['executed'])) {
    // save $form_state['access'] however you like.
  }
?><?php

Additionally, you may add 'no buttons' => TRUE if you wish to embed this form into your own, and instead call

@code{ $form = ctools_access_admin_form($form, $form_state); }

You'll be responsible for adding a submit button.

You may use ctools_access($access, $contexts) which will return TRUE if access is passed or FALSE if access is not passed.

File

includes/context-access-admin.inc

View source

<?php

/**
 * @file
 * Contains administrative screens for the access control plugins.
 *
 * Access control can be implemented by creating a list of 0 or more access
 * plugins, each with settings. This list can be ANDed together or ORed
 * together. When testing access, each plugin is tested until success
 * or failure can be determined. We use short circuiting techniques to
 * ensure we are as efficient as possible.
 *
 * Access plugins are part of the context system, and as such can require
 * contexts to work. That allows the use of access based upon visibility
 * of an object, or even more esoteric things such as node type, node language
 * etc. Since a lot of access depends on the logged in user, the logged in
 * user should always be provided as a context.
 *
 * In the UI, the user is presented with a table and a 'add access method' select.
 * When added, the user will be presented with the config wizard and, when
 * confirmed, table will be refreshed via AJAX to show the new access method.
 * Each item in the table will have controls to change the settings or remove
 * the item. Changing the settings will invoke the modal for update.
 *
 * Currently the modal is not degradable, but it could be with only a small
 * amount of work.
 *
 * A simple radio
 * control is used to let the user pick the and/or logic.
 *
 * Access control is stored in an array:
 * @code
 *   array(
 *     'plugins' => array(
 *       0 => array(
 *         'name' => 'name of access plugin',
 *         'settings' => array(), // These will be set by the form
 *       ),
 *       // ... as many as needed
 *     ),
 *     'logic' => 'AND', // or 'OR',
 *   ),
 * @endcode
 *
 * To add this widget to your UI, you need to do a little bit of setup.
 *
 * The form will utilize two callbacks, one to get the cached version
 * of the access settings, and one to store the cached version of the
 * access settings. These will be used from AJAX forms, so they will
 * be completely out of the context of this page load and will not have
 * knowledge of anything sent to this form (the 'module' and 'argument'
 * will be preserved through the URL only).
 *
 * The 'module' is used to determine the location of the callback. It
 * does not strictly need to be a module, so that if your module defines
 * multiple systems that use this callback, it can use anything within the
 * module's namespace it likes.
 *
 * When retrieving the cache, the cache may not have already been set up;
 * In order to efficiently use cache space, we want to cache the stored
 * settings *only* when they have changed. Therefore, the get access cache
 * callback should first look for cache, and if it finds nothing, return
 * the original settings.
 *
 * The callbacks:
 * - $module . _ctools_access_get($argument) -- get the 'access' settings
 *   from cache. Must return array($access, $contexts); This callback can
 *   perform access checking to make sure this URL is not being gamed.
 * - $module . _ctools_access_set($argument, $access) -- set the 'access'
 *   settings in cache.
 * - $module . _ctools_access_clear($argument) -- clear the cache.
 *
 * The ctools_object_cache is recommended for this purpose, but you can use
 * any caching mechanism you like. An example:
 *
 * @code{
 *   ctools_include('object-cache');
 *   ctools_object_cache_set("$module:argument", $access);
 * }
 *
 * To utilize this form:
 * @code
 *   ctools_include('context-access-admin');
 *   $form_state = array(
 *     'access' => $access,
 *     'module' => 'module name',
 *     'callback argument' => 'some string',
 *     'contexts' => $contexts, // an array of contexts. Optional if no contexts.
 *     // 'logged-in-user' will be added if not present as the access system
 *     // requires this context.
 *   ),
 *   $output = drupal_build_form('ctools_access_admin_form', $form_state);
 *   if (!empty($form_state['executed'])) {
 *     // save $form_state['access'] however you like.
 *   }
 * @endcode
 *
 * Additionally, you may add 'no buttons' => TRUE if you wish to embed this
 * form into your own, and instead call
 *
 * @code{
 *   $form = ctools_access_admin_form($form, $form_state);
 * }
 *
 * You'll be responsible for adding a submit button.
 *
 * You may use ctools_access($access, $contexts) which will return
 * TRUE if access is passed or FALSE if access is not passed.
 */

/**
 * Administrative form for access control.
 */
function ctools_access_admin_form($form, &$form_state) {
  ctools_include('context');
  $argument = isset($form_state['callback argument']) ? $form_state['callback argument'] : '';
  $fragment = $form_state['module'];
  if ($argument) {
    $fragment .= '-' . $argument;
  }
  $contexts = isset($form_state['contexts']) ? $form_state['contexts'] : array();
  $form['access_table'] = array(
    '#markup' => ctools_access_admin_render_table($form_state['access'], $fragment, $contexts),
  );
  $form['add-button'] = array(
    '#theme' => 'ctools_access_admin_add',
  );

  // This sets up the URL for the add access modal.
  $form['add-button']['add-url'] = array(
    '#attributes' => array(
      'class' => array(
        "ctools-access-add-url",
      ),
    ),
    '#type' => 'hidden',
    '#value' => url("ctools/context/ajax/access/add/{$fragment}", array(
      'absolute' => TRUE,
    )),
  );
  $plugins = ctools_get_relevant_access_plugins($contexts);
  $options = array();
  foreach ($plugins as $id => $plugin) {
    $options[$id] = $plugin['title'];
  }
  asort($options);
  $form['add-button']['type'] = array(
    // This ensures that the form item is added to the URL.
    '#attributes' => array(
      'class' => array(
        "ctools-access-add-url",
      ),
    ),
    '#type' => 'select',
    '#options' => $options,
    '#required' => FALSE,
  );
  $form['add-button']['add'] = array(
    '#type' => 'submit',
    '#attributes' => array(
      'class' => array(
        'ctools-use-modal',
      ),
    ),
    '#id' => "ctools-access-add",
    '#value' => t('Add'),
  );
  $form['logic'] = array(
    '#type' => 'radios',
    '#options' => array(
      'and' => t('All criteria must pass.'),
      'or' => t('Only one criteria must pass.'),
    ),
    '#default_value' => isset($form_state['access']['logic']) ? $form_state['access']['logic'] : 'and',
  );
  if (empty($form_state['no buttons'])) {
    $form['buttons']['save'] = array(
      '#type' => 'submit',
      '#value' => t('Save'),
      '#submit' => array(
        'ctools_access_admin_form_submit',
      ),
    );
  }
  return $form;
}

/**
 * Render the table. This is used both to render it initially and to rerender
 * it upon ajax response.
 */
function ctools_access_admin_render_table($access, $fragment, $contexts) {
  ctools_include('ajax');
  ctools_include('modal');
  $rows = array();
  if (empty($access['plugins'])) {
    $access['plugins'] = array();
  }
  foreach ($access['plugins'] as $id => $test) {
    $row = array();
    $plugin = ctools_get_access_plugin($test['name']);
    $title = isset($plugin['title']) ? $plugin['title'] : t('Broken/missing access plugin %plugin', array(
      '%plugin' => $test['name'],
    ));
    $row[] = array(
      'data' => $title,
      'class' => array(
        'ctools-access-title',
      ),
    );
    $description = ctools_access_summary($plugin, $contexts, $test);
    $row[] = array(
      'data' => $description,
      'class' => array(
        'ctools-access-description',
      ),
    );
    $operations = ctools_modal_image_button(ctools_image_path('icon-configure.png'), "ctools/context/ajax/access/configure/{$fragment}/{$id}", t('Configure settings for this item.'));
    $operations .= ctools_ajax_image_button(ctools_image_path('icon-delete.png'), "ctools/context/ajax/access/delete/{$fragment}/{$id}", t('Remove this item.'));
    $row[] = array(
      'data' => $operations,
      'class' => array(
        'ctools-access-operations',
      ),
      'align' => 'right',
    );
    $rows[] = $row;
  }
  $header = array(
    array(
      'data' => t('Title'),
      'class' => array(
        'ctools-access-title',
      ),
    ),
    array(
      'data' => t('Description'),
      'class' => array(
        'ctools-access-description',
      ),
    ),
    array(
      'data' => '',
      'class' => array(
        'ctools-access-operations',
      ),
      'align' => 'right',
    ),
  );
  if (empty($rows)) {
    $rows[] = array(
      array(
        'data' => t('No criteria selected, this test will pass.'),
        'colspan' => count($header),
      ),
    );
  }
  ctools_modal_add_js();
  return theme('table', array(
    'header' => $header,
    'rows' => $rows,
    'attributes' => array(
      'id' => 'ctools-access-table',
    ),
  ));
}

/**
 * Theme the 'add' portion of the access form into a table.
 */
function theme_ctools_access_admin_add($vars) {
  $rows = array(
    array(
      drupal_render_children($vars['form']),
    ),
  );
  $output = '<div class="container-inline">';
  $output .= theme('table', array(
    'rows' => $rows,
  ));
  $output .= '</div>';
  return $output;
}
function ctools_access_admin_form_submit($form, &$form_state) {
  $form_state['access']['logic'] = $form_state['values']['logic'];
  $function = $form_state['module'] . '_ctools_access_clear';
  if (function_exists($function)) {
    $function($form_state['callback argument']);
  }
}

// --------------------------------------------------------------------------
// AJAX menu entry points.

/**
 * AJAX callback to add a new access test to the list.
 */
function ctools_access_ajax_add($fragment = NULL, $name = NULL) {
  ctools_include('ajax');
  ctools_include('modal');
  ctools_include('context');
  if (empty($fragment) || empty($name)) {
    ctools_ajax_render_error();
  }
  $plugin = ctools_get_access_plugin($name);
  if (empty($plugin)) {
    ctools_ajax_render_error();
  }

  // Separate the fragment into 'module' and 'argument'.
  if (strpos($fragment, '-') === FALSE) {
    $module = $fragment;
    $argument = NULL;
  }
  else {
    list($module, $argument) = explode('-', $fragment, 2);
  }
  $function = $module . '_ctools_access_get';
  if (!function_exists($function)) {
    ctools_ajax_render_error(t('Missing callback hooks.'));
  }
  list($access, $contexts) = $function($argument);

  // Make sure we have the logged in user context.
  if (!isset($contexts['logged-in-user'])) {
    $contexts['logged-in-user'] = ctools_access_get_loggedin_context();
  }
  if (empty($access['plugins'])) {
    $access['plugins'] = array();
  }
  $test = ctools_access_new_test($plugin);
  $id = $access['plugins'] ? max(array_keys($access['plugins'])) + 1 : 0;
  $access['plugins'][$id] = $test;
  $form_state = array(
    'plugin' => $plugin,
    'id' => $id,
    'test' => &$access['plugins'][$id],
    'access' => &$access,
    'contexts' => $contexts,
    'title' => t('Add criteria'),
    'ajax' => TRUE,
    'modal' => TRUE,
    'modal return' => TRUE,
  );
  $output = ctools_modal_form_wrapper('ctools_access_ajax_edit_item', $form_state);
  $access = $form_state['access'];
  $access['plugins'][$id] = $form_state['test'];
  if (!isset($output[0])) {
    $function = $module . '_ctools_access_set';
    if (function_exists($function)) {
      $function($argument, $access);
    }
    $table = ctools_access_admin_render_table($access, $fragment, $contexts);
    $output = array();
    $output[] = ajax_command_replace('table#ctools-access-table', $table);
    $output[] = ctools_modal_command_dismiss();
  }
  print ajax_render($output);
}

/**
 * AJAX callback to edit an access test in the list.
 */
function ctools_access_ajax_edit($fragment = NULL, $id = NULL) {
  ctools_include('ajax');
  ctools_include('modal');
  ctools_include('context');
  if (empty($fragment) || !isset($id)) {
    ctools_ajax_render_error();
  }

  // Separate the fragment into 'module' and 'argument'.
  if (strpos($fragment, '-') === FALSE) {
    $module = $fragment;
    $argument = NULL;
  }
  else {
    list($module, $argument) = explode('-', $fragment, 2);
  }
  $function = $module . '_ctools_access_get';
  if (!function_exists($function)) {
    ctools_ajax_render_error(t('Missing callback hooks.'));
  }
  list($access, $contexts) = $function($argument);
  if (empty($access['plugins'][$id])) {
    ctools_ajax_render_error();
  }

  // Make sure we have the logged in user context.
  if (!isset($contexts['logged-in-user'])) {
    $contexts['logged-in-user'] = ctools_access_get_loggedin_context();
  }
  $plugin = ctools_get_access_plugin($access['plugins'][$id]['name']);
  $form_state = array(
    'plugin' => $plugin,
    'id' => $id,
    'test' => &$access['plugins'][$id],
    'access' => &$access,
    'contexts' => $contexts,
    'title' => t('Edit criteria'),
    'ajax' => TRUE,
    'modal' => TRUE,
    'modal return' => TRUE,
  );
  $output = ctools_modal_form_wrapper('ctools_access_ajax_edit_item', $form_state);
  $access = $form_state['access'];
  $access['plugins'][$id] = $form_state['test'];
  if (!isset($output[0])) {
    $function = $module . '_ctools_access_set';
    if (function_exists($function)) {
      $function($argument, $access);
    }
    $table = ctools_access_admin_render_table($access, $fragment, $contexts);
    $output = array();
    $output[] = ajax_command_replace('table#ctools-access-table', $table);
    $output[] = ctools_modal_command_dismiss();
  }
  print ajax_render($output);
}

/**
 * Form to edit the settings of an access test.
 */
function ctools_access_ajax_edit_item($form, &$form_state) {
  $test =& $form_state['test'];
  $plugin =& $form_state['plugin'];
  if (isset($plugin['required context'])) {
    $form['context'] = ctools_context_selector($form_state['contexts'], $plugin['required context'], $test['context']);
  }
  $form['settings'] = array(
    '#tree' => TRUE,
  );
  if ($function = ctools_plugin_get_function($plugin, 'settings form')) {
    $form = $function($form, $form_state, $test['settings']);
  }
  $form['not'] = array(
    '#type' => 'checkbox',
    '#title' => t('Reverse (NOT)'),
    '#default_value' => !empty($test['not']),
  );
  $form['save'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );
  return $form;
}

/**
 * Validate handler for argument settings.
 */
function ctools_access_ajax_edit_item_validate($form, &$form_state) {
  if ($function = ctools_plugin_get_function($form_state['plugin'], 'settings form validate')) {
    $function($form, $form_state);
  }
}

/**
 * Submit handler for argument settings.
 */
function ctools_access_ajax_edit_item_submit($form, &$form_state) {
  if ($function = ctools_plugin_get_function($form_state['plugin'], 'settings form submit')) {
    $function($form, $form_state);
  }
  $form_state['test']['settings'] = $form_state['values']['settings'];
  if (isset($form_state['values']['context'])) {
    $form_state['test']['context'] = $form_state['values']['context'];
  }
  $form_state['test']['not'] = !empty($form_state['values']['not']);
}

/**
 * AJAX command to remove an access control item.
 */
function ctools_access_ajax_delete($fragment = NULL, $id = NULL) {
  ctools_include('ajax');
  ctools_include('modal');
  ctools_include('context');
  if (empty($fragment) || !isset($id)) {
    ajax_render_error();
  }

  // Separate the fragment into 'module' and 'argument'.
  if (strpos($fragment, '-') === FALSE) {
    $module = $fragment;
    $argument = NULL;
  }
  else {
    list($module, $argument) = explode('-', $fragment, 2);
  }
  $function = $module . '_ctools_access_get';
  if (!function_exists($function)) {
    ajax_render_error(t('Missing callback hooks.'));
  }
  list($access, $contexts) = $function($argument);
  if (isset($access['plugins'][$id])) {
    unset($access['plugins'][$id]);
  }

  // re-cache.
  $function = $module . '_ctools_access_set';
  if (function_exists($function)) {
    $function($argument, $access);
  }
  $table = ctools_access_admin_render_table($access, $fragment, $contexts);
  $output = array();
  $output[] = ajax_command_replace('table#ctools-access-table', $table);
  print ajax_render($output);
}

Functions

Name	Description
ctools_access_admin_form	Administrative form for access control.
ctools_access_admin_form_submit
ctools_access_admin_render_table	Render the table. This is used both to render it initially and to rerender it upon ajax response.
ctools_access_ajax_add	AJAX callback to add a new access test to the list.
ctools_access_ajax_delete	AJAX command to remove an access control item.
ctools_access_ajax_edit	AJAX callback to edit an access test in the list.
ctools_access_ajax_edit_item	Form to edit the settings of an access test.
ctools_access_ajax_edit_item_submit	Submit handler for argument settings.
ctools_access_ajax_edit_item_validate	Validate handler for argument settings.
theme_ctools_access_admin_add	Theme the 'add' portion of the access form into a table.

You are here

context-access-admin.inc in Chaos Tool Suite (ctools) 7

File

Functions

API Navigation