ack_handler.inc in Access Control Kit 7

Contains the access control kit handler interface and base class.

File

ack_handler.inc

<?php

/**
 * @file
 * Contains the access control kit handler interface and base class.
 */

/**
 * Interface for an object access handler.
 */
interface AccessControlKitHandlerInterface {

  /**
   * Constructor: generates an object access handler for an access scheme.
   *
   * @param object $scheme
   *   The access scheme.
   * @param array $settings
   *   (optional) The handler configuration array. Handler implementations may
   *   implement AccessControlKitHandlerInterface::settingsForm() to define the
   *   config values that will be contained in this array.
   *
   * @see AccessControlKitHandlerInterface::settingsForm()
   */
  public function __construct($scheme, array $settings = array());

  /**
   * Returns the current handler settings.
   *
   * @return array
   *   The handler configuration array.
   */
  public function getSettings();

  /**
   * Returns a description of the handler.
   *
   * @return string
   *   A translated string that describes the method by which this handler
   *   relates objects to realms in a scheme.
   */
  public function description();

  /**
   * Returns the form elements needed to configure the handler.
   *
   * @return array
   *   An array of form elements, or an empty array() if the handler does not
   *   require configuration. Similar to the way system_settings_form() works in
   *   Drupal core, the form values generated by this form on submission will
   *   become associative values in the handler's settings array (that is the
   *   $settings parameter to AccessControlKitHandlerInterface::__construct()).
   *   Also note that the returned form elements will be wrapped in a parent
   *   element that has its '#tree' value set to TRUE when this method is called
   *   by the ACK UI, so form structure will be retained in the settings array.
   *
   * @see system_settings_form()
   * @see system_settings_form_submit()
   */
  public function settingsForm();

  /**
   * Returns the list of realms to which a given object belongs in the scheme.
   *
   * @param string $object_type
   *   A string indicating the type of $object (e.g., node, menu_link).
   * @param mixed $object
   *   An access-controllable object, as defined by hook_access_info(). The
   *   actual data type depends on the object type, but is typically an array or
   *   a stdClass object.
   *
   * @return array
   *   An array of realms to which the object belongs. If no realms were found
   *   for the object, returns array().
   */
  public function objectRealms($object_type, $object);

  /**
   * Alters the add/edit form for an object to reflect ACK permissions.
   *
   * It is up to the handler module to invoke this method as needed from
   * hook_form_alter(). Implementations of this method should modify the object
   * form so that the object may only be assigned to those realms in the access
   * scheme where the user has "create" permission. The method should also
   * prevent the object's assigned realms from being changed on edit.
   *
   * For example, if the handler's objectRealms() method relates nodes to realms
   * in the scheme by means of a certain list field's value, then when creating
   * a new node, the user should only be allowed to select values in that list
   * field that correspond to realms in which the user has "create" permission.
   * And when editing an existing node, the list field should be disabled or
   * hidden, so as to prevent non-admins from moving the node to a different
   * realm in the access scheme. See the ack_node module for a complete example.
   *
   * This method can also be used in combination with the objectFormValidate()
   * and objectFormSubmit() methods to take additional actions when the object
   * form is submitted. See the ACKMenuMap handler in the ack_menu module for an
   * example of how this can be used to update data related to the object.
   *
   * In addition to this method, the handler module is responsible for enforcing
   * access to the delete button (if one exists) on the object's form. This is
   * typically done by setting '#access' => FALSE on the button when the user
   * does not have "delete" permission in any of the object's assigned realms.
   *
   * @param string $object_type
   *   A string indicating the type of $object (e.g., node, menu_link).
   * @param mixed $object
   *   The access-controllable object represented by this form.
   * @param array &$form
   *   The form structure to alter. This can be a full form structure, or a
   *   sub-element of a larger form.
   * @param array &$form_state
   *   An associative array containing the current state of the form.
   * @param string $form_id
   *   String representing the name of the form itself. Typically this is the
   *   name of the function that generated the form.
   * @param array $realms
   *   An array of the realm values that the user may choose for this object.
   *   Typically, this list corresponds to the user's "create" permissions for
   *   the object, and the parameter is omitted when editing an existing object.
   *   If omitted, form elements that correspond to realms in the scheme will be
   *   locked (either '#disabled' => TRUE or '#access' => FALSE).
   *
   * @see AccessControlKitHandlerInterface::objectFormValidate()
   * @see AccessControlKitHandlerInterface::objectFormSubmit()
   */
  public function objectFormAlter($object_type, $object, &$form, &$form_state, $form_id, $realms = NULL);

  /**
   * Performs additional validation on an access-controlled object's form.
   *
   * It is up to the handler module to invoke this method as needed by adding an
   * additional validation function to the form (using hook_form_alter()).
   *
   * @param string $object_type
   *   A string indicating the type of $object (e.g., node, menu_link).
   * @param mixed $object
   *   The access-controllable object represented by this form.
   * @param array $form
   *   The form structure. This can be a full form structure, or a sub-element
   *   of a larger form.
   * @param array &$form_state
   *   An associative array containing the current state of the form.
   *
   * @see AccessControlKitHandlerInterface::objectFormAlter()
   */
  public function objectFormValidate($object_type, $object, $form, &$form_state);

  /**
   * Performs handler-specific actions when an object's form is submitted.
   *
   * It is up to the handler module to invoke this method as needed by adding an
   * additional submission function to the form (using hook_form_alter()).
   *
   * @param string $object_type
   *   A string indicating the type of $object (e.g., node, menu_link).
   * @param mixed $object
   *   The access-controllable object represented by this form.
   * @param array $form
   *   The form structure. This can be a full form structure, or a sub-element
   *   of a larger form.
   * @param array &$form_state
   *   An associative array containing the current state of the form.
   *
   * @see AccessControlKitHandlerInterface::objectFormAlter()
   */
  public function objectFormSubmit($object_type, $object, $form, &$form_state);

  /**
   * Relates realm field values to access-controlled objects for Views.
   *
   * @param array &$data
   *   The Views data array, passed in from hook_views_data_alter().
   * @param string $scheme_machine_name
   *   The machine name of the scheme to which the handler is attached.
   * @param string $realm_field_table_name
   *   The name of the realm field table.
   * @param string $realm_field_table_value
   *   The name of the column that contains the realm value.
   * @param string $object_type
   *   A string indicating the type of $object (e.g., node, menu_link).
   */
  public function viewsDataAlter(&$data, $scheme_machine_name, $realm_field_table_name, $realm_field_table_value, $object_type);

}

/**
 * Base class for object access handlers.
 */
abstract class AccessControlKitHandler implements AccessControlKitHandlerInterface {

  /**
   * The access handler configuration.
   *
   * @var array
   */
  protected $settings;

  /**
   * Implements AccessControlKitHandlerInterface::__construct().
   */
  public function __construct($scheme, array $settings = array()) {
    $this->settings = $settings;
  }

  /**
   * Implements AccessControlKitHandlerInterface::getSettings().
   */
  public function getSettings() {
    return $this->settings;
  }

  /**
   * Implements AccessControlKitHandlerInterface::description().
   */
  public function description() {
    return '';
  }

  /**
   * Implements AccessControlKitHandlerInterface::settingsForm().
   */
  public function settingsForm() {
    return array();
  }

  /**
   * Implements AccessControlKitHandlerInterface::objectRealms().
   */
  public function objectRealms($object_type, $object) {
    return array();
  }

  /**
   * Implements AccessControlKitHandlerInterface::objectFormAlter().
   */
  public function objectFormAlter($object_type, $object, &$form, &$form_state, $form_id, $realms = NULL) {

    // No filtering needed in the abstract class.
  }

  /**
   * Implements AccessControlKitHandlerInterface::objectFormValidate().
   */
  public function objectFormValidate($object_type, $object, $form, &$form_state) {

    // No validation needed in the abstract class.
  }

  /**
   * Implements AccessControlKitHandlerInterface::objectFormSubmit().
   */
  public function objectFormSubmit($object_type, $object, $form, &$form_state) {

    // No submit actions needed in the abstract class.
  }

  /**
   * Implements AccessControlKitHandlerInterface::viewsDataAlter().
   */
  public function viewsDataAlter(&$data, $scheme_machine_name, $realm_field_table_name, $realm_field_table_value, $object_type) {

    // No Views integration needed in the abstract class.
  }

}

Classes

Name	Description
AccessControlKitHandler	Base class for object access handlers.

Interfaces

Name	Description
AccessControlKitHandlerInterface	Interface for an object access handler.