class views_handler in Views (for Drupal 7) 6.2

Base handler, from which all the other handlers are derived. It creates a common interface to create consistency amongst handlers and data.

This class would be abstract in PHP5, but PHP4 doesn't understand that.

Definition terms:

• table: The actual table this uses; only specify if different from the table this is attached to.
• real field: The actual field this uses; only specify if different from the field this item is attached to.
• group: A text string representing the 'group' this item is attached to, for display in the UI. Examples: "Node", "Taxonomy", "Comment", "User", etc. This may be inherited from the parent definition or the 'table' definition.
• title: The title for this handler in the UI. This may be inherited from the parent definition or the 'table' definition.
• help: A more informative string to give to the user to explain what this field/handler is or does.
• access callback: If this field should have access control, this could be a function to use. 'user_access' is a common function to use here. If not specified, no access control is provided.
• access arguments: An array of arguments for the access callback.

Hierarchy

• class \views_object
  • class \views_handler

1 string reference to 'views_handler'

views_views_handlers in includes/handlers.inc

Implementation of hook_views_handlers() to register all of the basic handlers views uses.

File

includes/handlers.inc, line 228

handlers.inc Defines the various handler objects to help build and display views.

class views_handler extends views_object {

  /**
   * init the handler with necessary data.
   * @param $view
   *   The $view object this handler is attached to.
   * @param $options
   *   The item from the database; the actual contents of this will vary
   *   based upon the type of handler.
   */
  function init(&$view, $options) {
    $this->view =& $view;
    $this
      ->unpack_options($this->options, $options);

    // This exist on most handlers, but not all. So they are still optional.
    if (isset($options['table'])) {
      $this->table = $options['table'];
    }
    if (isset($this->definition['real field'])) {
      $this->real_field = $this->definition['real field'];
    }
    if (isset($this->definition['field'])) {
      $this->real_field = $this->definition['field'];
    }
    if (isset($options['field'])) {
      $this->field = $options['field'];
      if (!isset($this->real_field)) {
        $this->real_field = $options['field'];
      }
    }
    $this->query =& $view->query;
  }

  /**
   * Return a string representing this handler's name in the UI.
   */
  function ui_name($short = FALSE) {
    $title = $short && isset($this->definition['title short']) ? $this->definition['title short'] : $this->definition['title'];
    return t('!group: !title', array(
      '!group' => $this->definition['group'],
      '!title' => $title,
    ));
  }

  /**
   * Provide a form for setting options.
   */
  function options_form(&$form, &$form_state) {
  }

  /**
   * Validate the options form.
   */
  function options_validate($form, &$form_state) {
  }

  /**
   * Perform any necessary changes to the form values prior to storage.
   * There is no need for this function to actually store the data.
   */
  function options_submit($form, &$form_state) {
  }

  /**
   * If a handler has 'extra options' it will get a little settings widget and
   * another form called extra_options.
   */
  function has_extra_options() {
    return FALSE;
  }

  /**
   * Provide defaults for the handler.
   */
  function extra_options(&$option) {
  }

  /**
   * Provide a form for setting options.
   */
  function extra_options_form(&$form, &$form_state) {
  }

  /**
   * Validate the options form.
   */
  function extra_options_validate($form, &$form_state) {
  }

  /**
   * Perform any necessary changes to the form values prior to storage.
   * There is no need for this function to actually store the data.
   */
  function extra_options_submit($form, &$form_state) {
  }

  /**
   * Set new exposed option defaults when exposed setting is flipped
   * on.
   */
  function expose_options() {
  }

  /**
   * Render our chunk of the exposed filter form when selecting
   */
  function exposed_form(&$form, &$form_state) {
  }

  /**
   * Validate the exposed filter form
   */
  function exposed_validate(&$form, &$form_state) {
  }

  /**
   * Submit the exposed filter form
   */
  function exposed_submit(&$form, &$form_state) {
  }

  /**
   * Get information about the exposed form for the form renderer.
   *
   * @return
   *   An array with the following keys:
   *   - operator: The $form key of the operator. Set to NULL if no operator.
   *   - value: The $form key of the value. Set to NULL if no value.
   *   - label: The label to use for this piece.
   */
  function exposed_info() {
  }

  /**
   * Determine if a handler can be exposed.
   */
  function can_expose() {
    return FALSE;
  }

  /**
   * Check whether current user has access to this handler.
   *
   * @return boolean
   */
  function access() {
    if (isset($this->definition['access callback']) && function_exists($this->definition['access callback'])) {
      if (isset($this->definition['access arguments']) && is_array($this->definition['access arguments'])) {
        return call_user_func_array($this->definition['access callback'], $this->definition['access arguments']);
      }
      return $this->definition['access callback']();
    }
    return TRUE;
  }

  /**
   * Run before the view is built.
   *
   * This gives all the handlers some time to set up before any handler has
   * been fully run.
   */
  function pre_query() {
  }

  /**
   * Called just prior to query(), this lets a handler set up any relationship
   * it needs.
   */
  function set_relationship() {

    // Ensure this gets set to something.
    $this->relationship = NULL;

    // Don't process non-existant relationships.
    if (empty($this->options['relationship']) || $this->options['relationship'] == 'none') {
      return;
    }
    $relationship = $this->options['relationship'];

    // Ignore missing/broken relationships.
    if (empty($this->view->relationship[$relationship])) {
      return;
    }

    // Check to see if the relationship has already processed. If not, then we
    // cannot process it.
    if (empty($this->view->relationship[$relationship]->alias)) {
      return;
    }

    // Finally!
    $this->relationship = $this->view->relationship[$relationship]->alias;
  }

  /**
   * Add this handler into the query.
   *
   * If we were using PHP5, this would be abstract.
   */
  function query() {
  }

  /**
   * Ensure the main table for this handler is in the query. This is used
   * a lot.
   */
  function ensure_my_table() {
    if (!isset($this->table_alias)) {
      $this->table_alias = $this->query
        ->ensure_table($this->table, $this->relationship);
    }
    return $this->table_alias;
  }

  /**
   * Provide text for the administrative summary
   */
  function admin_summary() {
  }

  /**
   * Determine if the argument needs a style plugin.
   *
   * @return TRUE/FALSE
   */
  function needs_style_plugin() {
    return FALSE;
  }

  /**
   * Determine if this item is 'exposed', meaning it provides form elements
   * to let users modify the view.
   *
   * @return TRUE/FALSE
   */
  function is_exposed() {
    return !empty($this->options['exposed']);
  }

  /**
   * Take input from exposed filters and assign to this handler, if necessary.
   */
  function accept_exposed_input($input) {
    return TRUE;
  }

  /**
   * If set to remember exposed input in the session, store it there.
   */
  function store_exposed_input($input, $status) {
    return TRUE;
  }

  /**
   * Get the join object that should be used for this handler.
   *
   * This method isn't used a great deal, but it's very handy for easily
   * getting the join if it is necessary to make some changes to it, such
   * as adding an 'extra'.
   */
  function get_join() {

    // get the join from this table that links back to the base table.
    // Determine the primary table to seek
    if (empty($this->query->relationships[$this->relationship])) {
      $base_table = $this->query->base_table;
    }
    else {
      $base_table = $this->query->relationships[$this->relationship]['base'];
    }
    $join = views_get_table_join($this->table, $base_table);
    if ($join) {
      return drupal_clone($join);
    }
  }

  /**
   * Validates the handler against the complete View.
   *
   * This is called when the complete View is being validated. For validating
   * the handler options form use options_validate().
   *
   * @see views_handler::options_validate()
   *
   * @return
   *   Empty array if the handler is valid; an array of error strings if it is not.
   */
  function validate() {
    return array();
  }

  /**
   * Determine if the handler is considered 'broken', meaning it's a
   * a placeholder used when a handler can't be found.
   */
  function broken() {
  }

}

Members

Name	Modifiers	Type	Description	Overrides
views_handler::accept_exposed_input		function	Take input from exposed filters and assign to this handler, if necessary.	1
views_handler::access		function	Check whether current user has access to this handler.	5
views_handler::admin_summary		function	Provide text for the administrative summary	3
views_handler::broken		function	Determine if the handler is considered 'broken', meaning it's a a placeholder used when a handler can't be found.	5
views_handler::can_expose		function	Determine if a handler can be exposed.	1
views_handler::ensure_my_table		function	Ensure the main table for this handler is in the query. This is used a lot.	7
views_handler::exposed_form		function	Render our chunk of the exposed filter form when selecting	1
views_handler::exposed_info		function	Get information about the exposed form for the form renderer.	1
views_handler::exposed_submit		function	Submit the exposed filter form
views_handler::exposed_validate		function	Validate the exposed filter form	4
views_handler::expose_options		function	Set new exposed option defaults when exposed setting is flipped on.	1
views_handler::extra_options		function	Provide defaults for the handler.
views_handler::extra_options_form		function	Provide a form for setting options.	1
views_handler::extra_options_submit		function	Perform any necessary changes to the form values prior to storage. There is no need for this function to actually store the data.
views_handler::extra_options_validate		function	Validate the options form.
views_handler::get_join		function	Get the join object that should be used for this handler.
views_handler::has_extra_options		function	If a handler has 'extra options' it will get a little settings widget and another form called extra_options.	1
views_handler::init		function	init the handler with necessary data.	4
views_handler::is_exposed		function	Determine if this item is 'exposed', meaning it provides form elements to let users modify the view.
views_handler::needs_style_plugin		function	Determine if the argument needs a style plugin.	1
views_handler::options_form		function	Provide a form for setting options.	5
views_handler::options_submit		function	Perform any necessary changes to the form values prior to storage. There is no need for this function to actually store the data.	1
views_handler::options_validate		function	Validate the options form.	1
views_handler::pre_query		function	Run before the view is built.	1
views_handler::query		function	Add this handler into the query.	5
views_handler::set_relationship		function	Called just prior to query(), this lets a handler set up any relationship it needs.
views_handler::store_exposed_input		function	If set to remember exposed input in the session, store it there.	1
views_handler::ui_name		function	Return a string representing this handler's name in the UI.	5
views_handler::validate		function	Validates the handler against the complete View.
views_object::$options		property	Except for displays, options for the object will be held here.	1
views_object::construct		function	Views handlers use a special construct function so that we can more easily construct them with variable arguments.	5
views_object::destroy		function		2
views_object::options		function	Set default options on this object. Called by the constructor in a complex chain to deal with backward compatibility.	1
views_object::option_definition		function	Information about options for all kinds of purposes will be held here.	9
views_object::set_default_options		function	Set default options. For backward compatibility, it sends the options array; this is a feature that will likely disappear at some point.
views_object::set_definition		function	Let the handler know what its full definition is.
views_object::unpack_options		function	Unpack options over our existing defaults, drilling down into arrays so that defaults don't get totally blown away.
views_object::_set_option_defaults		function		1