From c4b46fe7c86e1042b5ec4f120641eed14208c7ca Mon Sep 17 00:00:00 2001 From: "monte.ohrt" Date: Fri, 2 Oct 2009 14:43:55 +0000 Subject: [PATCH] update for beta --- README | 152 +++++++++++++++++++++++++++++++++------------------------ 1 file changed, 89 insertions(+), 63 deletions(-) diff --git a/README b/README index f1957d62..6d9fde28 100644 --- a/README +++ b/README @@ -1,34 +1,29 @@ -Smarty 3.0 Alpha 1 : Proof of Concept +Smarty 3.0 Beta Author: Monte Ohrt Author: Uwe Tews -This code is a proof of concept as a basis of the Smarty 3 template engine. -It is by no means complete, it is only a shell of an infrastructure to build -the 3.0 codebase upon. What I need is feedback before continuing! Now is the -time to make decisions that will affect the engine fundamentals. +AN INTRODUCTION TO SMARTY 3 BETA -So, a quick intro to the thinking behind this alpha code. +The file structure is similar to Smarty 2: -If you take a look at the file structure, you should see this: - -index.php /libs/ Smarty.class.php /libs/sysplugins/ internal.* -/plugins/ +/libs/plugins/ function.mailto.php modifier.escape.php -/templates/ - index.tpl - index_view.php - + ... -If you execute the index.php file, you will see an example of using Smarty to -display a couple of template files. +A lot of Smarty 3 core functionality lies in the sysplugins directory, you do +not need to change any files here. The /libs/plugins/ folder is where Smarty +plugins are located. You can add your own here, or create a separate plugin +directory, just the same as Smarty 2. You will still need to create your own +/cache/, /templates/, /templates_c/, /configs/ folders. Be sure /cache/ and +/templates_c/ are writable. -The way to use Smarty 3 should look extremely familiar: +The typical way to use Smarty 3 should also look familiar: require('Smarty.class.php'); $smarty = new Smarty; @@ -36,60 +31,82 @@ $smarty->assign('foo','bar'); $smarty->display('index.tpl'); -However, Smarty works completely different on the inside. The majority of -the Smarty system now lies in the plugin directory. The core Smarty.class.php -class is extremely slim. The fundamental idea is for Smarty to lazy-load all -requirements (objects) on an as-needed basis. +However, Smarty 3 works completely different on the inside. Smarty 3 is mostly +backward compatible with Smarty 2, except for the following items: -LEXER/PARSER! - -Smarty 3 now uses a real lexing tokenizer and a parser. This opens all kinds of doors -such as template math, function recursion, among many other things. +*) Smarty 3 is PHP 5 only. It will not work with PHP 4. +*) The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true. +*) Delimiters surrounded by whitespace are no longer treated as Smarty tags. + Therefore, { foo } will not compile as a tag, you must use {foo}. This change + Makes Javascript/CSS easier to work with, eliminating the need for {literal}. -Since all internal plugins are now classes (did I mention that yet?), They all extend -Smarty_Internal_PluginBase, which makes $this->smarty a reference to the Smarty -object instance. This is available to all plugins. +There are many things that are new to Smarty 3. Here are the notable items: + +LEXER/PARSER + +Smarty 3 now uses a lexing tokenizer for it's parser/compiler. Basically, this +means Smarty has some syntax additions that make life easier such as in-template +math, shorter/intuitive function parameter options, infinite function recursion, +more accurate error handling, etc. + +OBJECTS + +Smarty 3 plugins are now objects that extend Smarty_Internal_PluginBase. All +plugins have the property $this->smarty available as a reference to the Smarty +object instance. The Smarty 2 function-style plugins are still compatible, you +can drop them right into the Smarty 3 plugin directory. PHP TEMPLATES -Smarty's fundamental design goals are meant to separate business logic from -presentation logic. Since Smarty 2.0 templates work on a tag-based syntax, this -has usually equated to "Don't put PHP in the templates." But, these two -philosophies are completely separate. You could conceivably use plain PHP -scripts as your templates and still maintain business logic separation. -Even though PHP is used in the template, it is still just presentation logic. +For those that prefer pure PHP over the {tag} based syntax, Smarty now offers +a PHP option for template syntax. PHP templates have several differences over +the tag-based templates: -So now you have your choice: Use templates that are just plain PHP code, or -use the compiled templates using the familiar {$foo} tag syntax. Whatever is -more important to you (PHP or tags/security/etc), make your own choice. Just -remember, PHP templates require YOU to keep the separation yourself. It won't -be as obvious. +*) PHP templates are not compiled, they are included directly by the engine. +*) None of Smarty's security features are applied to PHP templates. +*) By default, PHP templates are disabled, set $smarty->allow_php_templates=true. If you want to use a PHP template, just use the "php" resource type: -$smarty->display('php:mytemplate.tpl'); +$smarty->display('php:foo.php'); -Smarty will not compile it, it will just get executed as PHP. You have full -reign of PHP in your template code. Your assigned template vars are available -simply as , etc. +You can also mix PHP templates with {tag} templates: +{include file="php:foo.php"} + +In PHP templates, assigned vars are available simply as: + +// same as {$foo} + + // php short tags + +Modifiers are used as such: + +// same as {foo|trim|truncate:50} +$foo->trim()->truncate(50); + +Template functions are used as such: + +// same as {foo bar=$baz} +$_f->foo($baz); WHAT IS NEW IN SMARTY TEMPLATE SYNTAX -Smarty tags can be used as value in other tags. -Eample: {$foo={counter}+3} +Smarty tags can be used as values within other tags. +Example: {$foo={counter}+3} They can also be used inside double quoted strings. Example: {$foo="this is message {counter}"} -The special variable $smarty.current_dir does return the dirname of the current template. +$smarty.current_dir returns the dirname of the current template. -You can also use strings as templates with the "string" resource type: +You can use strings directly as templates with the "string" resource type: $smarty->display('string:This is my template, {$foo}!'); +{include file="string:This is my template, {$foo}!"} -You can use complex expressions almost anywhere. +You can use math expressions in the templates. {$x+$y} will output the sum of x and y. PHP functions can be used in expressions unless they are disabled by the security policy. {assign var=foo value=2*(3+sqrt($bar))} @@ -103,23 +120,25 @@ Arrays can be nested. There is a new "short" syntax for assigning variables. {$foo=$bar+2} -Arrays can be accessed now also with a new syntax -{$foo['colour']} -The old syntax {$foo.colour} will still work. +Arrays can be accessed now also with a new syntax. +{$foo['bar']} // same as {$foo.bar} +The quotes are required. This syntax addition addresses ambiguties when nesting +the dot syntax. The dot syntax {$foo.bar} will still work. -Variable names can be variable. -{$foo_{$x}} will output the variable foo_1 if $x has a value of 1. +Variable names can be handled with variables directly. +{$foo_{$x}} will output the variable $foo_1 if $x has a value of 1. Object method chaining is implemented. {$object->method1($x)->method2($y)} -New {for....} tag: -For a counting for loop: +{for} tag added for looping (replacement for {section} tag): {for $x=0, $y=count($foo); $x<$y; $i++} .... {/for} Any number of statements can be used separated by comma as the first -inital expression at {for} +inital expression at {for}. -New {foreach...} syntax to loop over an array: +The Smarty 2 {section} syntax is still supported. + +New {foreach} syntax to loop over an array: {foreach $myarray as $var} .... {/foreach} $var@key will deliver the key $var@iteration will deliver the iteration @@ -128,22 +147,29 @@ $var@total will deliver the total number of array entries $var@first will deliver true for the first iteration $var@last will deliver true for the last iteration -The {for} and new {foreach} will replace Smarty2's {foreach} and {section}. For BC Smarty2 {foreach} are {section} syntax is still supported. +The Smarty 2 {foreach} tag syntax is still supported. -NOTE: {$bar[foo]} will always be parsed that foo is the name of a section. -If you want to access an array element with index foo,you must use quotes like {$bar['foo']} +NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. +If you want to access an array element with index foo, you must use quotes +such as {$bar['foo']}, or use the dot syntax {$bar.foo}. New {while....} tag: {while $i<10} .... {/while} +Direct access to PHP functions: +Just as you can use PHP functions as modifiers directly, you can now access +PHP functions directly, provided they are permitted by security settings: +{time()} + +New {nocache} block function: {nocache} ... {/nocache} will declare a section of the template to be not cached. -You can declare output to be not cached with the nocache attribute. +New nocache attribute: +You can declare variable/function output as non-cached with the nocache attribute. {$foo nocache=true} +{foo bar="baz" nocache=true} {time() nocache=true} -Ok that pretty much wraps up the principles and fetures behind the alpha code. -But this list is not complete yet. Please look through it and send any questions/suggestions/etc to the forums. http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168