class ctools_context_optional in Chaos Tool Suite (ctools) 7

Used to compare to see if a list of contexts match an optional context. This can produce empty contexts to use as placeholders.

Hierarchy

• class \ctools_context_required
  • class \ctools_context_optional

File

includes/context.inc, line 389

Contains code related to the ctools system of 'context'.

class ctools_context_optional extends ctools_context_required {

  /**
   * {@inheritdoc}
   */
  public $required = FALSE;

  /**
   * Add the 'empty' context to the existing set.
   *
   * @param array &$contexts
   *   An array of ctools_context objects.
   */
  public function add_empty(&$contexts) {
    $context = new ctools_context('any');
    $context->title = t('No context');
    $context->identifier = t('No context');
    $contexts['empty'] = $context;
  }

  /**
   * Filter the contexts to determine which apply in the current environment.
   *
   * As for ctools_context_required, but we add the empty context to those
   * passed in so the check is optional (i.e. if nothing else matches, the
   * empty context will, and so there will always be at least one matched).
   *
   * @param array $contexts
   *   An array of ctools_context objects (or something which will cast to an
   *   array of them). The contexts to apply the filter on.
   *
   * @return array
   *   An array of context objects, keyed with the same keys used for $contexts,
   *   which pass the filter.
   *
   * @see ctools_context::is_type()
   */
  public function filter($contexts) {

    /**
     * @todo We are assuming here that $contexts is actually an array, whereas
     * ctools_context_required::filter only requires $contexts is convertible
     * to an array.
     */
    $this
      ->add_empty($contexts);
    return parent::filter($contexts);
  }

  /**
   * Select and return one context from the list of applicable contexts.
   *
   * Fundamentally, this returns $contexts[$context] or the empty context if
   * that does not exist.
   *
   * @param array $contexts
   *   The applicable contexts to check.
   * @param string $context
   *   The context id to check for.
   *
   * @return bool|ctools_context
   *   The matching ctools_context, or False if no such context was found.
   *
   * @see ctools_context_required::select()
   */
  public function select($contexts, $context) {

    /**
     * @todo We are assuming here that $contexts is actually an array, whereas
     * ctools_context_required::select permits ctools_context objects as well.
     */
    $this
      ->add_empty($contexts);
    if (empty($context)) {
      return $contexts['empty'];
    }
    $result = parent::select($contexts, $context);

    // Don't flip out if it can't find the context; this is optional, put
    // in an empty.
    if ($result === FALSE) {
      $result = $contexts['empty'];
    }
    return $result;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
ctools_context_optional::$required	public	property	Test to see if this context is required. Overrides ctools_context_required::$required
ctools_context_optional::add_empty	public	function	Add the 'empty' context to the existing set.
ctools_context_optional::filter	public	function	Filter the contexts to determine which apply in the current environment. Overrides ctools_context_required::filter
ctools_context_optional::select	public	function	Select and return one context from the list of applicable contexts. Overrides ctools_context_required::select
ctools_context_required::$keywords	public	property	Keyword strings associated with the context.
ctools_context_required::$skip_name_check	public	property	If TRUE, skip the check in ctools_context_required::select() for contexts whose names may have changed.
ctools_context_required::$title	public	property	If set, the title will be used in the selector to identify the context. This is very useful when multiple contexts are required to inform the user will be used for what.
ctools_context_required::__construct	public	function	The ctools_context_required constructor.