views/template.php

   1 <?php
   2 // Hoplite
   3 // Copyright (c) 2011 Blue Static
   4 //
   5 // This program is free software: you can redistribute it and/or modify it
   6 // under the terms of the GNU General Public License as published by the Free
   7 // Software Foundation, either version 3 of the License, or any later version.
   8 //
   9 // This program is distributed in the hope that it will be useful, but WITHOUT
  10 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  12 // more details.
  13 //
  14 // You should have received a copy of the GNU General Public License along with
  15 // this program.  If not, see <http://www.gnu.org/licenses/>.
  16
  17 namespace hoplite\views;
  18
  19 require_once HOPLITE_ROOT . '/base/filter.php';
  20
  21 /*!
  22  A Template is initialized with a text file (typically HTML) and can render it
  23  with data from some model. It has a short macro expansion system, equivalent
  24  to PHP short open tags, but usable on all installations. Template caching of
  25  the parsed state is available.
  26 */
  27 class Template
  28 {
  29   /*! @var string The name of the template. */
  30   protected $template_name = '';
  31
  32   /*! @var string The compiled template. */
  33   protected $data = NULL;
  34
  35   /*! @var array Variables to provide to the template. */
  36   protected $vars = array();
  37
  38   /*!
  39     Creates a new Template with a given name.
  40     @param string
  41   */
  42   private function __construct($name)
  43   {
  44     $this->template_name = $name;
  45   }
  46
  47   static public function NewWithData($data)
  48   {
  49     $template = new Template('');
  50     $template->data = $template->_ProcessTemplate($data);
  51     return $template;
  52   }
  53
  54   static public function NewFromCompiledData($data)
  55   {
  56     $template = new Template('');
  57     $template->data = $data;
  58     return $template;
  59   }
  60
  61   /*! Gets the name of the template. */
  62   public function template_name() { return $this->template_name; }
  63
  64   /*! Gets the parsed data of the template. */
  65   public function template() { return $this->data; }
  66
  67   /*! Overload property accessors to set view variables. */
  68   public function __get($key)
  69   {
  70     return $this->vars[$key];
  71   }
  72   public function __set($key, $value)
  73   {
  74     $this->vars[$key] = $value;
  75   }
  76
  77   /*! This includes the template and renders it out. */
  78   public function Render()
  79   {
  80     $_template = $this->data;
  81     $_vars = $this->vars;
  82     $render = function () use ($_template, $_vars) {
  83       extract($_vars);
  84       eval('?>' . $_template . '<' . '?');
  85     };
  86     $render();
  87   }
  88
  89   /*! @brief Does any pre-processing on the template.
  90     This performs the macro expansion. The language is very simple and is merely
  91     shorthand for the PHP tags.
  92
  93     The most common thing needed in templates is string escaped output from an
  94     expression. HTML entities are automatically escaped in this format:
  95       <p>Hello, {% $user->name %}!</p>
  96
  97     To specify the type to format, you use the pipe symbol and then one of the
  98     following types: str (default; above), int, float, raw.
  99       <p>Hello, {% %user->name | str %}</p>
 100       <p>Hello, user #{% $user->user_id | int %}</p>
 101
 102     To evaluate a non-printing expression, simply add a '!' before the first '%':
 103       {!% if (!$user->user_id): %}<p>Hello, Guest!</p>{!% endif %}
 104
 105     @param string Raw template data
 106     @return string Executable PHP
 107   */
 108   protected function _ProcessTemplate($data)
 109   {
 110     // The parsed output as compiled PHP.
 111     $processed = '';
 112
 113     // If processing a macro, this contains the contents of the macro while
 114     // it is being extracted from the template.
 115     $macro = '';
 116     $in_macro = FALSE;
 117
 118     $length = strlen($data);
 119     $i = 0;  // The current position of the iterator.
 120     $looking_for_end = FALSE;  // Whehter or not an end tag is expected.
 121     $line_number = 1;  // The current line number.
 122     $i_last_line = 0;  // The value of |i| at the previous new line, used for column numbering.
 123
 124     while ($i < $length) {
 125       // See how far the current position is from the end of the string.
 126       $delta = $length - $i;
 127
 128       // When a new line is reached, update the counters.
 129       if ($data[$i] == "\n") {
 130         ++$line_number;
 131         $i_last_line = $i;
 132       }
 133
 134       // Check for simple PHP short-tag expansion.
 135       if ($delta >= 3 && substr($data, $i, 3) == '{!%') {
 136         // If an expansion has already been opened, then it's an error to nest.
 137         if ($looking_for_end) {
 138           $column = $i - $i_last_line;
 139           throw new TemplateException("Unexpected start of expansion at line $line_number:$column");
 140         }
 141
 142         $looking_for_end = TRUE;
 143         $processed .= '<' . '?php';
 144         $i += 3;
 145         continue;
 146       }
 147       // Check for either the end tag or the start of a macro expansion.
 148       else if ($delta >= 2) {
 149         $substr = substr($data, $i, 2);
 150         // Check for an end tag.
 151         if ($substr == '%}') {
 152           // If an end tag was encountered without an open tag, that's an error.
 153           if (!$looking_for_end) {
 154             $column = $i - $i_last_line;
 155             throw new TemplateException("Unexpected end of expansion at line $line_number:$column");
 156           }
 157
 158           // If this is a macro, it's time to process it.
 159           if ($in_macro)
 160             $processed .= $this->_ProcessMacro($macro);
 161
 162           $looking_for_end = FALSE;
 163           $in_macro = FALSE;
 164           $processed .= ' ?>';
 165           $i += 2;
 166           continue;
 167         }
 168         // Check for the beginning of a macro.
 169         else if ($substr == '{%') {
 170           // If an expansion has already been opened, then it's an error to nest.
 171           if ($looking_for_end) {
 172             $column = $i - $i_last_line;
 173             throw new TemplateException("Unexpected start of expansion at line $line_number:$column");
 174           }
 175
 176           $processed .= '<' . '?php echo ';
 177           $macro = '';
 178           $in_macro = TRUE;
 179           $looking_for_end = TRUE;
 180           $i += 2;
 181           continue;
 182         }
 183       }
 184
 185       // All other characters go into a storage bin. If currently in a macro,
 186       // save off the data separately for parsing.
 187       if ($in_macro)
 188         $macro .= $data[$i];
 189       else
 190         $processed .= $data[$i];
 191       ++$i;
 192     }
 193
 194     return $processed;
 195   }
 196
 197   /*!
 198     Takes the contents of a macro |{% $some_var | int %}|, which is the part in
 199     between the open and close brackets (excluding '%') and transforms it into a
 200     PHP statement.
 201   */
 202   protected function _ProcessMacro($macro)
 203   {
 204     // The pipe operator specifies how to sanitize the output.
 205     $formatter_pos = strrpos($macro, '|');
 206
 207     // No specifier defaults to escaped string.
 208     if ($formatter_pos === FALSE)
 209       return 'hoplite\\base\\filter\\String(' . $macro . ')';
 210
 211     // Otherwise, apply the right filter.
 212     $formatter = trim(substr($macro, $formatter_pos + 1));
 213     $function = '';
 214     switch (strtolower($formatter)) {
 215       case 'int':   $function = 'Int'; break;
 216       case 'float': $function = 'Float'; break;
 217       case 'str':   $function = 'String'; break;
 218       case 'raw':   $function = 'RawString'; break;
 219       default:
 220         throw new TemplateException('Invalid macro formatter "' . $formatter . '"');
 221     }
 222
 223     // Now get the expression and return a PHP statement.
 224     $expression = trim(substr($macro, 0, $formatter_pos));
 225     return 'hoplite\\base\\filter\\' . $function . '(' . $expression . ')';
 226   }
 227 }
 228
 229 class TemplateException extends \Exception {}