abstract class boxes_box in Boxes 7

Abstract base class defining a box. A boxes content plugin provides a form of options for configuring content and renders content for display.

Hierarchy

• class \boxes_box

See also

boxes_simple

1 string reference to 'boxes_box'

boxes_boxes_plugins in ./boxes.module

Implements hook_boxes_plugins().

File

plugins/boxes_box.inc, line 9

abstract class boxes_box {
  static $boxes;

  // Static cache of box objects.
  public $delta;
  public $title;
  public $description;
  public $options;
  public $plugin_key;
  public $new;
  public $export_type;

  /**
   * Load existing box by its unique identifier $delta.
   */
  public static function load($delta, $reset = FALSE) {
    if (!isset(self::$boxes[$delta]) || $reset) {
      ctools_include('export');
      $box = ctools_export_load_object('box', 'names', array(
        $delta,
      ));
      if (!empty($box) && ($values = array_pop($box))) {
        self::$boxes[$delta] = self::factory($values->plugin_key, $values);
        self::$boxes[$delta]->new = FALSE;
      }
    }
    return isset(self::$boxes[$delta]) && get_class(self::$boxes[$delta]) != 'stdClass' ? self::$boxes[$delta] : NULL;
  }

  /**
   * Instantiate, populate and return a box object.
   *
   * @param $plugin_key
   *
   * @param $values
   *   An array with at least a plugin_key key identifying the plugin class to
   *   use for instantiating this box.
   */
  public static function factory($plugin_key, $values) {
    ctools_include('plugins');
    if ($class = ctools_plugin_load_class('boxes', 'plugins', $plugin_key, 'handler')) {

      // While we actually prefer to get objects, we need to allow for either,
      // so we convert it all to arrays.
      if (is_object($values)) {
        $values = (array) $values;
      }
      $box = new $class();
      $box->plugin_key = $plugin_key;
      foreach ($box as $key => $value) {
        if (isset($values[$key])) {
          $box->{$key} = $values[$key];
        }
      }
      foreach ($box
        ->options_defaults() as $key => $value) {
        if (isset($values[$key])) {
          $box->options[$key] = $values[$key];
        }
      }
      return $box;
    }
    return FALSE;
  }

  /**
   * Create a new box.
   */
  protected function __construct() {
    $this->new = TRUE;

    // A box is new unless it exists in the DB or in code.
    $this->options = $this
      ->options_defaults();
  }

  /**
   * Reset the boxes cache.
   *
   * Both ctools and boxes current maintain caches, ctools of the config and
   * boxes of the loaded box objects. We clear them both.
   */
  public static function reset() {
    ctools_include('export');
    ctools_export_load_object_reset('box');
    self::$boxes = array();
  }

  /**
   * Save a box.
   */
  public function save() {
    if (empty($this->delta)) {
      throw new Exception(t('Cannot save box without a specified delta.'));
    }
    self::reset();
    $existing = boxes_box_load($this->delta);
    if ($existing && $existing->export_type & EXPORT_IN_DATABASE) {
      drupal_write_record('box', $this, array(
        'delta',
      ));
    }
    else {
      drupal_write_record('box', $this);
    }
    $this->new = FALSE;
    self::reset();
    module_exists('context') ? context_invalidate_cache() : NULL;
  }

  /**
   * Delete a box.
   */
  public function delete() {
    self::reset();
    unset(self::$boxes[$this->delta]);
    db_delete('box')
      ->condition('delta', $this->delta)
      ->execute();
    module_exists('context') ? context_invalidate_cache() : NULL;
  }

  /**
   * Declare if the box should use a multistep form for the create form.
   *
   * This might me necessary for forms that use ajax on the options form.
   * Currently Context does not load this block correctly and the ajax in the
   * form will not work. Methinks Context UI Editor needs to be upgraded to
   * D7 AJAX framework for this to not be required. That said the functionality
   * is potentially useful even with proper functioning AJAX.
   */
  public function use_multistep_create() {
    return FALSE;
  }

  /**
   * Returns the block cache settings for this box. Subclasses can override this
   * to perform more intricate operations around deciding the cache settings of
   * the specific box instance.
   */
  public function cache_setting() {
    return DRUPAL_CACHE_CUSTOM;
  }

  /**
   * Declare default options.
   */
  public abstract function options_defaults();

  /**
   * Provide options to configure content.
   */
  public abstract function options_form(&$form_state);

  /**
   * Render a block. Must return an array with the keys
   * 'delta', 'title', 'subject' (same as title) and 'content'.
   *
   * title AND subject need to be present to avoid that block module overrides
   * title.
   */
  public abstract function render();

}

Members

Name	Modifiers	Type	Description	Overrides
boxes_box::$boxes	static	property
boxes_box::$delta	public	property
boxes_box::$description	public	property
boxes_box::$export_type	public	property
boxes_box::$new	public	property
boxes_box::$options	public	property
boxes_box::$plugin_key	public	property
boxes_box::$title	public	property
boxes_box::cache_setting	public	function	Returns the block cache settings for this box. Subclasses can override this to perform more intricate operations around deciding the cache settings of the specific box instance.
boxes_box::delete	public	function	Delete a box.
boxes_box::factory	public static	function	Instantiate, populate and return a box object.
boxes_box::load	public static	function	Load existing box by its unique identifier $delta.
boxes_box::options_defaults	abstract public	function	Declare default options.	1
boxes_box::options_form	abstract public	function	Provide options to configure content.	1
boxes_box::render	abstract public	function	Render a block. Must return an array with the keys 'delta', 'title', 'subject' (same as title) and 'content'.	1
boxes_box::reset	public static	function	Reset the boxes cache.
boxes_box::save	public	function	Save a box.
boxes_box::use_multistep_create	public	function	Declare if the box should use a multistep form for the create form.
boxes_box::__construct	protected	function	Create a new box.