class ctools_context_optional

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;
    }

}