class ctools_context_optional

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

Hierarchy

Expanded class hierarchy of ctools_context_optional

File

includes/context.inc, line 401

View source
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

Title Sort descending Modifiers Object type Summary Overriden Title
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.