class Messaging_Template in Messaging 7

Base template class

A template is a text object that has associated objects and can do token replacement.

These templates have some known parts: subject, header, content, footer

Hierarchy

• class \Messaging_Template

File

messaging_template/messaging_template.inc, line 92

Drupal Messaging Framework - Text filtering functions

class Messaging_Template {

  // Pre-built elements, needs to be built before render
  public $text = array();

  // Current template elements, renderable array
  public $elements;

  // Default format
  public $format = MESSAGING_FORMAT;

  // Parent element
  protected $parent;

  // Store multiple objects for token replacement
  protected $objects;

  // Options for string building and text replacement
  protected $options = array(
    'replace' => TRUE,
    'clear' => FALSE,
    'linebreak' => "\n",
  );

  // Tokens to add to all the template elements
  protected $tokens;

  /**
   * Add item of unknown type
   */
  function add_item($name, $value) {
    if (is_string($value)) {
      return $this
        ->add_string($name, $value);
    }
    elseif (is_object($value)) {
      return $this
        ->add_text($name, $value);
    }
    elseif (is_array($value)) {
      return $this
        ->add_element($name, $value);
    }
  }

  /**
   * Add element ready for drupal_render()
   */
  function add_element($name, $element) {
    $this->text[$name] = $element;
    return $this;
  }

  /**
   * Add string
   */
  function add_string($name, $string) {
    $element = array(
      '#markup' => $string,
    );
    return $this
      ->add_element($name, $element);
  }

  /**
   * Add text object
   */
  function add_text($name, $text) {
    $text
      ->set_parent($this);
    return $this
      ->add_element($name, $text);
  }

  /**
   * Set parent text
   */
  function set_parent($template) {
    $this->parent = $template;
    return $this;
  }

  /**
   * Reset built elements
   *
   * @param $part1, $part2...
   *   Optional parts to reset
   */
  public function reset() {
    $parts = func_get_args();
    if ($parts) {
      foreach ($parts as $key) {
        if (isset($this->elements[$key])) {
          unset($this->elements[$key]);
        }
      }
    }
    else {
      unset($this->elements);
    }
  }

  /**
   * Build all elements, return array
   *
   * @param $part1, $part2...
   *   Optional parts to render
   */
  public function build() {
    $parts = func_get_args();

    // If we don't have a list of parts we take known text parts
    $parts = $parts ? $parts : $this
      ->get_parts();

    // Build an array with each of the parts
    return $this
      ->build_parts($parts);
  }

  /**
   * Render elements, return string
   *
   * @param $part1, $part2...
   *   Optional parts to render
   */
  public function render() {
    $parts = func_get_args();

    // If we don't have a list of parts we take known text parts
    $parts = $parts ? $parts : $this
      ->get_parts();
    $build = $this
      ->build_parts($parts);
    return drupal_render($build);
  }

  /**
   * Build template parts
   */
  public function build_parts($parts) {
    $build = array();
    foreach ($parts as $key) {
      if (isset($this->elements[$key])) {

        // This one was already built
        $build[$key] = $this->elements[$key];
      }
      else {
        $build[$key] = $this
          ->build_element($key);
      }
    }
    return $build;
  }

  /**
   * Build a named element
   */
  public function build_element($name, $options = array()) {
    $text = $this
      ->get_text($name);
    $element = $text ? $this
      ->build_text($text) : array();
    $element += $this
      ->element_defaults($name);
    if (!empty($element['#parts'])) {

      // If the element has subparts, build them before the element
      $element += $this
        ->build_parts($element['#parts']);
    }
    return $this
      ->element_build($element);
  }

  /**
   * Build a message text element
   */
  protected function build_text($element, $options = array()) {
    if (is_object($element)) {
      return $element
        ->build();
    }
    elseif (is_string($element)) {
      return array(
        '#markup' => $element,
      );
    }
    elseif (is_array($element)) {
      return $element;
    }
    else {
      return array();
    }
  }

  /**
   * Build a message element with optional text replacement
   */
  protected function element_build($element, $options = array()) {
    foreach (element_children($element) as $key) {
      $element[$key] = $this
        ->build_text($element[$key], $options);
    }

    /*
    if (!empty($element['#tokens']) && (!isset($options['replace']) || $options['replace'])) {
      $element = $this->element_replace($element, $options);
    }
    */
    return $element;
  }

  /**
   * Perform token replace within an element
   */
  protected function element_replace($element, $options = array()) {
    foreach (array(
      '#markup',
      '#title',
      '#children',
      '#plaintext',
    ) as $key) {
      if (!empty($element[$key])) {
        $element[$key] = $this
          ->token_replace($element[$key]);
      }
    }
    foreach (element_children($element) as $key) {
      $element[$key] = $this
        ->element_replace($element[$key], $options);
    }
    return $element;
  }

  /*
   * Get defaults for elements
   */
  protected function element_defaults($name) {
    return array(
      '#format' => $this->format,
      '#method' => $this->method,
      '#options' => $this
        ->get_options(),
      '#template' => $this,
    );
  }

  /**
   * Get known template parts
   */
  protected function get_parts() {
    return array_keys($this->text);
  }

  /**
   * Add object to the list
   */
  function add_object($type, $object) {
    $this->objects[$type] = $object;
    return $this;
  }

  /**
   * Get objects from this template (include parent's ones)
   */
  function get_objects() {
    $objects = isset($this->objects) ? $this->objects : array();
    if (isset($this->parent)) {
      $objects += $this->parent
        ->get_objects();
    }
    return $objects;
  }

  /**
   * Get element from elements or default texts
   */
  function get_element($type, $options = array()) {
    if (isset($this->elements[$type])) {
      return $this->elements[$type];
    }
    else {
      return $this
        ->get_text($type, $options);
    }
  }

  /**
   * Get text element from this template
   */
  public function get_text($type, $options = array()) {
    if (isset($this->text[$type])) {
      return $this->text[$type];
    }
    else {
      $options += $this
        ->get_options();
      return $this
        ->default_text($type, $options);
    }
  }

  /**
   * Get options for texts, translations, etc
   */
  function get_options() {
    if (!isset($this->options)) {
      $this
        ->set_language(language_default());
    }
    return $this->options;
  }

  /**
   * Get tokens for templates
   */
  function get_tokens() {
    if (!isset($this->tokens)) {
      $this->tokens = array();

      // Use template options but don't clear tokens
      $options = $this
        ->get_options();
      $objects = $this
        ->get_objects();

      // Build token groups to optimize module calls
      $token_groups = array();
      foreach ($this
        ->token_list() as $token) {
        list($type, $name) = explode(':', $token);

        // Example $tokens['site']['name'] = 'site:name'
        $token_groups[$type][$name] = $token;

        // The token defaults to itself if it can't be replaced yet
        $this->tokens[$token] = '[' . $token . ']';
      }
      foreach ($token_groups as $type => $tokens) {
        $type_tokens = token_generate($type, $tokens, $objects, $options);
        $this->tokens = $type_tokens + $this->tokens;
      }
    }
    return $this->tokens;
  }

  /**
   * Set language
   */
  function set_language($language) {
    $this
      ->set_option('language', $language);
    $this
      ->set_option('langcode', $language->language);
    $this
      ->reset();
    return $this;
  }

  /**
   * Set options
   */
  function set_option($name, $value = TRUE) {
    $this->options[$name] = $value;
    return $this;
  }

  /**
   * Set array of options
   */
  function set_options($options = array()) {
    $this->options = array_merge($this->options, $options);
    return $this;
  }

  /**
   * Do token replacement with this template's objects
   */
  public function token_replace($text, $options = array()) {
    return token_replace($text, $this
      ->get_objects(), $options + $this
      ->get_options());
  }

  /**
   * Get default elements
   */
  protected function default_elements() {
    return array();
  }

  /**
   * Default texts for this template, may need token replacement
   */
  protected function default_text($type, $options) {

    // Text not found, something went wrong with our template processing
    return t('Template text not found: @type.', array(
      '@type' => $type,
    ), $options);
  }

  /**
   * Tokens for this template. Will be stored
   */
  protected function token_list() {
    return array(
      'site:name',
      'site:url',
    );
  }

}

Members

Name	Modifiers	Type	Description	Overrides
Messaging_Template::$elements	public	property
Messaging_Template::$format	public	property
Messaging_Template::$objects	protected	property
Messaging_Template::$options	protected	property
Messaging_Template::$parent	protected	property
Messaging_Template::$text	public	property
Messaging_Template::$tokens	protected	property
Messaging_Template::add_element		function	Add element ready for drupal_render()
Messaging_Template::add_item		function	Add item of unknown type
Messaging_Template::add_object		function	Add object to the list
Messaging_Template::add_string		function	Add string
Messaging_Template::add_text		function	Add text object
Messaging_Template::build	public	function	Build all elements, return array
Messaging_Template::build_element	public	function	Build a named element
Messaging_Template::build_parts	public	function	Build template parts
Messaging_Template::build_text	protected	function	Build a message text element
Messaging_Template::default_elements	protected	function	Get default elements
Messaging_Template::default_text	protected	function	Default texts for this template, may need token replacement	1
Messaging_Template::element_build	protected	function	Build a message element with optional text replacement
Messaging_Template::element_defaults	protected	function		1
Messaging_Template::element_replace	protected	function	Perform token replace within an element
Messaging_Template::get_element		function	Get element from elements or default texts
Messaging_Template::get_objects		function	Get objects from this template (include parent's ones)
Messaging_Template::get_options		function	Get options for texts, translations, etc
Messaging_Template::get_parts	protected	function	Get known template parts	1
Messaging_Template::get_text	public	function	Get text element from this template
Messaging_Template::get_tokens		function	Get tokens for templates
Messaging_Template::render	public	function	Render elements, return string
Messaging_Template::reset	public	function	Reset built elements
Messaging_Template::set_language		function	Set language
Messaging_Template::set_option		function	Set options
Messaging_Template::set_options		function	Set array of options
Messaging_Template::set_parent		function	Set parent text
Messaging_Template::token_list	protected	function	Tokens for this template. Will be stored
Messaging_Template::token_replace	public	function	Do token replacement with this template's objects