library/smarty/SMARTY_2_BC_NOTES.txt
changeset 0 4869aea77e21
equal deleted inserted replaced
-1:000000000000 0:4869aea77e21
       
     1 = Known incompatibilities with Smarty 2 =
       
     2 
       
     3 == Syntax ==
       
     4 
       
     5 Smarty 3 API has a new syntax. Much of the Smarty 2 syntax is supported 
       
     6 by a wrapper but deprecated. See the README that comes with Smarty 3 for more 
       
     7 information.
       
     8 
       
     9 The {$array|@mod} syntax has always been a bit confusing, where an "@" is required
       
    10 to apply a modifier to an array instead of the individual elements. Normally you
       
    11 always want the modifier to apply to the variable regardless of its type. In Smarty 3,
       
    12 {$array|mod} and {$array|@mod} behave identical. It is safe to drop the "@" and the
       
    13 modifier will still apply to the array. If you really want the modifier to apply to
       
    14 each array element, you must loop the array in-template, or use a custom modifier that
       
    15 supports array iteration. Most smarty functions already escape values where necessary
       
    16 such as {html_options}
       
    17 
       
    18 == PHP Version ==
       
    19 Smarty 3 is PHP 5 only. It will not work with PHP 4.
       
    20 
       
    21 == {php} Tag ==
       
    22 The {php} tag is disabled by default. The use of {php} tags is
       
    23 deprecated. It can be enabled with $smarty->allow_php_tag=true.
       
    24 
       
    25 But if you scatter PHP code which belongs together into several
       
    26 {php} tags it may not work any longer.
       
    27 
       
    28 == Delimiters and whitespace ==
       
    29 Delimiters surrounded by whitespace are no longer treated as Smarty tags.
       
    30 Therefore, { foo } will not compile as a tag, you must use {foo}. This change
       
    31 Makes Javascript/CSS easier to work with, eliminating the need for {literal}.
       
    32 This can be disabled by setting $smarty->auto_literal = false;
       
    33 
       
    34 == Unquoted Strings ==
       
    35 Smarty 2 was a bit more forgiving (and ambiguous) when it comes to unquoted strings 
       
    36 in parameters. Smarty3 is more restrictive. You can still pass strings without quotes 
       
    37 so long as they contain no special characters. (anything outside of A-Za-z0-9_) 
       
    38 
       
    39 For example filename strings must be quoted
       
    40 <source lang="smarty">
       
    41 {include file='path/foo.tpl'}
       
    42 </source>
       
    43 
       
    44 == Extending the Smarty class ==
       
    45 Smarty 3 makes use of the __construct method for initialization. If you are extending 
       
    46 the Smarty class, its constructor is not called implicitly if the your child class defines 
       
    47 its own constructor. In order to run Smarty's constructor, a call to parent::__construct() 
       
    48 within your child constructor is required. 
       
    49 
       
    50 <source lang="php">
       
    51 class MySmarty extends Smarty {
       
    52    function __construct() {
       
    53        parent::__construct();
       
    54     
       
    55        // your initialization code goes here
       
    56 
       
    57    }
       
    58 }
       
    59 </source>
       
    60 
       
    61 == Autoloader ==
       
    62 Smarty 3 does register its own autoloader with spl_autoload_register. If your code has 
       
    63 an existing __autoload function then this function must be explicitly registered on 
       
    64 the __autoload stack. See http://us3.php.net/manual/en/function.spl-autoload-register.php 
       
    65 for further details.
       
    66 
       
    67 == Plugin Filenames ==
       
    68 Smarty 3 optionally supports the PHP spl_autoloader. The autoloader requires filenames 
       
    69 to be lower case. Because of this, Smarty plugin file names must also be lowercase. 
       
    70 In Smarty 2, mixed case file names did work.
       
    71 
       
    72 == Scope of Special Smarty Variables ==
       
    73 In Smarty 2 the special Smarty variables $smarty.section... and $smarty.foreach... 
       
    74 had global scope. If you had loops with the same name in subtemplates you could accidentally 
       
    75 overwrite values of parent template.
       
    76 
       
    77 In Smarty 3 these special Smarty variable have only local scope in the template which 
       
    78 is defining the loop. If you need their value in a subtemplate you have to pass them 
       
    79 as parameter.
       
    80 <source lang="smarty">
       
    81 {include file='path/foo.tpl' index=$smarty.section.foo.index}
       
    82 </source>
       
    83 
       
    84 == SMARTY_RESOURCE_CHAR_SET ==
       
    85 Smarty 3 sets the constant SMARTY_RESOURCE_CHAR_SET to utf-8 as default template charset. 
       
    86 This is now used also on modifiers like escape as default charset. If your templates use 
       
    87 other charsets make sure that you define the constant accordingly. Otherwise you may not 
       
    88 get any output.
       
    89 
       
    90 == newline at {if} tags ==
       
    91 A \n was added to the compiled code of the {if},{else},{elseif},{/if} tags to get output of newlines as expected by the template source. 
       
    92 If one of the {if} tags is at the line end you will now get a newline in the HTML output.
       
    93 
       
    94 == trigger_error() ==
       
    95 The API function trigger_error() has been removed because it did just map to PHP trigger_error.
       
    96 However it's still included in the Smarty2 API wrapper.
       
    97 
       
    98 == Smarty constants ==
       
    99 The constants 
       
   100 SMARTY_PHP_PASSTHRU
       
   101 SMARTY_PHP_QUOTE
       
   102 SMARTY_PHP_REMOVE
       
   103 SMARTY_PHP_ALLOW
       
   104 have been replaced with class constants
       
   105 Smarty::PHP_PASSTHRU
       
   106 Smarty::PHP_QUOTE
       
   107 Smarty::PHP_REMOVE
       
   108 Smarty::PHP_ALLOW
       
   109