You are here

Home » API reference » Views (for Drupal 7) 6.3 » views_handler_filter.inc

class views_handler_filter in Views (for Drupal 7) 6.3

Same name and namespace in other branches
  1. 6.2 handlers/views_handler_filter.inc \views_handler_filter
  2. 7.3 handlers/views_handler_filter.inc \views_handler_filter

Base class for filters.

Hierarchy

Expanded class hierarchy of views_handler_filter

Related topics

Views' filter handlers
Handlers to tell Views how to filter queries.
4 string references to 'views_handler_filter'
node_views_handlers in modules/node.views.inc
Implementation of hook_views_handlers() to register all of the basic handlers views uses.
search_views_handlers in modules/search.views.inc
Implementation of hook_views_handlers() to register all of the basic handlers views uses.
translation_views_handlers in modules/translation.views.inc
Implementation of hook_views_handlers() to register all of the basic handlers views uses.
views_views_handlers in includes/handlers.inc
Implementation of hook_views_handlers() to register all of the basic handlers views uses.

File

handlers/views_handler_filter.inc, line 26

View source 
class views_handler_filter extends views_handler {

  /**
   * Contains the actual value of the field,either configured in the views ui
   * or entered in the exposed filters.
   */
  var $value = NULL;

  /**
   * Contains the operator which is used on the query.
   */
  var $operator = '=';

  /**
   * Provide some extra help to get the operator/value easier to use.
   *
   * This likely has to be overridden by filters which are more complex
   * than simple operator/value.
   */
  function init(&$view, $options) {
    parent::init($view, $options);
    $this->operator = $this->options['operator'];
    $this->value = $this->options['value'];

    // If there are relationships in the view, allow empty should be true
    // so that we can do IS NULL checks on items. Not all filters respect
    // allow empty, but string and numeric do and that covers enough.
    if ($this->view->display_handler
      ->get_option('relationships')) {
      $this->definition['allow empty'] = TRUE;
    }
  }
  function option_definition() {
    $options = parent::option_definition();
    $options['operator'] = array(
      'default' => '=',
    );
    $options['value'] = array(
      'default' => '',
    );
    $options['group'] = array(
      'default' => '1',
    );
    $options['exposed'] = array(
      'default' => FALSE,
    );
    $options['expose'] = array(
      'contains' => array(
        'operator' => array(
          'default' => FALSE,
        ),
        'limit_operators' => array(
          'default' => FALSE,
        ),
        'available_operators' => array(
          'default' => array(),
        ),
        'label' => array(
          'default' => '',
          'translatable' => TRUE,
        ),
        'use_operator' => array(
          'default' => 0,
        ),
        'operator' => array(
          'default' => '',
        ),
        'identifier' => array(
          'default' => '',
        ),
        'optional' => array(
          'default' => 1,
        ),
        'remember' => array(
          'default' => 0,
        ),
        'single' => array(
          'default' => 1,
        ),
      ),
    );
    return $options;
  }

  /**
   * Display the filter on the administrative summary
   */
  function admin_summary() {
    return check_plain((string) $this->operator) . ' ' . check_plain((string) $this->value);
  }

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

  /**
   * Provide the basic form which calls through to subforms.
   * If overridden, it is best to call through to the parent,
   * or to at least make sure all of the functions in this form
   * are called.
   */
  function options_form(&$form, &$form_state) {
    parent::options_form($form, $form_state);
    if ($this
      ->can_expose()) {
      $this
        ->show_expose_button($form, $form_state);
    }
    $form['op_val_start'] = array(
      '#value' => '<div class="clear-block">',
    );
    $this
      ->show_operator_form($form, $form_state);
    $this
      ->show_value_form($form, $form_state);
    $form['op_val_end'] = array(
      '#value' => '</div>',
    );
    if ($this
      ->can_expose()) {
      $this
        ->show_expose_form($form, $form_state);
    }
  }

  /**
   * Simple validate handler
   */
  function options_validate(&$form, &$form_state) {
    $this
      ->operator_validate($form, $form_state);
    $this
      ->value_validate($form, $form_state);
    if (!empty($this->options['exposed'])) {
      $this
        ->expose_validate($form, $form_state);
    }
  }

  /**
   * Simple submit handler
   */
  function options_submit($form, &$form_state) {
    unset($form_state['values']['expose_button']);

    // don't store this.
    $this
      ->operator_submit($form, $form_state);
    $this
      ->value_submit($form, $form_state);
    if (!empty($this->options['exposed'])) {
      if (!empty($form_state['values']['options']['expose']['limit_operators'])) {
        $form_state['values']['options']['expose']['available_operators'] = array_filter($form_state['values']['options']['expose']['available_operators']);
      }
      else {
        $form_state['values']['options']['expose']['available_operators'] = array();
      }
      $this
        ->expose_submit($form, $form_state);
      if (empty($form_state['values']['options']['expose']['use_operator'])) {
        $form_state['values']['options']['expose']['limit_operators'] = array();
      }
    }
  }

  /**
   * Shortcut to display the operator form.
   */
  function show_operator_form(&$form, &$form_state) {
    $this
      ->operator_form($form, $form_state);
    $form['operator']['#prefix'] = '<div class="views-left-30">';
    $form['operator']['#suffix'] = '</div>';
  }

  /**
   * Provide a form for setting the operator.
   *
   * This may be overridden by child classes, and it must
   * define $form['operator'];
   */
  function operator_form(&$form, &$form_state) {
    $options = $this
      ->operator_options();
    if (!empty($options)) {
      $limit = array_filter($this->options['expose']['available_operators']);
      if (!empty($this->options['expose']['limit_operators']) && count($limit)) {
        foreach ($options as $key => $value) {
          if (!isset($limit[$key])) {
            unset($options[$key]);
          }
        }
      }
      $form['operator'] = array(
        '#type' => count($options) < 10 ? 'radios' : 'select',
        '#title' => t('Operator'),
        '#default_value' => $this->operator,
        '#options' => $options,
      );
    }
  }

  /**
   * Provide a list of options for the default operator form.
   * Should be overridden by classes that don't override operator_form
   */
  function operator_options() {
    return array();
  }

  /**
   * Validate the operator form.
   */
  function operator_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 operator_submit($form, &$form_state) {
  }

  /**
   * Shortcut to display the value form.
   */
  function show_value_form(&$form, &$form_state) {
    $this
      ->value_form($form, $form_state);
    if (empty($this->no_operator)) {
      $form['value']['#prefix'] = '<div class="views-right-70">' . (isset($form['value']['#prefix']) ? $form['value']['#prefix'] : '');
      $form['value']['#suffix'] = (isset($form['value']['#suffix']) ? $form['value']['#suffix'] : '') . '</div>';
    }
  }

  /**
   * Provide a form for setting options.
   *
   * This should be overridden by all child classes and it must
   * define $form['value']
   */
  function value_form(&$form, &$form_state) {
    $form['value'] = array();
  }

  /**
   * Validate the options form.
   */
  function value_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 value_submit($form, &$form_state) {
  }

  /**
   * Handle the 'left' side fo the exposed options form.
   */
  function expose_form_left(&$form, &$form_state) {
    if (!empty($form['operator']['#type'])) {
      $form['expose']['use_operator'] = array(
        '#type' => 'checkbox',
        '#title' => t('Unlock operator'),
        '#description' => t('When checked, the operator will be exposed to the user'),
        '#default_value' => !empty($this->options['expose']['use_operator']),
      );
      $form['expose']['operator'] = array(
        '#type' => 'textfield',
        '#default_value' => $this->options['expose']['operator'],
        '#title' => t('Operator identifier'),
        '#size' => 40,
        '#description' => t('This will appear in the URL after the ? to identify this operator.'),
        '#process' => array(
          'views_process_dependency',
        ),
        '#dependency' => array(
          'edit-options-expose-use-operator' => array(
            1,
          ),
        ),
      );
      $form['expose']['limit_operators'] = array(
        '#type' => 'checkbox',
        '#title' => t('Limit operators'),
        '#description' => t('When checked, the operator will be exposed to the user'),
        '#default_value' => !empty($this->options['expose']['limit_operators']),
        '#process' => array(
          'views_process_dependency',
        ),
        '#dependency' => array(
          'edit-options-expose-use-operator' => array(
            1,
          ),
        ),
        '#description' => t('Restrict which operators will be available to select in the exposed operator form.'),
      );
      $operator_options = $this
        ->operator_options();
      if (count($operator_options)) {
        $form['expose']['available_operators'] = array(
          '#type' => 'checkboxes',
          '#title' => t('Limit the exposed operators'),
          '#default_value' => $this->options['expose']['available_operators'],
          '#prefix' => '<div id="edit-options-expose-available-operators-wrapper"><div id = "edit-options-expose-available-operators">',
          '#suffix' => '</div></div>',
          '#description' => t('Select which operators will be available to select in the exposed operator form. If none is selected, all the operators listed here will be used.'),
          '#options' => $operator_options,
          '#process' => array(
            'expand_checkboxes',
            'views_process_dependency',
          ),
          '#dependency' => array(
            'edit-options-expose-limit-operators' => array(
              1,
            ),
          ),
        );
      }
    }
    else {
      $form['expose']['operator'] = array(
        '#type' => 'value',
        '#value' => '',
      );
    }
    $form['expose']['identifier'] = array(
      '#type' => 'textfield',
      '#default_value' => $this->options['expose']['identifier'],
      '#title' => t('Filter identifier'),
      '#size' => 40,
      '#description' => t('This will appear in the URL after the ? to identify this filter. Cannot be blank.'),
    );
    $form['expose']['label'] = array(
      '#type' => 'textfield',
      '#default_value' => $this->options['expose']['label'],
      '#title' => t('Label'),
      '#size' => 40,
    );
  }

  /**
   * Handle the 'right' side fo the exposed options form.
   */
  function expose_form_right(&$form, &$form_state) {
    if (empty($this->no_optional)) {
      $form['expose']['optional'] = array(
        '#type' => 'checkbox',
        '#title' => t('Optional'),
        '#description' => t('This exposed filter is optional and will have added options to allow it not to be set.'),
        '#default_value' => $this->options['expose']['optional'],
      );
    }
    else {
      $form['expose']['optional'] = array(
        '#type' => 'value',
        '#value' => FALSE,
      );
    }
    if (empty($this->no_single)) {
      $form['expose']['single'] = array(
        '#type' => 'checkbox',
        '#title' => t('Force single'),
        '#description' => t('Force this exposed filter to accept only one option.'),
        '#default_value' => $this->options['expose']['single'],
      );
    }
    $form['expose']['remember'] = array(
      '#type' => 'checkbox',
      '#title' => t('Remember'),
      '#description' => t('Remember the last setting the user gave this filter.'),
      '#default_value' => $this->options['expose']['remember'],
    );
  }

  /**
   * Validate the options form.
   */
  function expose_validate($form, &$form_state) {
    if (empty($this->options['expose']['identifier'])) {
      if (empty($form_state['values']['options']['expose']['identifier'])) {
        form_error($form['expose']['identifier'], t('The identifier is required if the filter is exposed.'));
      }
    }
    if (!empty($form_state['values']['options']['expose']['identifier']) && $form_state['values']['options']['expose']['identifier'] == 'value') {
      form_error($form['expose']['identifier'], t('This identifier is not allowed.'));
    }
    if (!$this->view->display_handler
      ->is_identifier_unique($form_state['id'], $form_state['values']['options']['expose']['identifier'])) {
      form_error($form['expose']['identifier'], t('This identifier is used by another handler.'));
    }
  }

  /**
   * Provide default options for exposed filters.
   */
  function expose_options() {
    $this->options['expose'] = array(
      'use_operator' => FALSE,
      'operator' => $this->options['id'] . '_op',
      'identifier' => $this->options['id'],
      'label' => $this
        ->ui_name(),
      'remember' => FALSE,
      'single' => TRUE,
      'optional' => TRUE,
    );
  }

  /**
   * Render our chunk of the exposed filter form when selecting
   *
   * You can override this if it doesn't do what you expect.
   */
  function exposed_form(&$form, &$form_state) {
    if (empty($this->options['exposed'])) {
      return;
    }

    // Build the exposed form, when its based on an operator.
    if (!empty($this->options['expose']['use_operator']) && !empty($this->options['expose']['operator'])) {
      $operator = $this->options['expose']['operator'];
      $this
        ->operator_form($form, $form_state);
      $form[$operator] = $form['operator'];
      if (isset($form[$operator]['#title'])) {
        unset($form[$operator]['#title']);
      }
      $this
        ->exposed_translate($form[$operator], 'operator');
      unset($form['operator']);
    }

    // Build the form and set the value based on the identifier.
    if (!empty($this->options['expose']['identifier'])) {
      $value = $this->options['expose']['identifier'];
      $this
        ->value_form($form, $form_state);
      $form[$value] = $form['value'];
      if (isset($form[$value]['#title']) && !empty($form[$value]['#type']) && $form[$value]['#type'] != 'checkbox') {
        unset($form[$value]['#title']);
      }
      $this
        ->exposed_translate($form[$value], 'value');
      if (!empty($form['#type']) && ($form['#type'] == 'checkboxes' || $form['#type'] == 'select' && !empty($form['#multiple']))) {
        unset($form[$value]['#default_value']);
      }
      if (!empty($form['#type']) && $form['#type'] == 'select' && empty($form['#multiple'])) {
        $form[$value]['#default_value'] = 'All';
      }
      if ($value != 'value') {
        unset($form['value']);
      }
    }
  }

  /**
   * Make some translations to a form item to make it more suitable to
   * exposing.
   */
  function exposed_translate(&$form, $type) {
    if (!isset($form['#type'])) {
      return;
    }
    if ($form['#type'] == 'radios') {
      $form['#type'] = 'select';
    }

    // Checkboxes don't work so well in exposed forms due to GET conversions.
    if ($form['#type'] == 'checkboxes') {
      if (empty($form['#no_convert']) || !empty($this->options['expose']['single'])) {
        $form['#type'] = 'select';
      }
      if (empty($this->options['expose']['single'])) {
        $form['#multiple'] = TRUE;
      }
    }
    if (!empty($this->options['expose']['single']) && isset($form['#multiple'])) {
      unset($form['#multiple']);
      $form['#size'] = NULL;
    }
    if ($type == 'value' && empty($this->no_optional) && !empty($this->options['expose']['optional']) && $form['#type'] == 'select' && empty($form['#multiple'])) {
      $any_label = variable_get('views_exposed_filter_any_label', 'old_any') == 'old_any' ? '<Any>' : t('- Any -');
      $form['#options'] = array(
        'All' => $any_label,
      ) + $form['#options'];
      $form['#default_value'] = 'All';
      if (empty($this->options['expose']['optional'])) {
        $form['#required'] = TRUE;
      }
    }
  }

  /**
   * Tell the renderer about our exposed form. This only needs to be
   * overridden for particularly complex forms. And maybe not even then.
   *
   * @return array|null
   *   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() {
    if (empty($this->options['exposed'])) {
      return;
    }
    return array(
      'operator' => $this->options['expose']['operator'],
      'value' => $this->options['expose']['identifier'],
      'label' => $this->options['expose']['label'],
    );
  }

  /**
   * Check to see if input from the exposed filters should change
   * the behavior of this filter.
   */
  function accept_exposed_input($input) {
    if (empty($this->options['exposed'])) {
      return TRUE;
    }
    if (!empty($this->options['expose']['use_operator']) && !empty($this->options['expose']['operator']) && isset($input[$this->options['expose']['operator']])) {
      $this->operator = $input[$this->options['expose']['operator']];
    }
    if (!empty($this->options['expose']['identifier'])) {
      $value = $input[$this->options['expose']['identifier']];

      // Various ways to check for the absence of optional input.
      if (!empty($this->options['expose']['optional'])) {
        if (($this->operator == 'empty' || $this->operator == 'not empty') && $value === '') {
          $value = ' ';
        }
        if ($this->operator != 'empty' && $this->operator != 'not empty') {
          if ($value == 'All' || $value === array()) {
            return FALSE;
          }
        }
        if (!empty($this->no_single) && $value === '') {
          return FALSE;
        }
      }
      if (isset($value)) {
        $this->value = $value;
        if (empty($this->no_single) && !empty($this->options['expose']['single'])) {
          $this->value = array(
            $value,
          );
        }
      }
      else {
        return FALSE;
      }
    }
    return TRUE;
  }
  function store_exposed_input($input, $status) {
    if (empty($this->options['exposed']) || empty($this->options['expose']['identifier'])) {
      return TRUE;
    }
    if (empty($this->options['expose']['remember'])) {
      return;
    }

    // Figure out which display id is responsible for the filters, so we
    // know where to look for session stored values.
    $display_id = $this->view->display_handler
      ->is_defaulted('filters') ? 'default' : $this->view->current_display;

    // shortcut test.
    $operator = !empty($this->options['expose']['use_operator']) && !empty($this->options['expose']['operator']);

    // false means that we got a setting that means to recuse ourselves,
    // so we should erase whatever happened to be there.
    if (!$status && isset($_SESSION['views'][$this->view->name][$display_id])) {
      $session =& $_SESSION['views'][$this->view->name][$display_id];
      if ($operator && isset($session[$this->options['expose']['operator']])) {
        unset($session[$this->options['expose']['operator']]);
      }
      if (isset($session[$this->options['expose']['identifier']])) {
        unset($session[$this->options['expose']['identifier']]);
      }
    }
    if ($status) {
      if (!isset($_SESSION['views'][$this->view->name][$display_id])) {
        $_SESSION['views'][$this->view->name][$display_id] = array();
      }
      $session =& $_SESSION['views'][$this->view->name][$display_id];
      if ($operator && isset($input[$this->options['expose']['operator']])) {
        $session[$this->options['expose']['operator']] = $input[$this->options['expose']['operator']];
      }
      $session[$this->options['expose']['identifier']] = $input[$this->options['expose']['identifier']];
    }
  }

  /**
   * Add this filter to the query.
   *
   * Due to the nature of fapi, the value and the operator have an unintended
   * level of indirection. You will find them in $this->operator
   * and $this->value respectively.
   */
  function query() {
    $this
      ->ensure_my_table();
    $this->query
      ->add_where($this->options['group'], "{$this->table_alias}.{$this->real_field} " . $this->operator . " '%s'", $this->value);
  }

  /**
   * Can this filter be used in OR groups?
   *
   * Some filters have complicated where clauses that cannot be easily used
   * with OR groups. Some filters must also use HAVING which also makes
   * them not groupable. These filters will end up in a special group
   * if OR grouping is in use.
   *
   * @return bool
   */
  function can_group() {
    return TRUE;
  }

}

Members

Namesort descending Modifiers Type Description Overrides
views_handler::$handler_type property The type of the handler, for example filter/footer/field.
views_handler::$query property Where the $query object will reside: 6
views_handler::$view property The top object of a view. Overrides views_object::$view
views_handler::access function Check whether current user has access to this handler. 6
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. 6
views_handler::ensure_my_table function Ensure the main table for this handler is in the query. This is used a lot. 8
views_handler::exposed_submit function Submit the exposed handler form
views_handler::exposed_validate function Validate the exposed handler form 4
views_handler::expose_form function Overridable form for exposed handler options.
views_handler::expose_submit function Perform any necessary changes to the form exposes prior to storage. There is no need for this function to actually store the data.
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_field function Shortcut to get a handler's raw field value.
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::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::pre_query function Run before the view is built. 1
views_handler::sanitize_value function Sanitize the value for output.
views_handler::set_relationship function Called just prior to query(), this lets a handler set up any relationship it needs.
views_handler::show_expose_button function Shortcut to display the expose/hide button.
views_handler::show_expose_form function Shortcut to display the exposed options form.
views_handler::ui_name function Return a string representing this handler's name in the UI. 10
views_handler::use_group_by function Provides the handler some groupby. 2
views_handler::validate function Validates the handler against the complete View. 1
views_handler_filter::$operator property Contains the operator which is used on the query.
views_handler_filter::$value property Contains the actual value of the field,either configured in the views ui or entered in the exposed filters.
views_handler_filter::accept_exposed_input function Check to see if input from the exposed filters should change the behavior of this filter. Overrides views_handler::accept_exposed_input 2
views_handler_filter::admin_summary function Display the filter on the administrative summary Overrides views_handler::admin_summary 9
views_handler_filter::can_expose function Determine if a filter can be exposed. Overrides views_handler::can_expose 3
views_handler_filter::can_group function Can this filter be used in OR groups? 2
views_handler_filter::exposed_form function Render our chunk of the exposed filter form when selecting Overrides views_handler::exposed_form 1
views_handler_filter::exposed_info function Tell the renderer about our exposed form. This only needs to be overridden for particularly complex forms. And maybe not even then. Overrides views_handler::exposed_info
views_handler_filter::exposed_translate function Make some translations to a form item to make it more suitable to exposing.
views_handler_filter::expose_form_left function Handle the 'left' side fo the exposed options form. Overrides views_handler::expose_form_left
views_handler_filter::expose_form_right function Handle the 'right' side fo the exposed options form. Overrides views_handler::expose_form_right 2
views_handler_filter::expose_options function Provide default options for exposed filters. Overrides views_handler::expose_options 2
views_handler_filter::expose_validate function Validate the options form. Overrides views_handler::expose_validate
views_handler_filter::init function Provide some extra help to get the operator/value easier to use. Overrides views_handler::init 1
views_handler_filter::operator_form function Provide a form for setting the operator. 6
views_handler_filter::operator_options function Provide a list of options for the default operator form. Should be overridden by classes that don't override operator_form 6
views_handler_filter::operator_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_filter::operator_validate function Validate the operator form.
views_handler_filter::options_form function Provide the basic form which calls through to subforms. If overridden, it is best to call through to the parent, or to at least make sure all of the functions in this form are called. Overrides views_handler::options_form 3
views_handler_filter::options_submit function Simple submit handler Overrides views_handler::options_submit
views_handler_filter::options_validate function Simple validate handler Overrides views_handler::options_validate 1
views_handler_filter::option_definition function Information about options for all kinds of purposes will be held here. Overrides views_handler::option_definition 6
views_handler_filter::query function Add this filter to the query. Overrides views_handler::query 11
views_handler_filter::show_operator_form function Shortcut to display the operator form.
views_handler_filter::show_value_form function Shortcut to display the value form.
views_handler_filter::store_exposed_input function If set to remember exposed input in the session, store it there. Overrides views_handler::store_exposed_input
views_handler_filter::value_form function Provide a form for setting options. 6
views_handler_filter::value_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_filter::value_validate function Validate the options form. 3
views_object::$definition property Handler's definition
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. 6
views_object::destroy function 2
views_object::export_option function 1
views_object::export_options function
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::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::unpack_translatable function Unpack a single option definition.
views_object::unpack_translatables function Unpacks each handler to store translatable texts.
views_object::_set_option_defaults function