function hook_access_scheme_info in Access Control Kit 7

Defines access scheme types.

Modules can implement this hook to make various types of Drupal data available to the access control kit module as the basis for defining realms in an access scheme. For example, ACK itself implements this hook to allow access schemes to be based on taxonomy vocabularies or the allowed values of list fields.

Callback functions

The definition for each scheme type must include a realms callback function, which is invoked to find the list of realms in the scheme. The definition may also include a settings callback function, if the scheme type requires additional configuration. For example, in the taxonomy_term scheme type, the settings callback provides a form element for selecting the vocabulary that will define the scheme, and the realms callback returns a list of terms in the selected vocabulary.

Realms callbacks

Realms callbacks receive the scheme object as a parameter and return an array listing the currently available access realms in the scheme. The returned array will be used as the '#options' property of the realm selector on the access grant form; thus, the keys of this array are the realm values to be stored, and its values are the human-readable names of the access realms. For example, ACK defines taxonomy terms as a scheme type like so:

function access_access_scheme_info() {
  $info['taxonomy_term'] = array(
    'realms callback' => 'access_scheme_taxonomy_term_realms',
  );
  return $items;
}
function access_scheme_taxonomy_term_realms($scheme) {

  // Re-use the allowed values function for term reference fields.
  $field = array();
  $field['settings']['allowed_values'][] = array(
    'vocabulary' => $scheme->settings['vocabulary'],
    'parent' => 0,
  );
  return taxonomy_allowed_values($field);
}

Settings callbacks

Settings callbacks receive as parameters the scheme object and a boolean indicating whether access grants already exist for the scheme. A callback should return an array containing the form elements needed to configure the scheme. These elements will be displayed on the scheme add/edit form, and the submitted values will be stored in $scheme->settings. For example, ACK configures the taxonomy term scheme type like so:

function access_access_scheme_info() {
  $info['taxonomy_term'] = array(
    'settings callback' => 'access_scheme_taxonomy_term_settings',
  );
  return $items;
}
function access_scheme_taxonomy_term_settings($scheme, $has_data) {
  $options = array();
  foreach (taxonomy_get_vocabularies() as $vocabulary) {
    $options[$vocabulary->machine_name] = $vocabulary->name;
  }
  $settings = $scheme->settings;
  $value = isset($settings['vocabulary']) ? $settings['vocabulary'] : NULL;
  $form['vocabulary'] = array(
    '#type' => 'select',
    '#title' => t('Vocabulary'),
    '#default_value' => $value,
    '#options' => $options,
    '#required' => TRUE,
    '#disabled' => $has_data,
  );
  return $form;
}

Return value

array An array of scheme types. Each type has a key that defines the type's machine-readable name. The corresponding array value is an associative array that contains the following key-value pairs:

label: The human-readable name of the scheme type.
data_type: The data type of the realm values. Valid data types are 'boolean', 'integer', 'float' and 'text'.
description: (optional) A translated string describing the scheme type.
realms callback: The name of the function that provides the realm list.
settings callback: (optional) The name of the function that provides the scheme type's settings form.
file: (optional) A file that will be included before the callbacks are executed; this allows the callback functions to be in a separate file. The file should be relative to the implementing module's directory unless otherwise specified by the "file path" option.
file path: (optional) The path to the directory containing the file specified in "file". This defaults to the path to the module implementing the hook.

File

./access.api.php, line 212: Hooks provided by the access control kit module.

Code

function hook_access_scheme_info() {

  // Allow taxonomy vocabularies to be used as realm lists for access schemes.
  // Note that the data_type is an integer because the primary identifier for a
  // taxonomy term is its tid.
  $info['taxonomy_term'] = array(
    'label' => t('Taxonomy'),
    'data_type' => 'integer',
    'description' => t('A <em>taxonomy</em> scheme controls access based on the terms of a selected vocabulary.'),
    'realms callback' => 'access_scheme_taxonomy_term_realms',
    'settings callback' => 'access_scheme_taxonomy_term_settings',
    'file' => 'callbacks/access.taxonomy.inc',
  );
  return $info;
}

You are here