smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-07-29 15:37:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

WIP improving the docs

Browse Source
This commit is contained in:
Simon Wisselink
2023-02-05 23:14:10 +01:00
parent 51ed0d6791
commit 1e0d25638e
25 changed files with 705 additions and 765 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/appendixes/tips.md
View File

@ -1,23 +1,22 @@
Tips & Tricks {#tips}
=============
# Tips & Tricks
Blank Variable Handling {#tips.blank.var.handling}
=======================
## Blank Variable Handling
There may be times when you want to print a default value for an empty
variable instead of printing nothing, such as printing ` ` so that
html table backgrounds work properly. Many would use an
[`{if}`](#language.function.if) statement to handle this, but there is a
[`{if}`](../designers/language-builtin-functions/language-function-if.md) statement to handle this, but there is a
shorthand way with Smarty, using the
[`default`](#language.modifier.default) variable modifier.
[`default`](../designers/language-modifiers/language-modifier-default.md) variable modifier.
> **Note**
>
> "Undefined variable" errors will show an E\_NOTICE if not disabled in
> PHP\'s [`error_reporting()`](https://www.php.net/error_reporting) level or
> Smarty\'s [`$error_reporting`](#variable.error.reporting) property and
> PHP's [`error_reporting()`](https://www.php.net/error_reporting) level or
> Smarty's [`$error_reporting`](../programmers/api-variables/variable-error-reporting.md) property and
> a variable had not been assigned to Smarty.
```smarty
{* the long way *}
{if $title eq ''}
@ -29,19 +28,18 @@ shorthand way with Smarty, using the
{* the short way *}
{$title|default:' '}
```
See also [`default`](#language.modifier.default) modifier and [default
variable handling](#tips.default.var.handling).
See also [`default`](../designers/language-modifiers/language-modifier-default.md) modifier and [default
variable handling](#default-variable-handling).
Default Variable Handling {#tips.default.var.handling}
=========================
## Default Variable Handling
If a variable is used frequently throughout your templates, applying the
[`default`](#language.modifier.default) modifier every time it is
[`default`](../designers/language-modifiers/language-modifier-default.md) modifier every time it is
mentioned can get a bit ugly. You can remedy this by assigning the
variable its default value with the
[`{assign}`](#language.function.assign) function.
[`{assign}`](../designers/language-builtin-functions/language-function-assign.md) function.
{* do this somewhere at the top of your template *}
@ -52,150 +50,156 @@ variable its default value with the
See also [`default`](#language.modifier.default) modifier and [blank
variable handling](#tips.blank.var.handling).
See also [`default`](../designers/language-modifiers/language-modifier-default.md) modifier and [blank
variable handling](#blank-variable-handling).
Passing variable title to header template {#tips.passing.vars}
=========================================
## Passing variable title to header template
When the majority of your templates use the same headers and footers, it
is common to split those out into their own templates and
[`{include}`](#language.function.include) them. But what if the header
[`{include}`](../designers/language-builtin-functions/language-function-include.md) them. But what if the header
needs to have a different title, depending on what page you are coming
from? You can pass the title to the header as an
[attribute](#language.syntax.attributes) when it is included.
[attribute](../designers/language-basic-syntax/language-syntax-attributes.md) when it is included.
`mainpage.tpl` - When the main page is drawn, the title of "Main Page"
is passed to the `header.tpl`, and will subsequently be used as the
title.
```smarty
{include file='header.tpl' title='Main Page'}
{* template body goes here *}
{include file='footer.tpl'}
{include file='header.tpl' title='Main Page'}
{* template body goes here *}
{include file='footer.tpl'}
```
`archives.tpl` - When the archives page is drawn, the title will be
"Archives". Notice in the archive example, we are using a variable from
the `archives_page.conf` file instead of a hard coded variable.
```smarty
{config_load file='archive_page.conf'}
{config_load file='archive_page.conf'}
{include file='header.tpl' title=#archivePageTitle#}
{* template body goes here *}
{include file='footer.tpl'}
{include file='header.tpl' title=#archivePageTitle#}
{* template body goes here *}
{include file='footer.tpl'}
```
`header.tpl` - Notice that "Smarty News" is printed if the `$title`
variable is not set, using the [`default`](#language.modifier.default)
variable is not set, using the [`default`](../designers/language-modifiers/language-modifier-default.md)
variable modifier.
```smarty
<html>
<html>
<head>
<title>{$title|default:'Smarty News'}</title>
<title>{$title|default:'Smarty News'}</title>
</head>
<body>
<body>
```
`footer.tpl`
```smarty
</body>
</html>
</html>
```
Dates {#tips.dates}
=====
## Dates
As a rule of thumb, always pass dates to Smarty as
[timestamps](https://www.php.net/time). This allows template designers to
use the [`date_format`](#language.modifier.date.format) modifier for
use the [`date_format`](../designers/language-modifiers/language-modifier-date-format.md) modifier for
full control over date formatting, and also makes it easy to compare
dates if necessary.
{$startDate|date_format}
```smarty
{$startDate|date_format}
```
This will output:
```
Jan 4, 2009
```
Jan 4, 2009
```smarty
{$startDate|date_format:"%Y/%m/%d"}
{$startDate|date_format:"%Y/%m/%d"}
```
This will output:
2009/01/04
```
2009/01/04
```
Dates can be compared in the template by timestamps with:
```smarty
{if $order_date < $invoice_date}
...do something..
{/if}
{if $order_date < $invoice_date}
...do something..
{/if}
```
When using [`{html_select_date}`](#language.function.html.select.date)
When using [`{html_select_date}`](../designers/language-custom-functions/language-function-html-select-date.md)
in a template, the programmer will most likely want to convert the
output from the form back into timestamp format. Here is a function to
help you with that.
```php
<?php
<?php
// this assumes your form elements are named
// startDate_Day, startDate_Month, startDate_Year
// this assumes your form elements are named
// startDate_Day, startDate_Month, startDate_Year
$startDate = makeTimeStamp($startDate_Year, $startDate_Month, $startDate_Day);
$startDate = makeTimeStamp($startDate_Year, $startDate_Month, $startDate_Day);
function makeTimeStamp($year='', $month='', $day='')
{
if(empty($year)) {
$year = strftime('%Y');
}
if(empty($month)) {
$month = strftime('%m');
}
if(empty($day)) {
$day = strftime('%d');
}
function makeTimeStamp($year='', $month='', $day='')
{
if(empty($year)) {
$year = strftime('%Y');
}
if(empty($month)) {
$month = strftime('%m');
}
if(empty($day)) {
$day = strftime('%d');
}
return mktime(0, 0, 0, $month, $day, $year);
}
?>
return mktime(0, 0, 0, $month, $day, $year);
}
```
See also [`{html_select_date}`](#language.function.html.select.date),
[`{html_select_time}`](#language.function.html.select.time),
[`date_format`](#language.modifier.date.format) and
[`$smarty.now`](#language.variables.smarty.now),
See also [`{html_select_date}`](../designers/language-custom-functions/language-function-html-select-date.md),
[`{html_select_time}`](../designers/language-custom-functions/language-function-html-select-time.md),
[`date_format`](../designers/language-modifiers/language-modifier-date-format.md) and
[`$smarty.now`](../designers/language-variables/language-variables-smarty.md#smarty-now),
Componentized Templates {#tips.componentized.templates}
=======================
## Componentized Templates
Traditionally, programming templates into your applications goes as
follows: First, you accumulate your variables within your PHP
application, (maybe with database queries.) Then, you instantiate your
Smarty object, [`assign()`](#api.assign) the variables and
[`display()`](#api.display) the template. So lets say for example we
Smarty object, [`assign()`](../programmers/api-functions/api-assign.md) the variables and
[`display()`](../programmers/api-functions/api-display.md) the template. So lets say for example we
have a stock ticker on our template. We would collect the stock data in
our application, then assign these variables in the template and display
it. Now wouldn't it be nice if you could add this stock ticker to any
@ -206,58 +210,59 @@ You can do this by writing a custom plugin for fetching the content and
assigning it to a template variable.
`function.load_ticker.php` - drop file in
[`$plugins directory`](#variable.plugins.dir)
[`$plugins directory`](../programmers/api-variables/variable-plugins-dir.md)
```php
<?php
<?php
// setup our function for fetching stock data
function fetch_ticker($symbol)
{
// put logic here that fetches $ticker_info
// from some ticker resource
return $ticker_info;
}
// setup our function for fetching stock data
function fetch_ticker($symbol)
{
// put logic here that fetches $ticker_info
// from some ticker resource
return $ticker_info;
}
function smarty_function_load_ticker($params, $smarty)
{
// call the function
$ticker_info = fetch_ticker($params['symbol']);
function smarty_function_load_ticker($params, $smarty)
{
// call the function
$ticker_info = fetch_ticker($params['symbol']);
// assign template variable
$smarty->assign($params['assign'], $ticker_info);
}
?>
// assign template variable
$smarty->assign($params['assign'], $ticker_info);
}
```
`index.tpl`
```smarty
{load_ticker symbol='SMARTY' assign='ticker'}
{load_ticker symbol='SMARTY' assign='ticker'}
Stock Name: {$ticker.name} Stock Price: {$ticker.price}
Stock Name: {$ticker.name} Stock Price: {$ticker.price}
```
See also: [`{include}`](#language.function.include).
See also: [`{include}`](../designers/language-builtin-functions/language-function-include.md).
Obfuscating E-mail Addresses {#tips.obfuscating.email}
============================
## Obfuscating E-mail Addresses
Do you ever wonder how your email address gets on so many spam mailing
lists? One way spammers collect email addresses is from web pages. To
help combat this problem, you can make your email address show up in
scrambled javascript in the HTML source, yet it it will look and work
correctly in the browser. This is done with the
[`{mailto}`](#language.function.mailto) plugin.
[`{mailto}`](../designers/language-custom-functions/language-function-mailto.md) plugin.
```smarty
<div id="contact">Send inquiries to
{mailto address=$EmailAddress encode='javascript' subject='Hello'}
</div>
<div id="contact">Send inquiries to
{mailto address=$EmailAddress encode='javascript' subject='Hello'}
</div>
```
> **Note**
>
@ -265,5 +270,5 @@ correctly in the browser. This is done with the
> his e-mail collector to decode these values, but not likely\....
> hopefully..yet \... wheres that quantum computer :-?.
See also [`escape`](#language.modifier.escape) modifier and
[`{mailto}`](#language.function.mailto).
See also [`escape`](../designers/language-modifiers/language-modifier-escape.md) modifier and
[`{mailto}`](../designers/language-custom-functions/language-function-mailto.md).

122
docs/appendixes/troubleshooting.md
View File

@ -1,20 +1,18 @@
Troubleshooting
===============
# Troubleshooting
Smarty/PHP errors {#smarty.php.errors}
=================
## Smarty/PHP errors
Smarty can catch many errors such as missing tag attributes or malformed
variable names. If this happens, you will see an error similar to the
following:
```
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
in /path/to/smarty/Smarty.class.php on line 1041
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
in /path/to/smarty/Smarty.class.php on line 1041
Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
in /path/to/smarty/Smarty.class.php on line 1041
Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
in /path/to/smarty/Smarty.class.php on line 1041
```
Smarty shows you the template name, the line number and the error. After
@ -25,96 +23,82 @@ There are certain errors that Smarty cannot catch, such as missing close
tags. These types of errors usually end up in PHP compile-time parsing
errors.
Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
`Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75`
When you encounter a PHP parsing error, the error line number will
correspond to the compiled PHP script, NOT the template itself. Usually
you can look at the template and spot the syntax error. Here are some
common things to look for: missing close tags for
[`{if}{/if}`](#language.function.if) or
[`{section}{/section}`](#language.function.if), or syntax of logic
within an `{if}` tag. If you can\'t find the error, you might have to
[`{if}{/if}`](../designers/language-builtin-functions/language-function-if.md) or
[`{section}{/section}`](../designers/language-builtin-functions/language-function-section.md),
or syntax of logic within an `{if}` tag. If you can\'t find the error, you might have to
open the compiled PHP file and go to the line number to figure out where
the corresponding error is in the template.
```
Warning: Smarty error: unable to read resource: "index.tpl" in...
```
or
```
Warning: Smarty error: unable to read resource: "site.conf" in...
```
Warning: Smarty error: unable to read resource: "index.tpl" in...
or
Warning: Smarty error: unable to read resource: "site.conf" in...
- The [`$template_dir`](#variable.template.dir) is incorrect, doesn\'t
- The [`$template_dir`](../programmers/api-variables/variable-template-dir.md) is incorrect, doesn't
exist or the file `index.tpl` is not in the `templates/` directory
- A [`{config_load}`](#language.function.config.load) function is
within a template (or [`configLoad()`](#api.config.load) has been
called) and either [`$config_dir`](#variable.config.dir) is
- A [`{config_load}`](../designers/language-builtin-functions/language-function-config-load.md) function is
within a template (or [`configLoad()`](../programmers/api-functions/api-config-load.md) has been
called) and either [`$config_dir`](../programmers/api-variables/variable-config-dir.md) is
incorrect, does not exist or `site.conf` is not in the directory.
<!-- -->
```
Fatal error: Smarty error: the $compile_dir 'templates_c' does not exist,
or is not a directory...
```
Fatal error: Smarty error: the $compile_dir 'templates_c' does not exist,
or is not a directory...
- Either the [`$compile_dir`](#variable.compile.dir)is incorrectly
- Either the [`$compile_dir`](../programmers/api-variables/variable-compile-dir.md)is incorrectly
set, the directory does not exist, or `templates_c` is a file and
not a directory.
<!-- -->
Fatal error: Smarty error: unable to write to $compile_dir '....
```
Fatal error: Smarty error: unable to write to $compile_dir '....
```
- The [`$compile_dir`](#variable.compile.dir) is not writable by the
- The [`$compile_dir`](../programmers/api-variables/variable-compile-dir.md) is not writable by the
web server. See the bottom of the [installing
smarty](#installing.smarty.basic) page for more about permissions.
<!-- -->
Fatal error: Smarty error: the $cache_dir 'cache' does not exist,
or is not a directory. in /..
smarty](../getting-started.md#installation) page for more about permissions.
```
Fatal error: Smarty error: the $cache_dir 'cache' does not exist,
or is not a directory. in /..
```
- This means that [`$caching`](#variable.caching) is enabled and
either; the [`$cache_dir`](#variable.cache.dir) is incorrectly set,
- This means that [`$caching`](../programmers/api-variables/variable-caching.md) is enabled and
either; the [`$cache_dir`](../programmers/api-variables/variable-cache-dir.md) is incorrectly set,
the directory does not exist, or `cache/` is a file and not a
directory.
<!-- -->
```
Fatal error: Smarty error: unable to write to $cache_dir '/...
```
Fatal error: Smarty error: unable to write to $cache_dir '/...
- This means that [`$caching`](#variable.caching) is enabled and the
[`$cache_dir`](#variable.cache.dir) is not writable by the web
- This means that [`$caching`](../programmers/api-variables/variable-caching.md) is enabled and the
[`$cache_dir`](../programmers/api-variables/variable-cache-dir.md) is not writable by the web
server. See the bottom of the [installing
smarty](#installing.smarty.basic) page for permissions.
smarty](../getting-started.md#installation) page for permissions.
<!-- -->
Warning: filemtime(): stat failed for /path/to/smarty/cache/3ab50a623e65185c49bf17c63c90cc56070ea85c.one.tpl.php
in /path/to/smarty/libs/sysplugins/smarty_resource.php
```
Warning: filemtime(): stat failed for /path/to/smarty/cache/3ab50a623e65185c49bf17c63c90cc56070ea85c.one.tpl.php
in /path/to/smarty/libs/sysplugins/smarty_resource.php
```
- This means that your application registered a custom error handler
(using [set\_error\_handler()](https://www.php.net/set_error_handler))
(using [set_error_handler()](https://www.php.net/set_error_handler))
which is not respecting the given `$errno` as it should. If, for
whatever reason, this is the desired behaviour of your custom error
handler, please call
[`muteExpectedErrors()`](#api.mute.expected.errors) after you\'ve
[`muteExpectedErrors()`](../programmers/api-functions/api-mute-expected-errors.md) after you've
registered your custom error handler.
See also [debugging](#chapter.debugging.console).
See also [debugging](../designers/chapter-debugging-console.md).

3
docs/designers/chapter-debugging-console.md
View File

@ -1,5 +1,4 @@
Debugging Console {#chapter.debugging.console}
=================
# Debugging Console
There is a debugging console included with Smarty. The console informs
you of all the [included](./language-builtin-functions/language-function-include.md) templates,

53
docs/designers/config-files.md
View File

@ -1,5 +1,4 @@
Config Files {#config.files}
============
# Config Files
Config files are handy for designers to manage global template variables
from one file. One example is template colors. Normally if you wanted to
@ -8,39 +7,38 @@ each and every template file and change the colors. With a config file,
the colors can be kept in one place, and only one file needs to be
updated.
```ini
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
tableBgColor = #000000
rowBgColor = #00ff00
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
tableBgColor = #000000
rowBgColor = #00ff00
[Customer]
pageTitle = "Customer Info"
[Customer]
pageTitle = "Customer Info"
[Login]
pageTitle = "Login"
focus = "username"
Intro = """This is a value that spans more
than one line. you must enclose
it in triple quotes."""
# hidden section
[.Database]
host=my.example.com
db=ADDRESSBOOK
user=php-user
pass=foobar
[Login]
pageTitle = "Login"
focus = "username"
Intro = """This is a value that spans more
than one line. you must enclose
it in triple quotes."""
# hidden section
[.Database]
host=my.example.com
db=ADDRESSBOOK
user=php-user
pass=foobar
```
Values of [config file variables](./language-variables/language-config-variables.md) can be in
quotes, but not necessary. You can use either single or double quotes.
If you have a value that spans more than one line, enclose the entire
value with triple quotes (\"\"\"). You can put comments into config
value with triple quotes \("""\). You can put comments into config
files by any syntax that is not a valid config file syntax. We recommend
using a `
#` (hash) at the beginning of the line.
using a `#` (hash) at the beginning of the line.
The example config file above has two sections. Section names are
enclosed in \[brackets\]. Section names can be arbitrary strings not
@ -54,8 +52,7 @@ the last one will be used unless
[`$config_overwrite`](../programmers/api-variables/variable-config-overwrite.md) is disabled.
Config files are loaded into templates with the built-in template
function [`
{config_load}`](./language-builtin-functions/language-function-config-load.md) or the API
function [`{config_load}`](./language-builtin-functions/language-function-config-load.md) or the API
[`configLoad()`](../programmers/api-functions/api-config-load.md) function.
You can hide variables or entire sections by prepending the variable

22
docs/designers/language-basic-syntax.md → docs/designers/language-basic-syntax/index.md
View File

@ -1,8 +1,7 @@
Basic Syntax
============
# Basic Syntax
A simple Smarty template could look like this:
```html
```smarty
<h1>{$title|escape}</h1>
<ul>
{foreach $cities as $city}
@ -15,7 +14,7 @@ A simple Smarty template could look like this:
All Smarty template tags are enclosed within delimiters. By default
these are `{` and `}`, but they can be
[changed](../programmers/api-variables/variable-left-delimiter.md).
[changed](../../programmers/api-variables/variable-left-delimiter.md).
For the examples in this manual, we will assume that you are using the
default delimiters. In Smarty, all content outside of delimiters is
@ -24,10 +23,11 @@ template tags, it attempts to interpret them, and displays the
appropriate output in their place.
The basis components of the Smarty syntax are:
- [Comments](./language-basic-syntax/language-syntax-comments.md)
- [Variables](./language-basic-syntax/language-syntax-variables.md)
- [Functions](./language-basic-syntax/language-syntax-functions.md)
- [Attributes](./language-basic-syntax/language-syntax-attributes.md)
- [Quotes](./language-basic-syntax/language-syntax-quotes.md)
- [Math](./language-basic-syntax/language-math.md)
- [Escaping](./language-basic-syntax/language-escaping.md)
- [Comments](language-syntax-comments.md)
- [Variables](language-syntax-variables.md)
- [Functions](language-syntax-functions.md)
- [Attributes](language-syntax-attributes.md)
- [Quotes](language-syntax-quotes.md)
- [Math](language-math.md)
- [Escaping](language-escaping.md)

3
docs/designers/language-basic-syntax/language-escaping.md
View File

@ -1,5 +1,4 @@
Escaping Smarty Parsing {#language.escaping}
=======================
# Escaping Smarty Parsing
It is sometimes desirable or even necessary to have Smarty ignore
sections it would otherwise parse. A classic example is embedding

38
docs/designers/language-builtin-functions.md
View File

@ -1,38 +0,0 @@
Built-in Functions {#language.builtin.functions}
==================
## Table of contents
- [{$var=...}](./language-builtin-functions/language-function-shortform-assign.md)
- [{append}](./language-builtin-functions/language-function-append.md)
- [{assign}](./language-builtin-functions/language-function-assign.md)
- [{block}](./language-builtin-functions/language-function-block.md)
- [{call}](./language-builtin-functions/language-function-call.md)
- [{capture}](./language-builtin-functions/language-function-capture.md)
- [{config_load}](./language-builtin-functions/language-function-config-load.md)
- [{debug}](./language-builtin-functions/language-function-debug.md)
- [{extends}](./language-builtin-functions/language-function-extends.md)
- [{for}](./language-builtin-functions/language-function-for.md)
- [{foreach},{foreachelse}](./language-builtin-functions/language-function-foreach.md)
- [{function}](./language-builtin-functions/language-function-function.md)
- [{if},{elseif},{else}](./language-builtin-functions/language-function-if.md)
- [{include}](./language-builtin-functions/language-function-include.md)
- [{insert}](./language-builtin-functions/language-function-insert.md)
- [{ldelim},{rdelim}](./language-builtin-functions/language-function-ldelim.md)
- [{literal}](./language-builtin-functions/language-function-literal.md)
- [{nocache}](./language-builtin-functions/language-function-nocache.md)
- [{section},{sectionelse}](./language-builtin-functions/language-function-section.md)
- [{setfilter}](./language-builtin-functions/language-function-setfilter.md)
- [{strip}](./language-builtin-functions/language-function-strip.md)
- [{while}](./language-builtin-functions/language-function-while.md)
Smarty comes with several built-in functions. These built-in functions
are the integral part of the smarty template engine. They are compiled
into corresponding inline PHP code for maximum performance.
You cannot create your own [custom
functions](./language-custom-functions.md) with the same name; and you
should not need to modify the built-in functions.
A few of these functions have an `assign` attribute which collects the
result the function to a named template variable instead of being
output; much like the [`{assign}`](./language-builtin-functions/language-function-assign.md) function.

35
docs/designers/language-builtin-functions/index.md Normal file
View File

@ -0,0 +1,35 @@
# Built-in Functions
Smarty comes with several built-in functions. These built-in functions
are the integral part of the smarty template engine. They are compiled
into corresponding inline PHP code for maximum performance.
You cannot create your own [custom functions](../language-custom-functions.md) with the same name; and you
should not need to modify the built-in functions.
A few of these functions have an `assign` attribute which collects the
result the function to a named template variable instead of being
output; much like the [`{assign}`](language-function-assign.md) function.
- [{append}](language-function-append.md)
- [{assign}](language-function-assign.md) or [{$var=...}](language-function-shortform-assign.md)
- [{block}](language-function-block.md)
- [{call}](language-function-call.md)
- [{capture}](language-function-capture.md)
- [{config_load}](language-function-config-load.md)
- [{debug}](language-function-debug.md)
- [{extends}](language-function-extends.md)
- [{for}](language-function-for.md)
- [{foreach}, {foreachelse}](language-function-foreach.md)
- [{function}](language-function-function.md)
- [{if}, {elseif}, {else}](language-function-if.md)
- [{include}](language-function-include.md)
- [{insert}](language-function-insert.md)
- [{ldelim}, {rdelim}](language-function-ldelim.md)
- [{literal}](language-function-literal.md)
- [{nocache}](language-function-nocache.md)
- [{section}, {sectionelse}](language-function-section.md)
- [{setfilter}](language-function-setfilter.md)
- [{strip}](language-function-strip.md)
- [{while}](language-function-while.md)

52
docs/designers/language-builtin-functions/language-function-append.md
View File

@ -1,42 +1,42 @@
{append} {#language.function.append}
========
# {append}
`{append}` is used for creating or appending template variable arrays
**during the execution of a template**.
## Attributes
| Attribute | Required | Description |
|-----------|------------|----------------------------------------------------------------------------------------------------|
| var | | The name of the variable being assigned |
| value | | The value being assigned |
| index | (optional) | The index for the new array element. If not specified the value is append to the end of the array. |
| scope | (optional) | The scope of the assigned variable: parent, root or global. Defaults to local if omitted. |
## Option Flags
| Name | Description |
|---------|-----------------------------------------------------|
| nocache | Assigns the variable with the 'nocache' attribute |
> **Note**
>
> Assignment of variables in-template is essentially placing application
> logic into the presentation that may be better handled in PHP. Use at
> your own discretion.
**Attributes:**
## Examples
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- ----------------------------------------------------------------------------------------------------
var string Yes *n/a* The name of the variable being assigned
value string Yes *n/a* The value being assigned
index string No *n/a* The index for the new array element. If not specified the value is append to the end of the array.
scope string No *n/a* The scope of the assigned variable: \'parent\',\'root\' or \'global\'
**Option Flags:**
Name Description
--------- -----------------------------------------------------
nocache Assigns the variable with the \'nocache\' attribute
{append var='name' value='Bob' index='first'}
{append var='name' value='Meyer' index='last'}
// or
{append 'name' 'Bob' index='first'} {* short-hand *}
{append 'name' 'Meyer' index='last'} {* short-hand *}
The first name is {$name.first}.<br>
The last name is {$name.last}.
```smarty
{append var='name' value='Bob' index='first'}
{append var='name' value='Meyer' index='last'}
// or
{append 'name' 'Bob' index='first'} {* short-hand *}
{append 'name' 'Meyer' index='last'} {* short-hand *}
The first name is {$name.first}.<br>
The last name is {$name.last}.
```
The above example will output:

179
docs/designers/language-builtin-functions/language-function-assign.md
View File

@ -1,148 +1,147 @@
{assign} {#language.function.assign}
========
# {assign}, {$var=...}
`{assign}` is used for assigning template variables **during the
`{assign}` or `{$var=...}` is used for assigning template variables **during the
execution of a template**.
## Attributes of the {assign} syntax
| Attribute Name | Required | Description |
|----------------|------------|-----------------------------------------------------------------------|
| var | | The name of the variable being assigned |
| value | | The value being assigned |
| scope | (optional) | The scope of the assigned variable: \'parent\',\'root\' or \'global\' |
## Attributes of the {$var=...} syntax
| Attribute Name | Required | Description |
|----------------|------------|-----------------------------------------------------------------------|
| scope | (optional) | The scope of the assigned variable: \'parent\',\'root\' or \'global\' |
## Option Flags
| Name | Description |
|---------|---------------------------------------------------|
| nocache | Assigns the variable with the 'nocache' attribute |
> **Note**
>
> Assignment of variables in-template is essentially placing application
> logic into the presentation that may be better handled in PHP. Use at
> your own discretion.
> **Note**
>
> See also the [`short-form`](#language.function.shortform.assign)
> method of assigning template vars.
## Examples
**Attributes:**
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- -----------------------------------------------------------------------
var string Yes *n/a* The name of the variable being assigned
value string Yes *n/a* The value being assigned
scope string No *n/a* The scope of the assigned variable: \'parent\',\'root\' or \'global\'
**Option Flags:**
Name Description
--------- -----------------------------------------------------
nocache Assigns the variable with the \'nocache\' attribute
{assign var="name" value="Bob"}
{assign "name" "Bob"} {* short-hand *}
The value of $name is {$name}.
```smarty
{assign var="name" value="Bob"} {* or *}
{assign "name" "Bob"} {* short-hand, or *}
{$name='Bob'}
The value of $name is {$name}.
```
The above example will output:
The value of $name is Bob.
```
The value of $name is Bob.
```
{assign var="name" value="Bob" nocache}
{assign "name" "Bob" nocache} {* short-hand *}
The value of $name is {$name}.
```smarty
{assign var="name" value="Bob" nocache} {* or *}
{assign "name" "Bob" nocache} {* short-hand, or *}
{$name='Bob' nocache}
The value of $name is {$name}.
```
The above example will output:
The value of $name is Bob.
```
The value of $name is Bob.
```
{assign var=running_total value=$running_total+$some_array[$row].some_value}
```smarty
{assign var=running_total value=$running_total+$some_array[$row].some_value} {* or *}
{$running_total=$running_total+$some_array[row].some_value}
```
Variables assigned in the included template will be seen in the
including template.
```smarty
{include file="sub_template.tpl"}
{include file="sub_template.tpl"}
...
{* display variable assigned in sub_template *}
{$foo}<br>
...
{* display variable assigned in sub_template *}
{$foo}<br>
```
The template above includes the example `sub_template.tpl` below:
The template above includes the example `sub_template.tpl` below
```smarty
{* foo will be known also in the including template *}
{assign var="foo" value="something" scope=parent}
{$foo="something" scope=parent}
...
{* foo will be known also in the including template *}
{assign var="foo" value="something" scope=parent}
{* bar is assigned only local in the including template *}
{assign var="bar" value="value"}
...
{* bar is assigned only local in the including template *}
{assign var="bar" value="value"} {* or *}
{$var="value"}
```
You can assign a variable to root of the current root tree. The variable
is seen by all templates using the same root tree.
{assign var=foo value="bar" scope="root"}
```smarty
{assign var=foo value="bar" scope="root"}
```
A global variable is seen by all templates.
{assign var=foo value="bar" scope="global"}
{assign "foo" "bar" scope="global"} {* short-hand *}
```smarty
{assign var=foo value="bar" scope="global"} {* or *}
{assign "foo" "bar" scope="global"} {* short-hand, or *}
{$foo="bar" scope="global"}
```
To access `{assign}` variables from a php script use
[`getTemplateVars()`](#api.get.template.vars). Here\'s the template that
creates the variable `$foo`.
[`getTemplateVars()`](../../programmers/api-functions/api-get-template-vars.md).
Here's the template that creates the variable `$foo`.
{assign var="foo" value="Smarty"}
```smarty
{assign var="foo" value="Smarty"} {* or *}
{$foo="Smarty"}
```
The template variables are only available after/during template
execution as in the following script.
```php
<?php
<?php
// this will output nothing as the template has not been executed
echo $smarty->getTemplateVars('foo');
// this will output nothing as the template has not been executed
echo $smarty->getTemplateVars('foo');
// fetch the template to a variable
$whole_page = $smarty->fetch('index.tpl');
// fetch the template to a variable
$whole_page = $smarty->fetch('index.tpl');
// this will output 'smarty' as the template has been executed
echo $smarty->getTemplateVars('foo');
// this will output 'smarty' as the template has been executed
echo $smarty->getTemplateVars('foo');
$smarty->assign('foo','Even smarter');
$smarty->assign('foo','Even smarter');
// this will output 'Even smarter'
echo $smarty->getTemplateVars('foo');
```
// this will output 'Even smarter'
echo $smarty->getTemplateVars('foo');
?>
The following functions can also *optionally* assign template variables.
[`{capture}`](#language.function.capture),
The following functions can also *optionally* assign template variables: [`{capture}`](#language.function.capture),
[`{include}`](#language.function.include),
[`{insert}`](#language.function.insert),
[`{counter}`](#language.function.counter),
[`{cycle}`](#language.function.cycle),
[`{eval}`](#language.function.eval),
[`{fetch}`](#language.function.fetch),
[`{math}`](#language.function.math),
[`{textformat}`](#language.function.textformat)
[`{math}`](#language.function.math) and
[`{textformat}`](#language.function.textformat).
See also [`{$var=...}`](#language.function.shortform.assign),
See also [`{append}`](./language-function-append.md),
[`assign()`](#api.assign) and
[`getTemplateVars()`](#api.get.template.vars).

118
docs/designers/language-builtin-functions/language-function-block.md
View File

@ -1,9 +1,8 @@
{block} {#language.function.block}
=======
# {block}
`{block}` is used to define a named area of template source for template
inheritance. For details see section of [Template
Inheritance](#advanced.features.template.inheritance).
Inheritance](../../programmers/advanced-features/advanced-features-template-inheritance.md).
The `{block}` template source area of a child template will replace the
corresponding areas in the parent template(s).
@ -11,181 +10,192 @@ corresponding areas in the parent template(s).
Optionally `{block}` areas of child and parent templates can be merged
into each other. You can append or prepend the parent `{block}` content
by using the `append` or `prepend` option flag with the child's `{block}`
definition. With the {\$smarty.block.parent} the `{block}` content of
definition. With `{$smarty.block.parent}` the `{block}` content of
the parent template can be inserted at any location of the child
`{block}` content. {\$smarty.block.child} inserts the `{block}` content
`{block}` content. `{$smarty.block.child}` inserts the `{block}` content
of the child template at any location of the parent `{block}`.
`{blocks}'s` can be nested.
**Attributes:**
## Attributes
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- ---------------------------------------
name string Yes *n/a* The name of the template source block
| Attribute Name | Required | Description |
|----------------|----------|----------------------------------------------------------------------------------------------------------------------|
| name | yes | The name of the template source block |
| assign | no | The name of variable to assign the output of the block to. |
**Option Flags (in child templates only):**
> **Note**
>
> The assign attribute only works on the block that actually gets executed, so you may need
> to add it to each child block as well.
Name Description
--------- -------------------------------------------------------------------------------------------
append The `{block}` content will be be appended to the content of the parent template `{block}`
prepend The `{block}` content will be prepended to the content of the parent template `{block}`
hide Ignore the block content if no child block of same name is existing.
nocache Disables caching of the `{block}` content
## Option Flags (in child templates only):
| Name | Description |
|---------|-----------------------------------------------------------------------------------------|
| append | The `{block}` content will be appended to the content of the parent template `{block}` |
| prepend | The `{block}` content will be prepended to the content of the parent template `{block}` |
| hide | Ignore the block content if no child block of same name is existing. |
| nocache | Disables caching of the `{block}` content |
## Examples
parent.tpl
```smarty
<html>
<head>
<title>{block name="title"}Default Title{/block}</title>
<title>{block "title"}Default Title{/block}</title> {* short-hand *}
</head>
</html>
```
child.tpl
```smarty
{extends file="parent.tpl"}
{block name="title"}
Page Title
{/block}
```
The result would look like
```html
<html>
<head>
<title>Page Title</title>
</head>
</html>
```
parent.tpl
```smarty
<html>
<head>
<title>{block name="title"}Title - {/block}</title>
</head>
</html>
```
child.tpl
```smarty
{extends file="parent.tpl"}
{block name="title" append}
Page Title
Page Title
{/block}
```
The result would look like
```html
<html>
<head>
<title>Title - Page Title</title>
</head>
</html>
```
parent.tpl
```smarty
<html>
<head>
<title>{block name="title"} is my title{/block}</title>
</head>
</html>
```
child.tpl
```smarty
{extends file="parent.tpl"}
{block name="title" prepend}
Page Title
{/block}
```
The result would look like
```html
<html>
<head>
<title>Page title is my titel</title>
</head>
</html>
```
parent.tpl
```smarty
<html>
<head>
<title>{block name="title"}The {$smarty.block.child} was inserted here{/block}</title>
</head>
</html>
```
child.tpl
```smarty
{extends file="parent.tpl"}
{block name="title"}
Child Title
Child Title
{/block}
```
The result would look like
```html
<html>
<head>
<title>The Child Title was inserted here</title>
</head>
</html>
```
parent.tpl
```smarty
<html>
<head>
<title>{block name="title"}Parent Title{/block}</title>
</head>
</html>
```
child.tpl
```smarty
{extends file="parent.tpl"}
{block name="title"}
You will see now - {$smarty.block.parent} - here
You will see now - {$smarty.block.parent} - here
{/block}
```
The result would look like
```html
<html>
<head>
<title>You will see now - Parent Title - here</title>
</head>
</html>
```
See also [Template
Inheritance](#advanced.features.template.inheritance),
[`$smarty.block.parent`](#language.variables.smarty.block.parent),
[`$smarty.block.child`](#language.variables.smarty.block.child), and
[`{extends}`](#language.function.extends)
Inheritance](../../programmers/advanced-features/advanced-features-template-inheritance.md),
[`$smarty.block.parent`](../language-variables/language-variables-smarty.md#smartyblockparent-languagevariablessmartyblockparent),
[`$smarty.block.child`](../language-variables/language-variables-smarty.md#smartyblockchild-languagevariablessmartyblockchild), and
[`{extends}`](./language-function-extends.md)

45
docs/designers/language-builtin-functions/language-function-call.md
View File

@ -1,39 +1,41 @@
{call} {#language.function.call}
======
# {call}
`{call}` is used to call a template function defined by the
[`{function}`](#language.function.function) tag just like a plugin
[`{function}`](./language-function-function.md) tag just like a plugin
function.
> **Note**
>
> Template functions are defined global. Since the Smarty compiler is a
> single-pass compiler, The [`{call}`](#language.function.call) tag must
> single-pass compiler, The `{call}` tag must
> be used to call a template function defined externally from the given
> template. Otherwise you can directly use the function as
> `{funcname ...}` in the template.
- The `{call}` tag must have the `name` attribute which contains the
the name of the template function.
name of the template function.
- Values for variables can be passed to the template function as
[attributes](#language.syntax.attributes).
[attributes](../language-basic-syntax/language-syntax-attributes.md).
**Attributes:**
## Attributes
Attribute Name Type Required Default Description
---------------- -------------- ---------- --------- ------------------------------------------------------------------------------------------
name string Yes *n/a* The name of the template function
assign string No *n/a* The name of the variable that the output of called template function will be assigned to
\[var \...\] \[var type\] No *n/a* variable to pass local to template function
| Attribute Name | Required | Description |
|----------------|----------|------------------------------------------------------------------------------------------|
| name | Yes | The name of the template function |
| assign | No | The name of the variable that the output of called template function will be assigned to |
| [var ...] | No | variable to pass local to template function |
**Option Flags:**
## Option Flags
Name Description
--------- --------------------------------------------
nocache Call the template function in nocache mode
| Name | Description |
|---------|--------------------------------------------|
| nocache | Call the template function in nocache mode |
## Examples
```smarty
{* define the function *}
{function name=menu level=0}
<ul class="level{$level}">
@ -55,12 +57,12 @@ function.
{* run the array through the function *}
{call name=menu data=$menu}
{call menu data=$menu} {* short-hand *}
```
Will generate the following output
```
* item1
* item2
* item3
@ -70,7 +72,6 @@ Will generate the following output
+ item3-3-1
+ item3-3-2
* item4
```
See also [`{function}`](#language.function.function)
See also [`{function}`](./language-function-function.md).

87
docs/designers/language-builtin-functions/language-function-capture.md
View File

@ -1,5 +1,4 @@
{capture} {#language.function.capture}
=========
# {capture}
`{capture}` is used to collect the output of the template between the
tags into a variable instead of displaying it. Any content between
@ -7,26 +6,26 @@ tags into a variable instead of displaying it. Any content between
specified in the `name` attribute.
The captured content can be used in the template from the variable
[`$smarty.capture.foo`](#language.variables.smarty.capture) where "foo"
[`$smarty.capture.foo`](../language-variables/language-variables-smarty.md#smartycapture-languagevariablessmartycapture) where "foo"
is the value passed in the `name` attribute. If you do not supply the
`name` attribute, then "default" will be used as the name ie
`$smarty.capture.default`.
`{capture}'s` can be nested.
**Attributes:**
## Attributes
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- ----------------------------------------------------------------------
name string Yes *n/a* The name of the captured block
assign string No *n/a* The variable name where to assign the captured output to
append string No *n/a* The name of an array variable where to append the captured output to
| Attribute Name | Required | Description |
|----------------|----------|----------------------------------------------------------------------|
| name | Yes | The name of the captured block |
| assign | No | The variable name where to assign the captured output to |
| append | No | The name of an array variable where to append the captured output to |
**Option Flags:**
## Option Flags
Name Description
--------- -----------------------------------------
nocache Disables caching of this captured block
| Name | Description |
|---------|-----------------------------------------|
| nocache | Disables caching of this captured block |
> **Note**
>
@ -35,48 +34,48 @@ is the value passed in the `name` attribute. If you do not supply the
> [`{insert}`](#language.function.insert) commands that you expect to
> run within cached content, do not capture this content.
## Examples
{* we don't want to print a div tag unless content is displayed *}
{capture name="banner"}
{capture "banner"} {* short-hand *}
{include file="get_banner.tpl"}
{/capture}
{if $smarty.capture.banner ne ""}
<div id="banner">{$smarty.capture.banner}</div>
{/if}
```smarty
{* we don't want to print a div tag unless content is displayed *}
{capture name="banner"}
{capture "banner"} {* short-hand *}
{include file="get_banner.tpl"}
{/capture}
{if $smarty.capture.banner ne ""}
<div id="banner">{$smarty.capture.banner}</div>
{/if}
```
This example demonstrates the capture function.
```smarty
{capture name=some_content assign=popText}
{capture some_content assign=popText} {* short-hand *}
The server is {$my_server_name|upper} at {$my_server_addr}<br>
Your ip is {$my_ip}.
{/capture}
<a href="#">{$popText}</a>
{capture name=some_content assign=popText}
{capture some_content assign=popText} {* short-hand *}
The server is {$my_server_name|upper} at {$my_server_addr}<br>
Your ip is {$my_ip}.
{/capture}
<a href="#">{$popText}</a>
```
This example also demonstrates how multiple calls of capture can be used
to create an array with captured content.
{capture append="foo"}hello{/capture}I say just {capture append="foo"}world{/capture}
{foreach $foo as $text}{$text} {/foreach}
```smarty
{capture append="foo"}hello{/capture}I say just {capture append="foo"}world{/capture}
{foreach $foo as $text}{$text} {/foreach}
```
The above example will output:
I say just hello world
```
I say just hello world
```
See also [`$smarty.capture`](#language.variables.smarty.capture),
[`{eval}`](#language.function.eval),
[`{fetch}`](#language.function.fetch), [`fetch()`](#api.fetch) and
[`{assign}`](#language.function.assign).
See also [`$smarty.capture`](../language-variables/language-variables-smarty.md#smartycapture-languagevariablessmartycapture),
[`{eval}`](./language-function-eval.md),
[`{fetch}`](./language-function-fetch.md), [`fetch()`](../../programmers/api-functions/api-fetch.md) and
[`{assign}`](./language-function-assign.md).

108
docs/designers/language-builtin-functions/language-function-config-load.md
View File

@ -1,56 +1,52 @@
{config\_load} {#language.function.config.load}
==============
# {config_load}
`{config_load}` is used for loading config
[`#variables#`](#language.config.variables) from a [configuration
file](#config.files) into the template.
[`#variables#`](#language.config.variables) from a [configuration file](#config.files) into the template.
**Attributes:**
## Attributes
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
file string Yes *n/a* The name of the config file to include
section string No *n/a* The name of the section to load
scope string no *local* How the scope of the loaded variables are treated, which must be one of local, parent or global. local means variables are loaded into the local template context. parent means variables are loaded into both the local context and the parent template that called it. global means variables are available to all templates.
| Attribute Name | Required | Description |
|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| file | Yes | The name of the config file to include |
| section | No | The name of the section to load |
| scope | no | How the scope of the loaded variables are treated, which must be one of local, parent or global. local means variables are loaded into the local template context. parent means variables are loaded into both the local context and the parent template that called it. global means variables are available to all templates. |
The `example.conf` file.
```ini
#this is config file comment
#this is config file comment
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
tableBgColor = #000000
rowBgColor = #00ff00
#customer variables section
[Customer]
pageTitle = "Customer Info"
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
tableBgColor = #000000
rowBgColor = #00ff00
#customer variables section
[Customer]
pageTitle = "Customer Info"
```
and the template
```smarty
{config_load file="example.conf"}
{config_load "example.conf"} {* short-hand *}
{config_load file="example.conf"}
{config_load "example.conf"} {* short-hand *}
<html>
<html>
<title>{#pageTitle#|default:"No title"}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
</html>
```
[Config Files](#config.files) may also contain sections. You can load
variables from within a section with the added attribute `section`. Note
that global config variables are always loaded along with section
@ -59,33 +55,31 @@ variables, and same-named section variables overwrite the globals.
> **Note**
>
> Config file *sections* and the built-in template function called
> [`{section}`](#language.function.section) have nothing to do with each
> [`{section}`](../language-builtin-functions/language-function-section.md) have nothing to do with each
> other, they just happen to share a common naming convention.
```smarty
{config_load file='example.conf' section='Customer'}
{config_load 'example.conf' 'Customer'} {* short-hand *}
{config_load file='example.conf' section='Customer'}
{config_load 'example.conf' 'Customer'} {* short-hand *}
<html>
<html>
<title>{#pageTitle#}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
</html>
```
See [`$config_overwrite`](#variable.config.overwrite) to create arrays
See [`$config_overwrite`](../../programmers/api-variables/variable-config-overwrite.md) to create arrays
of config file variables.
See also the [config files](#config.files) page, [config
variables](#language.config.variables) page,
[`$config_dir`](#variable.config.dir),
[`getConfigVars()`](#api.get.config.vars) and
[`configLoad()`](#api.config.load).
See also the [config files](../config-files.md) page, [config variables](../language-variables/language-config-variables.md) page,
[`$config_dir`](../../programmers/api-variables/variable-config-dir.md),
[`getConfigVars()`](../../programmers/api-functions/api-get-config-vars.md) and
[`configLoad()`](../../programmers/api-functions/api-config-load.md).

9
docs/designers/language-builtin-functions/language-function-debug.md
View File

@ -1,10 +1,9 @@
{debug} {#language.function.debug}
=======
# {debug}
`{debug}` dumps the debug console to the page. This works regardless of
the [debug](#chapter.debugging.console) settings in the php script.
the [debug](../chapter-debugging-console.md) settings in the php script.
Since this gets executed at runtime, this is only able to show the
[assigned](#api.assign) variables; not the templates that are in use.
[assigned](../../programmers/api-functions/api-assign.md) variables; not the templates that are in use.
However, you can see all the currently available variables within the
scope of a template.
@ -15,4 +14,4 @@ In order to see also the variables which have been locally assigned
within the template it does make sense to place the `{debug}` tag at the
end of the template.
See also the [debugging console page](#chapter.debugging.console).
See also the [debugging console page](../chapter-debugging-console.md).

36
docs/designers/language-builtin-functions/language-function-extends.md
View File

@ -1,9 +1,8 @@
{extends} {#language.function.extends}
=========
# {extends}
`{extends}` tags are used in child templates in template inheritance for
extending parent templates. For details see section of [Template
Inheritance](#advanced.features.template.inheritance).
Inheritance](../../programmers/advanced-features/advanced-features-template-inheritance.md).
- The `{extends}` tag must be on the first line of the template.
@ -11,27 +10,26 @@ Inheritance](#advanced.features.template.inheritance).
tag it may contain only `{block}` tags. Any other template content
is ignored.
- Use the syntax for [template resources](#resources) to extend files
outside of the [`$template_dir`](#variable.template.dir) directory.
- Use the syntax for [template resources](../../programmers/resources.md) to extend files
outside the [`$template_dir`](../../programmers/api-variables/variable-template-dir.md) directory.
## Attributes
| Attribute | Required | Description |
|-----------|----------|-------------------------------------------------|
| file | Yes | The name of the template file which is extended |
> **Note**
>
> When extending a variable parent like `{extends file=$parent_file}`,
> make sure you include `$parent_file` in the
> [`$compile_id`](#variable.compile.id). Otherwise Smarty cannot
> [`$compile_id`](../../programmers/api-variables/variable-compile-id.md). Otherwise, Smarty cannot
> distinguish between different `$parent_file`s.
**Attributes:**
```smarty
{extends file='parent.tpl'}
{extends 'parent.tpl'} {* short-hand *}
```
Attribute Name Type Required Default Description
---------------- -------- ---------- --------- -------------------------------------------------
file string Yes *n/a* The name of the template file which is extended
{extends file='parent.tpl'}
{extends 'parent.tpl'} {* short-hand *}
See also [Template Inheritance](#advanced.features.template.inheritance)
and [`{block}`](#language.function.block).
See also [Template Inheritance](../../programmers/advanced-features/advanced-features-template-inheritance.md)
and [`{block}`](./language-function-block.md).

84
docs/designers/language-builtin-functions/language-function-shortform-assign.md
View File

@ -1,84 +0,0 @@
{\$var=\...} {#language.function.shortform.assign}
============
This is a short-hand version of the {assign} function. You can assign
values directly to the template, or assign values to array elements too.
> **Note**
>
> Assignment of variables in-template is essentially placing application
> logic into the presentation that may be better handled in PHP. Use at
> your own discretion.
The following attributes can be added to the tag:
**Attributes:**
Attribute Name Shorthand Type Required Default Description
---------------- ----------- -------- ---------- --------- -----------------------------------------------------------------------
scope n/a string No *n/a* The scope of the assigned variable: \'parent\',\'root\' or \'global\'
**Option Flags:**
Name Description
--------- -----------------------------------------------------
nocache Assigns the variable with the \'nocache\' attribute
{$name='Bob'}
The value of $name is {$name}.
The above example will output:
The value of $name is Bob.
{$running_total=$running_total+$some_array[row].some_value}
{$user.name="Bob"}
{$user.name.first="Bob"}
{$users[]="Bob"}
Variables assigned in the included template will be seen in the
including template.
{include file="sub_template.tpl"}
...
{* display variable assigned in sub_template *}
{$foo}<br>
...
The template above includes the example `sub_template.tpl` below
...
{* foo will be known also in the including template *}
{$foo="something" scope=parent}
{* bar is assigned only local in the including template *}
{$bar="value"}
...
See also [`{assign}`](#language.function.assign) and
[`{append}`](#language.function.append)

41
docs/designers/language-combining-modifiers.md
View File

@ -1,35 +1,32 @@
Combining Modifiers {#language.combining.modifiers}
===================
# Combining Modifiers
You can apply any number of modifiers to a variable. They will be
applied in the order they are combined, from left to right. They must be
separated with a `|` (pipe) character.
```php
<?php
<?php
$smarty->assign('articleTitle', 'Smokers are Productive, but Death Cuts Efficiency.');
?>
$smarty->assign('articleTitle', 'Smokers are Productive, but Death Cuts Efficiency.');
```
where template is:
{$articleTitle}
{$articleTitle|upper|spacify}
{$articleTitle|lower|spacify|truncate}
{$articleTitle|lower|truncate:30|spacify}
{$articleTitle|lower|spacify|truncate:30:". . ."}
```smarty
{$articleTitle}
{$articleTitle|upper|spacify}
{$articleTitle|lower|spacify|truncate}
{$articleTitle|lower|truncate:30|spacify}
{$articleTitle|lower|spacify|truncate:30:". . ."}
```
The above example will output:
Smokers are Productive, but Death Cuts Efficiency.
S M O K E R S A R ....snip.... H C U T S E F F I C I E N C Y .
s m o k e r s a r ....snip.... b u t d e a t h c u t s...
s m o k e r s a r e p r o d u c t i v e , b u t . . .
s m o k e r s a r e p. . .
```
Smokers are Productive, but Death Cuts Efficiency.
S M O K E R S A R ....snip.... H C U T S E F F I C I E N C Y .
s m o k e r s a r ....snip.... b u t d e a t h c u t s...
s m o k e r s a r e p r o d u c t i v e , b u t . . .
s m o k e r s a r e p. . .
```

4
docs/designers/language-custom-functions.md
View File

@ -1,10 +1,8 @@
Custom Functions {#language.custom.functions}
================
# Custom Functions
Smarty comes with several custom plugin functions that you can use in
the templates.
## Table of contents
- [{counter}](./language-custom-functions/language-function-counter.md)
- [{cycle}](./language-custom-functions/language-function-cycle.md)
- [{eval}](./language-custom-functions/language-function-eval.md)

77
docs/designers/language-modifiers.md
View File

@ -1,7 +1,15 @@
Variable Modifiers {#language.modifiers}
==================
# Variable Modifiers
Variable modifiers can be applied to
[variables](./language-variables.md), [custom functions](./language-custom-functions.md)
or strings. To apply a modifier,
specify the value followed by a `|` (pipe) and the modifier name. A
modifier may accept additional parameters that affect its behavior.
These parameters follow the modifier name and are separated by a `:`
(colon). Also, *all php-functions can be used as modifiers implicitly*
(more below) and modifiers can be
[combined](./language-combining-modifiers.md).
## Table of contents
- [capitalize](./language-modifiers/language-modifier-capitalize.md)
- [cat](./language-modifiers/language-modifier-cat.md)
- [count_characters](./language-modifiers/language-modifier-count-characters.md)
@ -27,59 +35,50 @@ Variable Modifiers {#language.modifiers}
- [upper](./language-modifiers/language-modifier-upper.md)
- [wordwrap](./language-modifiers/language-modifier-wordwrap.md)
Variable modifiers can be applied to
[variables](./language-variables.md), [custom
functions](./language-custom-functions.md) or strings. To apply a modifier,
specify the value followed by a `|` (pipe) and the modifier name. A
modifier may accept additional parameters that affect its behavior.
These parameters follow the modifier name and are separated by a `:`
(colon). Also, *all php-functions can be used as modifiers implicitly*
(more below) and modifiers can be
[combined](./language-combining-modifiers.md).
## Examples
```smarty
{* apply modifier to a variable *}
{$title|upper}
{* apply modifier to a variable *}
{$title|upper}
{* modifier with parameters *}
{$title|truncate:40:"..."}
{* modifier with parameters *}
{$title|truncate:40:"..."}
{* apply modifier to a function parameter *}
{html_table loop=$myvar|upper}
{* apply modifier to a function parameter *}
{html_table loop=$myvar|upper}
{* with parameters *}
{html_table loop=$myvar|truncate:40:"..."}
{* with parameters *}
{html_table loop=$myvar|truncate:40:"..."}
{* apply modifier to literal string *}
{"foobar"|upper}
{* apply modifier to literal string *}
{"foobar"|upper}
{* using date_format to format the current date *}
{$smarty.now|date_format:"%Y/%m/%d"}
{* using date_format to format the current date *}
{$smarty.now|date_format:"%Y/%m/%d"}
{* apply modifier to a custom function *}
{mailto|upper address="smarty@example.com"}
{* apply modifier to a custom function *}
{mailto|upper address="smarty@example.com"}
{* using php's str_repeat *}
{"="|str_repeat:80}
{* using php's str_repeat *}
{"="|str_repeat:80}
{* php's count *}
{$myArray|@count}
{* this will uppercase and truncate the whole array *}
<select name="name_id">
{html_options output=$my_array|upper|truncate:20}
</select>
{* php's count *}
{$myArray|@count}
{* this will uppercase and truncate the whole array *}
<select name="name_id">
{html_options output=$my_array|upper|truncate:20}
</select>
```
- Modifiers can be applied to any type of variables, including arrays
and objects.
> **Note**
>
> The default behavior was changed with Smarty 3. In Smarty 2.x, you
> had to use an \"`@`\" symbol to apply a modifier to an array, such
> as `{$articleTitle|@count}`. With Smarty 3, the \"`@`\" is no
> had to use an "`@`" symbol to apply a modifier to an array, such
> as `{$articleTitle|@count}`. With Smarty 3, the "`@`" is no
> longer necessary, and is ignored.
>
> If you want a modifier to apply to each individual item of an

24
docs/designers/language-variables.md
View File

@ -1,16 +1,13 @@
Variables
=========
# Variables
Smarty has several types of variables. The type of the
variable depends on what symbol it is prefixed or enclosed within.
## Table of contents
- [Variables assigned from PHP](./language-variables/language-assigned-variables.md)
- [Variable scopes](./language-variables/language-variable-scopes.md)
- [Variables loaded from config files](./language-variables/language-config-variables.md)
- [{$smarty} reserved variable](./language-variables/language-variables-smarty.md)
Smarty has several different types of variables. The type of the
variable depends on what symbol it is prefixed or enclosed within.
Variables in Smarty can be either displayed directly or used as
arguments for [functions](./language-basic-syntax/language-syntax-functions.md),
[attributes](./language-basic-syntax/language-syntax-attributes.md) and
@ -19,17 +16,16 @@ To print a variable, simply enclose it in the
[delimiters](../programmers/api-variables/variable-left-delimiter.md) so that it is the only thing
contained between them.
```smarty
{$Name}
{$Name}
{$product.part_no} <b>{$product.description}</b>
{$product.part_no} <b>{$product.description}</b>
{$Contacts[row].Phone}
<body bgcolor="{#bgcolor#}">
{$Contacts[row].Phone}
<body bgcolor="{#bgcolor#}">
```
> **Note**
>
> An easy way to examine assigned Smarty variables is with the

36
docs/getting-started.md
View File

@ -1,26 +1,25 @@
What is Smarty?
==============
# Getting started
## Requirements
Smarty can be run with PHP 7.1 to PHP 8.2.
## Installation
Smarty versions 3.1.11 or later can be installed with [Composer](https://getcomposer.org/).
Smarty can be installed with [Composer](https://getcomposer.org/).
To get the latest stable version of Smarty use:
```bash
```shell
composer require smarty/smarty
````
```
To get the latest, unreleased version, use:
```bash
```shell
composer require smarty/smarty:dev-master
````
```
To get the previous stable version of Smarty, Smarty 3, use:
```bash
```shell
composer require smarty/smarty:^3
````
```
Here's how you create an instance of Smarty in your PHP scripts:
```php
@ -30,7 +29,7 @@ require 'vendor/autoload.php';
$smarty = new Smarty();
```
Now that the library files are in place, it's time to setup the Smarty
Now that the library files are in place, it's time to set up the Smarty
directories for your application.
Smarty requires four directories which are by default named
@ -82,7 +81,7 @@ $smarty->testInstall();
Now, let's create the `index.tpl` file that Smarty will display. This
needs to be located in the [`$template_dir`](./programmers/api-variables/variable-template-dir.md).
```html
```smarty
{* Smarty *}
Hello {$name}, welcome to Smarty!
```
@ -118,24 +117,22 @@ $smarty->display('index.tpl');
> **Note**
>
> In our example, we are setting absolute paths to all of the Smarty
> In our example, we are setting absolute paths to all the Smarty
> directories. If `/web/www.example.com/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.
Now, run your PHP file. You should see *\"Hello Ned, welcome to Smarty!\"*
Now, run your PHP file. You should see *"Hello Ned, welcome to Smarty!"*
You have completed the basic setup for Smarty!
## Extended Setup {#installing.smarty.extended}
==============
## Extended Setup
This is a continuation of the [basic
installation](#installing.smarty.basic), please read that first!
This is a continuation of the [basic installation](#installation), please read that first!
A slightly more flexible way to setup Smarty is to extend the Smarty
A slightly more flexible way to set up Smarty is to extend the Smarty
class and initialize your Smarty
environment. So instead of repeatedly setting directory paths, assigning
the same vars, etc., we can do that in one place.
@ -163,7 +160,8 @@ class Smarty_GuestBook extends Smarty {
Now, we can use `Smarty_GuestBook` instead of `Smarty` in our scripts:
```php
<?php
$smarty = new Smarty_GuestBook();
$smarty->assign('name','Ned');
$smarty->assign('name', 'Ned');
$smarty->display('index.tpl');
```

4
docs/index.md
View File

@ -26,11 +26,11 @@ and 480 for $height, the result is:
- [Getting Started](./getting-started.md)
## Smarty for template designers
- [Basic Syntax](./designers/language-basic-syntax.md)
- [Basic Syntax](designers/language-basic-syntax/language-basic-syntax.md)
- [Variables](./designers/language-variables.md)
- [Variable Modifiers](./designers/language-modifiers.md)
- [Combining Modifiers](./designers/language-combining-modifiers.md)
- [Built-in Functions](./designers/language-builtin-functions.md)
- [Built-in Functions](designers/language-builtin-functions/language-builtin-functions.md)
- [Custom Functions](./designers/language-custom-functions.md)
- [Config Files](./designers/config-files.md)
- [Debugging Console](./designers/chapter-debugging-console.md)

3
docs/philosophy.md
View File

@ -1,5 +1,4 @@
Philosophy
=======
# Philosophy
## What is Smarty?

56
mkdocs.yml
View File

@ -5,6 +5,10 @@ theme:
primary: amber
features:
- content.code.copy
- navigation.tabs
- navigation.tabs.sticky
- navigation.instant
- navigation.tracking
icon:
logo: material/lightbulb-on
favicon: images/favicon.ico
@ -19,3 +23,55 @@ markdown_extensions:
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
nav:
- Home: 'index.md'
- 'Getting started': 'getting-started.md'
- 'Designers':
- 'Basic Syntax':
- Introduction: 'designers/language-basic-syntax/index.md'
- Comments: 'designers/language-basic-syntax/language-syntax-comments.md'
- Variables: 'designers/language-basic-syntax/language-syntax-variables.md'
- Functions: 'designers/language-basic-syntax/language-syntax-functions.md'
- Attributes: 'designers/language-basic-syntax/language-syntax-attributes.md'
- Quotes: 'designers/language-basic-syntax/language-syntax-quotes.md'
- Math: 'designers/language-basic-syntax/language-math.md'
- Escaping: 'designers/language-basic-syntax/language-escaping.md'
- 'designers/language-variables.md'
- 'designers/language-modifiers.md'
- 'designers/language-combining-modifiers.md'
- 'Builtin Functions':
- 'Introduction': 'designers/language-builtin-functions/index.md'
- '{append}': 'designers/language-builtin-functions/language-function-append.md'
- '{assign}': 'designers/language-builtin-functions/language-function-assign.md'
- '{block}': 'designers/language-builtin-functions/language-function-block.md'
- '{call}': 'designers/language-builtin-functions/language-function-call.md'
- '{capture}': 'designers/language-builtin-functions/language-function-capture.md'
- '{config_load}': 'designers/language-builtin-functions/language-function-config-load.md'
- '{debug}': 'designers/language-builtin-functions/language-function-debug.md'
- '{extends}': 'designers/language-builtin-functions/language-function-extends.md'
- '{for}': 'designers/language-builtin-functions/language-function-for.md'
- '{foreach}': 'designers/language-builtin-functions/language-function-foreach.md'
- '{function}': 'designers/language-builtin-functions/language-function-function.md'
- '{if},{elseif},{else}': 'designers/language-builtin-functions/language-function-if.md'
- '{include}': 'designers/language-builtin-functions/language-function-include.md'
- '{insert}': 'designers/language-builtin-functions/language-function-insert.md'
- '{ldelim},{rdelim}': 'designers/language-builtin-functions/language-function-ldelim.md'
- '{literal}': 'designers/language-builtin-functions/language-function-literal.md'
- '{nocache}': 'designers/language-builtin-functions/language-function-nocache.md'
- '{section}': 'designers/language-builtin-functions/language-function-section.md'
- '{setfilter}': 'designers/language-builtin-functions/language-function-setfilter.md'
- '{strip}': 'designers/language-builtin-functions/language-function-strip.md'
- '{while}': 'designers/language-builtin-functions/language-function-while.md'
- 'designers/language-custom-functions.md'
- 'designers/config-files.md'
- 'designers/chapter-debugging-console.md'
- 'Programmers':
- 'programmers/charset.md'
- 'programmers/smarty-constants.md'
- 'programmers/api-variables.md'
- 'programmers/api-functions.md'
- 'programmers/caching.md'
- 'programmers/resources.md'
- 'programmers/advanced-features.md'
- 'programmers/plugins.md'