update files for 1.4.0 release

NEWS

@@ -1,3 +1,9 @@
+Version 1.4.0
+-------------
+    - added RELEASE_NOTES file to distribution (Monte)
+    - added register_resource() and unregister_resource() functions (Monte)
+    - changed syntax of variables called within section loops,
+      supplied fix_vars.php script to fix old syntax (Andrei)
     - added $check_cached_insert_tags to speed up cached pages if
       {insert ...} is not used (Monte)
     - added $compiler_class variable to allow specifying a different compiler

README

@@ -2,7 +2,7 @@ NAME:
 
     Smarty - the PHP compiling template engine
 
-VERSION: 1.3.2
+VERSION: 1.4.0
 
 AUTHORS:
     
@@ -14,7 +14,8 @@ MAILING LIST:
 
     We have a mailing list for you to share your ideas or ask questions.
     send a blank e-mail message to subscribe-smarty@lists.ispi.net
-
+    You can also browse the mailing list archives at
+    http://marc.theaimsgroup.com/?l=smarty&r=1&w=2
 
 SYNOPSIS:
 

RELEASE_NOTES

@@ -3,15 +3,15 @@
 
 IMPORTANT NOTICE: Smarty now has a new syntax for accessing elements within
 section loops. The new syntax is easier to use for complex data structures.
-Consequently, this breaks the old syntax. To fix your old templates, we have
+Consequently, this breaks the old syntax. To fix your current templates, we
-provided a script that will fix the syntax for you. Located in
+have provided a script that will adjust the syntax for you. Located in
 misc/fix_vars.php, run this script from the the command line, giving each
 template as an argument. Be sure to use absolute pathnames, or pathnames
 relative to the executing script. Probably the easiest way to do this is to
 copy the fix_vars.php script into your template directory and run 'php -q
-fix_vars.php *.tpl' For each template, this will create a temporary file with
+fix_vars.php *.tpl' Be sure you have proper write permission, and backup your
-the fixes, then move the temp file over top the original. Backup your scripts
+scripts first to be safe! The examples in the 1.4.0 documentation have been
-first to be safe!
+updated to reflect the changes.
 
 Smarty 1.4.0 also has a new compilation process. Instead of compiling all the
 templates up front, it now compiles them at runtime. This has several
@@ -21,13 +21,11 @@ directories or even database calls. This also speeds the performance of Smarty
 when $compile_check is enabled, since it is only checking the template that is
 being executed instead of everything found in the template directory. The
 $tpl_file_ext is no longer needed, but kept for backward compatability.
-Templates can now be named anything you like with any extension. Smarty makes
+Templates can now be named anything you like with any extension.
-use of the PEAR database abstraction class for obtaining templates from
-databases.
 
-We also added a workaround for LOCK_EX on Windows systems, and changed a couple
+A workaround for LOCK_EX on Windows systems was added, and changed a couple of
-of file permissions for better security on public servers. Thanks goes to
+file permissions for better security on public servers. Thanks goes to Fernando
-Fernando Nunes for his code contributions.
+Nunes for his code contributions.
 
 date_format, html_select_date and html_select_time used to require a unix
 timestamp as the format of the date passed into the template. Smarty is now a
@@ -35,14 +33,19 @@ bit smarter at this. It will take a unix timestamp, a mysql timestamp, or any
 date string that is parsable by strtotime, such as 10/01/2001 or 2001-10-01,
 etc. Just give some formats a try and see what works.
 
+The format of the files created in the $compile_dir are now a bit different.
+Instead of reflecting the name and path of the source template, it uses an
+encoded file name, all in the top level directory. This was done to make way
+for arbitrary template resources. Each compiled template has a header that
+states what template resource was used to create it. From a unix command
+prompt, you can use "head -2 *" to see the first two lines of each file.
+
 When upgrading to 1.4.0, you will want to first clear out all your files in the
-$compile_dir, since it now uses a new format. Since templates can come from any
+$compile_dir, since it now uses a new format. If you have $compile_check set to
-source, the compiled versions have encoded names. Each file has a comment at
-the top that states which resource was used as the source file. In unix, "head
--2 *" shows the first two lines of each file. If you have $compile_check set to
 false and the compiled template does not yet exist, it will compile it
-regardless of this setting. Once it is compiled though, it will not check to see
+regardless of this setting. This way you can clear out the $compile_dir and not
-if recompilation is necessary.
+worry about setting $compile_check to true to get the inital compilation under
+way.
 
 1.3.2
 -----

Smarty.addons.php

@@ -4,7 +4,7 @@
  * File:        Smarty.addons.php
  * Author:      Monte Ohrt <monte@ispi.net>
  *              Andrei Zmievski <andrei@ispi.net>
- * Version:     1.3.2
+ * Version:     1.4.0
  * Copyright:   2001 ispi of Lincoln, Inc.
  *
  * This library is free software; you can redistribute it and/or

Smarty.class.php

@@ -5,7 +5,7 @@
  * Author:      Monte Ohrt <monte@ispi.net>
  *              Andrei Zmievski <andrei@ispi.net>
  *
- * Version:             1.3.2
+ * Version:             1.4.0
  * Copyright:           2001 ispi of Lincoln, Inc.
  *              
  * This library is free software; you can redistribute it and/or
@@ -123,9 +123,7 @@ class Smarty
                                     'count_paragraphs'  => 'smarty_mod_count_paragraphs'
                                  );
                                  
-    var $template_resource_handlers  =  array(); // where resource handlers are mapped
+    var $version               =   '1.4.0';  // Smarty version number                     
-
-    var $version               =   '1.3.2';  // Smarty version number                     
     var $show_info_header      =   true;     // display info header at top of page output
 
     var $compiler_class        =   'Smarty_Compiler'; // the compiler class used by
@@ -140,6 +138,7 @@ class Smarty
     var $_error_msg             =   false;      // error messages. true/false
     var $_tpl_vars              =   array();
     var $_smarty_md5            =   'f8d698aea36fcbead2b9d5359ffca76f'; // md5 checksum of the string 'Smarty'    
+    var $_resource_handlers  =  array(); // what functions resource handlers are mapped to
     
 /*======================================================================*\
     Function: Smarty
@@ -248,6 +247,24 @@ class Smarty
         unset($this->custom_mods[$modifier]);
     }
 
+/*======================================================================*\
+    Function: register_resource
+    Purpose:  Registers a resource to fetch a template
+\*======================================================================*/
+    function register_resource($name, $function_name)
+    {
+        $this->_resource_handlers[$name] = $function_name;
+    }
+
+/*======================================================================*\
+    Function: unregister_resource
+    Purpose:  Unregisters a resource
+\*======================================================================*/
+    function unregister_resource($name)
+    {
+        unset($this->_resource_handlers[$name]);
+    }
+
     
 /*======================================================================*\
     Function:   clear_cache()
@@ -525,10 +542,21 @@ class Smarty
                     return false;
                 }
                 break;
-
             default:
-                $this->_trigger_error_msg("unknown resource type: \"$resource_type.\"");
+                if(isset($this->_resource_handlers[$resource_type])) {
+                    $funcname = $this->_resource_handlers[$resource_type];
+                    if(function_exists($funcname)) {
+                        // call the function to fetch the template
+                        $funcname($resource_name,$template_source,$template_timestamp);
+                        return true;
+                    } else {
+                        $this->_trigger_error_msg("function: \"$funcname\" does not exist for resource type: \"$resource_type\".");
                         return false;                        
+                    }
+                } else {
+                    $this->_trigger_error_msg("unknown resource type: \"$resource_type\". Register this resource first.");
+                    return false;
+                }
                 break;
         }
 

Smarty_Compiler.class.php

@@ -6,7 +6,7 @@
  * Author:      Monte Ohrt <monte@ispi.net>
  *              Andrei Zmievski <andrei@ispi.net>
  *
- * Version:             1.3.2
+ * Version:             1.4.0
  * Copyright:           2001 ispi of Lincoln, Inc.
  *
  * This library is free software; you can redistribute it and/or

docs.sgml

@@ -734,6 +734,51 @@ $smarty->register_modifier("sslash","stripslashes");
 
 $smarty->unregister_modifier("strip_tags");
 
+</programlisting>
+</example>
+		</sect2>
+		<sect2 id="api.register.resource">
+			<title>register_resource</title>
+			<funcsynopsis>
+			<funcprototype>
+			<funcdef>void <function>register_resource</function></funcdef>
+				<paramdef>string <parameter>resource_name</parameter></paramdef>
+				<paramdef>string <parameter>function_name</parameter></paramdef>
+			</funcprototype>
+			</funcsynopsis>
+			<para>
+                Use this to dynamically register a resource to fetch templates
+                with Smarty. See <link
+                linkend="section.template.resources">template resources</link>
+                for more information on how to setup a function for fetching
+                templates.
+			</para>
+<example>
+<title>register_resource</title>
+<programlisting>
+
+$smarty->register_resource("db","get_db_template");
+
+</programlisting>
+</example>
+		</sect2>
+		<sect2 id="api.unregister.resource">
+			<title>unregister_resource</title>
+			<funcsynopsis>
+			<funcprototype>
+			<funcdef>void <function>unregister_resource</function></funcdef>
+				<paramdef>string <parameter>resource_name</parameter></paramdef>
+			</funcprototype>
+			</funcsynopsis>
+			<para>
+                Use this to dynamically unregister a resource.
+			</para>
+<example>
+<title>unregister_resource</title>
+<programlisting>
+
+$smarty->unregister_resource("db");
+
 </programlisting>
 </example>
 		</sect2>
@@ -921,9 +966,10 @@ echo $output;
 		<sect2>
 			<title>Templates from $template_dir</title>
 			<para>
-            Templates from the $template_dir do not require a template resource.
+            Templates from the $template_dir do not require a template
-            Just supply the path to the template you want to use relative to the
+            resource, although you can use the file: resource for consistancy.
-            $template_dir root directory.
+            Just supply the path to the template you want to use relative to
+            the $template_dir root directory.
             </para>
 <example>
 
@@ -959,6 +1005,47 @@ $smarty->display("file:/path/to/my/templates/menu.tpl");
 {* from within Smarty template *}
 {include file="file:/usr/local/share/templates/navigation.tpl"}
 
+</programlisting>
+</example>
+        </sect2>
+		<sect2>
+			<title>Templates from a function call</title>
+			<para>
+            You can get templates from a custom function call, such as
+            retrieving templates from a database. You do this by first
+            registering your resource handler function, then creating your
+            function to get the template. Smarty expects your function to be of
+            this form: funcname($tpl_name,&tpl_source, &$tpl_timestamp) {} $tpl
+            name is passed into the function, and your function should populate
+            $tpl_source and $tpl_timestamp with the template source and the
+            last modified time of the template respectively.
+            </para>
+<example>
+
+<title>using templates from a function call</title>
+<programlisting>
+
+// from PHP script
+
+// put this function somewhere in your application
+function get_db_template ($tpl_name, &$tpl_source, &$tpl_timestamp) {
+    // do database calls (or whatever) here to fetch your template, populating
+    // $tpl_source and $tpl_timestamp.
+    
+    $tpl_source = "This is a simulation of a template fetched from a db.";
+    $tpl_timestamp = mktime();
+    
+    return true;
+}
+
+$smarty->register_resource("db" => "get_db_template");
+
+// using resource from php script
+$smarty->display("db:index.tpl");
+
+{* using resource from within Smarty template *}
+{include file="db:/extras/navigation.tpl"}
+
 </programlisting>
 </example>
         </sect2>

libs/Smarty.class.php

@@ -5,7 +5,7 @@
  * Author:      Monte Ohrt <monte@ispi.net>
  *              Andrei Zmievski <andrei@ispi.net>
  *
- * Version:             1.3.2
+ * Version:             1.4.0
  * Copyright:           2001 ispi of Lincoln, Inc.
  *              
  * This library is free software; you can redistribute it and/or
@@ -123,9 +123,7 @@ class Smarty
                                     'count_paragraphs'  => 'smarty_mod_count_paragraphs'
                                  );
                                  
-    var $template_resource_handlers  =  array(); // where resource handlers are mapped
+    var $version               =   '1.4.0';  // Smarty version number                     
-
-    var $version               =   '1.3.2';  // Smarty version number                     
     var $show_info_header      =   true;     // display info header at top of page output
 
     var $compiler_class        =   'Smarty_Compiler'; // the compiler class used by
@@ -140,6 +138,7 @@ class Smarty
     var $_error_msg             =   false;      // error messages. true/false
     var $_tpl_vars              =   array();
     var $_smarty_md5            =   'f8d698aea36fcbead2b9d5359ffca76f'; // md5 checksum of the string 'Smarty'    
+    var $_resource_handlers  =  array(); // what functions resource handlers are mapped to
     
 /*======================================================================*\
     Function: Smarty
@@ -248,6 +247,24 @@ class Smarty
         unset($this->custom_mods[$modifier]);
     }
 
+/*======================================================================*\
+    Function: register_resource
+    Purpose:  Registers a resource to fetch a template
+\*======================================================================*/
+    function register_resource($name, $function_name)
+    {
+        $this->_resource_handlers[$name] = $function_name;
+    }
+
+/*======================================================================*\
+    Function: unregister_resource
+    Purpose:  Unregisters a resource
+\*======================================================================*/
+    function unregister_resource($name)
+    {
+        unset($this->_resource_handlers[$name]);
+    }
+
     
 /*======================================================================*\
     Function:   clear_cache()
@@ -525,10 +542,21 @@ class Smarty
                     return false;
                 }
                 break;
-
             default:
-                $this->_trigger_error_msg("unknown resource type: \"$resource_type.\"");
+                if(isset($this->_resource_handlers[$resource_type])) {
+                    $funcname = $this->_resource_handlers[$resource_type];
+                    if(function_exists($funcname)) {
+                        // call the function to fetch the template
+                        $funcname($resource_name,$template_source,$template_timestamp);
+                        return true;
+                    } else {
+                        $this->_trigger_error_msg("function: \"$funcname\" does not exist for resource type: \"$resource_type\".");
                         return false;                        
+                    }
+                } else {
+                    $this->_trigger_error_msg("unknown resource type: \"$resource_type\". Register this resource first.");
+                    return false;
+                }
                 break;
         }
 

libs/Smarty_Compiler.class.php

@@ -6,7 +6,7 @@
  * Author:      Monte Ohrt <monte@ispi.net>
  *              Andrei Zmievski <andrei@ispi.net>
  *
- * Version:             1.3.2
+ * Version:             1.4.0
  * Copyright:           2001 ispi of Lincoln, Inc.
  *
  * This library is free software; you can redistribute it and/or