mirror of
https://github.com/smarty-php/smarty.git
synced 2026-05-03 19:30:49 +02:00
make use_sub_dirs go back to crc32 for subdir separation
This commit is contained in:
mohrt
+81
-89
@@ -1,18 +1,45 @@
|
||||
<part id="getting.started">
|
||||
<title>Getting Started</title>
|
||||
|
||||
<chapter id="overview">
|
||||
<title>Overview</title>
|
||||
<sect1 id="what.is.smarty">
|
||||
<chapter id="what.is.smarty">
|
||||
<title>What is Smarty?</title>
|
||||
<para>
|
||||
Smarty is a template engine for PHP. One of the unique aspects about
|
||||
Smarty is that it compiles the template files into native PHP scripts
|
||||
upon the first invocation. After that, it just executes the compiled
|
||||
PHP scripts. Therefore, there is no costly template file parsing for
|
||||
each request, and each template can take full advantage of PHP compiler
|
||||
cache solutions such as Zend Cache (http://www.zend.com) or PHP
|
||||
Accelerator (http://www.php-accelerator.co.uk).
|
||||
Smarty is a template engine for PHP. More specifically, it facilitates a
|
||||
managable way to separate application logic and content from its
|
||||
presentation. This is best described in a situation where the application
|
||||
programmer and the template designer play different roles, or in most cases
|
||||
are not the same person. For example, let's say you are creating a web page
|
||||
that is displaying a newspaper article. The article headline, tagline,
|
||||
author and body are content elements, they contain no information about how
|
||||
they will be presented. They are passed into Smarty by the application,
|
||||
then the template designer edits the templates and uses a combination of
|
||||
HTML tags and template tags to format the presentation of these elements
|
||||
(HTML tables, background colors, font sizes, style sheets, etc.) One day
|
||||
the programmer needs to change the way the article content is retrieved (a
|
||||
change in application logic.) This change does not affect the template
|
||||
designer, the content will still arrive in the template exactly the same.
|
||||
Likewise, if the template designer wants to completely redesign the
|
||||
templates, this requires no changes to the application logic. Therefore,
|
||||
the programmer can make changes to the application logic without the need
|
||||
to restructure templates, and the template designer can make changes to
|
||||
templates without breaking application logic.
|
||||
</para>
|
||||
<para>
|
||||
Now for a short word on what Smarty does NOT do. Smarty does not attempt to
|
||||
completely separate logic from the templates. There is no problem with
|
||||
logic in your templates under the condition that this logic is strictly for
|
||||
presentation. A word of advice: keep application logic out of the
|
||||
templates, and presentation logic out of the application. This will most
|
||||
definately keep things managable and scalable for the foreseeable future.
|
||||
</para>
|
||||
<para>
|
||||
One of the unique aspects about Smarty is the template compling. This means
|
||||
Smarty reads the template files and creates PHP scripts from them. Once
|
||||
they are created, they are executed from then on. Therefore there is no
|
||||
costly template file parsing for each request, and each template can take
|
||||
full advantage of PHP compiler cache solutions such as Zend Accelerator
|
||||
(http://www.zend.com) or PHP Accelerator
|
||||
(http://www.php-accelerator.co.uk).
|
||||
</para>
|
||||
<para>
|
||||
Some of Smarty's features:
|
||||
@@ -41,66 +68,7 @@
|
||||
<listitem><para>Custom cache handling functions</para></listitem>
|
||||
<listitem><para>Plugin architecture</para></listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="how.smarty.works">
|
||||
<title>How Smarty works</title>
|
||||
|
||||
<sect2 id="features.compiling"><title>Compiling</title>
|
||||
<para>
|
||||
Smarty compiles the templates into native PHP code on-the-fly. The actual
|
||||
PHP scripts that are generated are created implicitly, so theoretically you
|
||||
should never have to worry about touching these files, or even know of their
|
||||
existence. The exception to this is debugging Smarty template syntax errors,
|
||||
discussed later in this document.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="features.caching">
|
||||
<title>Caching</title>
|
||||
<para>
|
||||
Smarty can cache the output of your generated templates. By default
|
||||
this is disabled. If you <link linkend="variable.caching">enable
|
||||
caching</link>, Smarty will store a copy of the generated template
|
||||
output, and use this until the copy <link
|
||||
linkend="variable.cache.lifetime">expires</link>, regenerating a new
|
||||
one. The default cache expire time can be configured from the
|
||||
class. The exception to the rule is the <link
|
||||
linkend="language.function.insert">insert</link> tag. Anything
|
||||
generated by the insert tag is not cached, but run dynamically on
|
||||
every invocation, even within cached content.
|
||||
</para>
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
Any time you change a template, change values in
|
||||
config files or change the content that gets displayed in a
|
||||
template, you can turn on compile_check to regenerate the caches
|
||||
that are affected, or wait for the cache to expire to see the
|
||||
results of the changes. You clear caches manually by deleting files
|
||||
from the cache directory, programatically with <link
|
||||
linkend="api.clear.cache">clear_cache</link> or <link
|
||||
linkend="api.clear.all.cache">clear_all_cache</link>, or turn on
|
||||
$compile_check (or $force_compile).
|
||||
</para>
|
||||
</note>
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
If you have caching enabled AND you have compile_check enabled, the cached
|
||||
file will regenerate if an involved template or config file has been
|
||||
modified, regardless of the cache expire time. This results in a slight
|
||||
performance hit since Smarty has to check the templates and config files
|
||||
for modification times. Therefore if you are not actively changing
|
||||
templates or config files, it is advisable to leave compile_check off.
|
||||
Enabling $force_compile will effectively disable caching, as the cache will
|
||||
get regerated on every invocation.
|
||||
</para>
|
||||
</note>
|
||||
</sect2>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
<chapter id="installation">
|
||||
<title>Installation</title>
|
||||
|
||||
@@ -113,17 +81,20 @@
|
||||
|
||||
<sect1 id="installing.smarty.basic">
|
||||
<title>Basic Installation</title>
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
This installation guide makes the assumption that you are familiar with
|
||||
your web server setup, your PHP setup, and your operating system directory
|
||||
naming conventions. In these examples we use a Unix filesystem, so be sure
|
||||
you make the appropriate adjustments for your environment. To be sure the
|
||||
examples in this installation work, add "/php/includes" to your PHP
|
||||
include_path if it is not already there. Your include_path is usually set
|
||||
in your php.ini file. You can see your current include_path from phpinfo(),
|
||||
or you can use ini_get('include_path') from within your PHP script.
|
||||
you make the appropriate adjustments for your environment.
|
||||
</para>
|
||||
<para>
|
||||
The following examples assume that "/php/includes" is in your PHP
|
||||
include_path. See the PHP manual for information on setting this up.
|
||||
</para>
|
||||
</note>
|
||||
<para>
|
||||
First install the Smarty library files. These are the PHP files that you DO
|
||||
NOT edit. They are shared among all applications and they only get updated
|
||||
when you upgrade to a new version of Smarty.
|
||||
@@ -131,10 +102,10 @@
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
We highly recommend you do not edit the Smarty files. This makes upgrades
|
||||
much easier for you. You DO NOT need to edit these files to configure your
|
||||
applications! Use an instance of the Smarty class, which we'll get to in
|
||||
the sample setup below.
|
||||
We recommend that you do not edit the Smarty library files. This makes
|
||||
upgrades much easier for you. You DO NOT need to edit these files to
|
||||
configure your applications! Use an instance of the Smarty class, which
|
||||
we'll get to in the sample setup below.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@@ -209,16 +180,16 @@ $smarty = new Smarty;</screen>
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
As a rule of thumb, none of these directories should be within the document
|
||||
root of your web server, and this is recommended to avoid any possible
|
||||
direct access. You may, for example, have config files with sensitive data.
|
||||
As a rule of thumb, none of these directories should be under the document
|
||||
root of your web server. This is recommended to avoid any possible direct
|
||||
access. You may, for example, have config files with sensitive data.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
You will need as least one file under your document root, and that is the
|
||||
script accessed by the web browser. We will call our script "index.php",
|
||||
and place it in a subdirectory called "guestbook".
|
||||
and place it in a subdirectory under the document root called "/guestbook/".
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@@ -254,6 +225,15 @@ $smarty = new Smarty;</screen>
|
||||
/web/www.mydomain.com/docs/guestbook/index.php</screen>
|
||||
</example>
|
||||
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
The $config_dir and $cache_dir are not absolutely necessary if you do not
|
||||
plan on using config files or template caching. It is probably a good idea
|
||||
to set them up anyways, in the case you decide to use them later.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Smarty will need write access to the $compile_dir and $cache_dir, so be sure
|
||||
the web server user can write to them. This is usually user "nobody" and
|
||||
@@ -298,6 +278,17 @@ Hello, {$name}!</screen>
|
||||
</example>
|
||||
|
||||
|
||||
<note>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
{* Smarty *} is a template comment. It is not required, but it is good
|
||||
practice to start all your template files with this comment. It makes
|
||||
the file easy to recognize regardless of the file extension. For
|
||||
example, text editors could recognize the file and turn on special
|
||||
syntax highlighting.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
Now lets edit index.php. We'll create an instance of Smarty, assign a
|
||||
template variable and display the index.tpl file.
|
||||
@@ -326,10 +317,11 @@ $smarty->display('index.tpl');</screen>
|
||||
<title>Technical Note</title>
|
||||
<para>
|
||||
In our example, we are setting absolute paths to all of the Smarty
|
||||
directories. If these directories are within your PHP include_path, then
|
||||
these settings are not necessary. However, it is more efficient and (in
|
||||
personal experience) less error-prone to set them to absolute paths. This
|
||||
ensures that Smarty is getting files from the directories you intended.
|
||||
directories. If '/web/www.mydomain.com/smarty/guestbook/' is within your
|
||||
PHP include_path, then these settings are not necessary. However, it is
|
||||
more efficient and (from experience) less error-prone to set them to
|
||||
absolute paths. This ensures that Smarty is getting files from the
|
||||
directories you intended.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@@ -342,7 +334,7 @@ $smarty->display('index.tpl');</screen>
|
||||
</para>
|
||||
</sect1>
|
||||
<sect1 id="installing.smarty.extended">
|
||||
<title>Extended Installation</title>
|
||||
<title>Extended Setup</title>
|
||||
|
||||
<para>
|
||||
This is a continuation of the <link
|
||||
@@ -365,8 +357,8 @@ $smarty->display('index.tpl');</screen>
|
||||
define(SMARTY_DIR,'/usr/local/lib/php/Smarty/');
|
||||
require(SMARTY_DIR.'Smarty.class.php');
|
||||
|
||||
// load application library files
|
||||
require('guestbook/guestbook.lib.php');
|
||||
// a good place to load application library files, example:
|
||||
// require('guestbook/guestbook.lib.php');
|
||||
|
||||
Smarty_GuestBook extends Smarty {
|
||||
|
||||
|
||||
Reference in New Issue
Block a user