Smarty-2.6.2/FAQ

   1 QUESTION INDEX
   2 --------------
   3
   4 GENERAL
   5
   6 Q: What is Smarty?
   7 Q: What's the difference between Smarty and other template engines?
   8 Q: What do you mean "Compiled PHP Scripts" ?
   9 Q: Why can't I just use PHPA (http://php-accelerator.co.uk) or Zend Cache?
  10 Q: Why does smarty have a built in cache? Wouldn't it be better to handle this
  11    in a separate class?
  12 Q: Is Smarty faster than <insert other PHP template engine>?
  13 Q: How can I be sure to get the best performance from Smarty?
  14 Q: Do you have a mailing list?
  15 Q: Can you change the mailing list so reply-to sends to the list and not the
  16    user?
  17
  18 TROUBLESHOOTING
  19
  20 Q: Smarty doesn't work.
  21 Q: I get the following error when running Smarty:
  22    Warning:  Smarty error: problem creating directory "templates_c/239/239105369"
  23    in /path/to/Smarty.class.php on line 542
  24 Q: I get the following error when running Smarty:
  25    Warning: Wrong parameter count for preg_replace() in
  26    Smarty.class.php on line 371
  27 Q: I get this error when passing variables to {include}:
  28    Fatal error: Call to undefined function: get_defined_vars() in
  29    /path/to/Smarty/templates_c/index.tpl.php on line 8
  30 Q: I get PHP errors in my {if} tag logic.
  31 Q: I'm changing my php code and/or templates, and my results are not getting
  32    updated.
  33 Q: I'm running Windows 2000 and I get blank content. My compiled PHP files are
  34    also zero length.
  35 Q: The template goes into an infinite loop when I include included templates
  36    that pass local variables
  37 Q: Javascript is causing Smarty errors in my templates.
  38 Q: I get "SAFE MODE Restriction in effect. ..."-errors when running smarty.
  39
  40 MISC
  41
  42 Q: Can I use Macromedia's Dreamweaver to edit my templates?
  43 Q: Dreamweaver is urlencoding the template delimiters when they are in a SRC or
  44    HREF link. How do I get around this?
  45
  46 HOWTO
  47
  48 Q: How do I generate different cache files per template based on arguments
  49    passed to the page?
  50 Q: How do I pass a template variable as a parameter? {function param={$varname}}
  51    does not work.
  52 Q: How do I include cached template(s) within a non-cached template?
  53
  54
  55 GENERAL
  56 -------
  57
  58 Q: What is Smarty?
  59 A: Smarty is a template engine for PHP... but be aware this isn't just another
  60    PHP template engine. It's much more than that.
  61
  62 Q: What's the difference between Smarty and other template engines?
  63 A: Most other template engines for PHP provide basic variable substitution and
  64    dynamic block functionality. Smarty takes a step further to be a "smart"
  65    template engine, adding features such as configuration files, template
  66    functions, variable modifiers (see the docs!) and making all of this
  67    functionality as easy as possible to use for both programmers and template
  68    designers. Smarty also compiles the templates into PHP scripts, eliminating
  69    the need to parse the templates on every invocation, making Smarty extremely
  70    scalable and manageable for large application needs.
  71
  72 Q: What do you mean "Compiled PHP Scripts" ?
  73 A: Smarty reads the template files and creates PHP scripts from them. Once
  74    these PHP scripts are created, Smarty executes these, never having to parse
  75    the template files again. If you change a template file, Smarty will
  76    recreate the PHP script for it. All this is done automatically by Smarty.
  77    Template designers never need to mess with the generated PHP scripts or even
  78    know of their existance. (NOTE: you can turn off this compile checking step
  79    in Smarty for increased performance.)
  80
  81 Q: Why can't I just use PHPA (http://php-accelerator.co.uk) or Zend Cache?
  82 A: You certainly can, and we highly recommend it! What PHPA does is caches
  83    compiled bytecode of your PHP scripts in shared memory or in a file. This
  84    speeds up server response and saves the compilation step. Smarty creates PHP
  85    scripts, which PHPA will cache nicely. Now, Smarty's built-in cache is
  86    something completely different. It caches the _output_ of the template
  87    contents. For example, if you have a template that requires several database
  88    queries, Smarty can cache this output, saving the need to call the database
  89    every time. Smarty and PHPA (or Zend Cache) complement each other nicely. If
  90    performance is of the utmost importance, we would recommend using one of
  91    these with any PHP application, using Smarty or not. As you can see in the
  92    benchmarks, Smartys performance _really_ excels in combination with a PHP
  93    accelerator.
  94
  95 Q: Why does Smarty have a built in cache? Wouldn't it be better to handle this
  96    in a separate class?
  97 A: Smarty's caching functionality is tightly integrated with the template
  98    engine, making it quite a bit more flexible than a simple caching wrapper.
  99    For instance, you can cache select portions of a template page. Let's say
 100    you have a polling box on your site. With Smarty, you can leave the poll
 101    dynamic and cache the rest of the page. You can also pass templates
 102    multiple cache ids, meaning that a template can have several caches
 103    depending on URL, cookies, etc.
 104
 105 Q: Is Smarty faster than <insert other PHP template engine>?
 106 A: See the benchmark page for some performance comparisons. Smarty's approach
 107    to templates is a bit different from some languages: it compiles templates
 108    into PHP scripts instead of parsing them on each invocation. This usually
 109    results in great performance gains, especially with complex templates.
 110    Coupled with the built-in caching of Smarty templates, the performance is
 111    outstanding.
 112
 113 Q: How can I be sure to get the best performance from Smarty?
 114 A: Be sure you set $compile_check=false once your templates are initially
 115    compiled. This will skip the unneeded step of testing if the template has
 116    changed since it was last compiled. If you have complex pages that don't
 117    change too often, turn on the caching engine and adjust your application so
 118    it doesn't do unnecessary work (like db calls) if a cached page is
 119    available. See the documentation for examples.
 120
 121 Q: Do you have a mailing list?
 122 A:  We have a few mailing lists. "general" for you to share your ideas or ask
 123         questions, "dev" for those interested in the development efforts of Smarty,
 124         and "cvs" for those that would like to track the updates made in the cvs
 125         repository.
 126
 127     send a blank e-mail message to:
 128       smarty-general-subscribe@lists.php.net (subscribe to the general list)
 129       smarty-general-unsubscribe@lists.php.net (unsubscribe from the general list)
 130       smarty-general-digest-subscribe@lists.php.net (subscribe to digest)
 131       smarty-general-digest-unsubscribe@lists.php.net (unsubscribe from digest)
 132       smarty-dev-subscribe@lists.php.net (subscribe to the dev list)
 133       smarty-dev-unsubscribe@lists.php.net (unsubscribe from the dev list)
 134       smarty-cvs-subscribe@lists.php.net (subscribe to the cvs list)
 135       smarty-cvs-unsubscribe@lists.php.net (unsubscribe from the cvs list)
 136     You can also browse the mailing list archives at
 137     http://marc.theaimsgroup.com/?l=smarty&r=1&w=2
 138
 139
 140
 141 Q: Can you change the mailing list so Reply-To sends to the list and not the
 142    user?
 143 A: Yes we could, but no we won't. Use "Reply-All" in your e-mail client to send
 144    to the list. http://www.unicom.com/pw/reply-to-harmful.html
 145
 146 TROUBLESHOOTING
 147 ---------------
 148
 149 Q: Smarty doesn't work.
 150 A: You must be using PHP 4.0.6 or later if you use any version of Smarty
 151    past 2.0.1. Read the BUGS file for more info.
 152
 153 Q: I get the following error when running Smarty:
 154    Warning:  Smarty error: problem creating directory "templates_c/239/239105369"
 155    in /path/to/Smarty.class.php on line 542
 156 A: Your web server user does not have permission to write to the templates_c
 157    directory, or is unable to create the templates_c directory. Be sure the
 158    templates_c directory exists in the location defined in Smarty.class.php,
 159    and the web server user can write to it. If you do not know the web server
 160    user, chmod 777 the templates_c directory, reload the page, then check the
 161    file ownership of the files created in templates_c. Or, you can check the
 162    httpd.conf (usually in /usr/local/apache/conf) file for this setting:
 163    User nobody
 164    Group nobody
 165
 166 Q: I get the following error when running Smarty: Warning: Wrong parameter
 167    count for preg_replace() in Smarty.class.php on line 371
 168 A: preg_replace had a parameter added in PHP 4.0.2 that Smarty
 169    requires. Upgrade to at least 4.0.6 to fix all known PHP issues with
 170    Smarty.
 171
 172 Q: I get this error when passing variables to {include}:
 173    Fatal error: Call to undefined function: get_defined_vars() in
 174    /path/to/Smarty/templates_c/index.tpl.php on line 8
 175 A: get_defined_vars() was added to PHP 4.0.4. If you plan on passing
 176    variables to included templates, you will need PHP 4.0.6 or later.
 177
 178 Q: I get PHP errors in my {if} tag logic.
 179 A: All conditional qualifiers must be separated by spaces. This syntax will not
 180    work: {if $name=="Wilma"} You must instead do this: {if $name == "Wilma"}.
 181    The reason for this is syntax ambiguity. Both "==" and "eq" are equivalent
 182    in the template parser, so something like {if $nameeq"Wilma"} wouldn't be
 183    parsable by the tokenizer.
 184
 185 Q: I'm changing my php code and/or templates, and my results are not getting
 186    updated.
 187 A: This may be the result of your compile or cache settings. If you are
 188    changing your php code, your templates will not necessarily get recompiled
 189    to reflect the changes. Use $force_compile during develpment to avoid these
 190    situations. Also turn off caching during development when you aren't
 191    specifically testing it. You can also remove everything from your
 192    compile_dir and cache_dir and reload the page to be sure everything gets
 193    regenerated.
 194
 195 Q: I'm running Windows 2000 and I get blank content. My compiled PHP files are
 196    also zero length.
 197 A: There seems to be a problem with some W2k machines and exclusive file
 198    locking. Comment out the flock() call in _write_file to get around this,
 199    although be aware this could possibly cause a problem with simultaneous
 200    writes to a file, especially with caching turned on. NOTE: As of Smarty
 201    1.4.0, a workaround was put in place that should solve this.
 202
 203 Q: The template goes into an infinite loop when I include included templates
 204    that pass local variables
 205 A: This was fixed in 1.3.2 (new global attribute)
 206
 207 Q: Javascript is causing Smarty errors in my templates.
 208 A: Surround your javascript with {literal}{/literal} tags. See the docs.
 209
 210 Q: I get "SAFE MODE Restriction in effect. ..."-errors when running smarty.
 211 A: Use $smarty->use_sub_dirs = false when running php in safe mode.
 212
 213 MISC
 214 ----
 215
 216 Q: Can I use Macromedia's Dreamweaver to edit my templates?
 217 A: Certainly. You might want to change your tag delimiters from {} to something
 218    that resembles valid HTML, like <!--{ }--> or <{ }> or something similar.
 219    This way the editor won't view the template tags as errors.
 220
 221 Q: Dreamweaver is urlencoding the template delimiters when they are in a SRC or
 222    HREF link. How do I get around this?
 223 A: In Edit - Properties - Rewrite HTML you can specify if Dreamweaver should
 224    change special letters to %-equivalent or not. The default is on which
 225    produces this error.
 226
 227 HOWTO
 228 -----
 229
 230 Q: How do I generate different cache files per template based on arguments
 231    passed to the page?
 232 A: Use your $REQUEST_URI as the cache_id when fetching the page:
 233
 234    global $REQUEST_URI; // if not already present
 235    $smarty->display('index.tpl',$REQUEST_URI);
 236
 237    This will create a separate cache file for each unique URL when you call
 238    index.tpl. See the documentation for display() and fetch()
 239
 240 Q: How do I pass a template variable as a parameter? {function param={$varname}}
 241    does not work.
 242 A: {function param=$varname} (You cannot nest template delimiters.)
 243
 244 Q: How do I include cached template(s) within a non-cached template?
 245 A: One way to do it:
 246
 247    $smarty->caching = true;
 248    $tpl1 = $smarty->fetch("internal1.tpl");
 249    $tpl2 = $smarty->fetch("internal2.tpl");
 250    $tpl3 = $smarty->fetch("internal3.tpl");
 251
 252    $smarty->assign("tpl1_contents",$tpl1);
 253    $smarty->assign("tpl2_contents",$tpl2);
 254    $smarty->assign("tpl3_contents",$tpl3);
 255
 256    $smarty->caching = false;
 257    $smarty->display('index.tpl');
 258
 259    index.tpl
 260    ---------
 261
 262    <table>
 263            <tr>
 264                    <td>{$tpl1_contents}</td>
 265                    <td>{$tpl2_contents}</td>
 266                    <td>{$tpl3_contents}</td>
 267            </tr>
 268    </table>
 269
 270
 271
 272
 273    Another approach:
 274
 275    You could write a custom insert function to fetch your internal
 276    templates:
 277
 278    <table>
 279            <tr>
 280                    <td>{insert name=fetch_tpl tpl="internal1.tpl"}</td>
 281                    <td>{insert name=fetch_tpl tpl="internal2.tpl"}</td>
 282                    <td>{insert name=fetch_tpl tpl="internal3.tpl"}</td>
 283            </tr>
 284    </table>