History: Smarty Templates

            ! Smarty Templates
Tiki uses the Smarty Template Engine to control ((themes)) (mostly the layout, and some design / layout logic).

"One of Smarty's primary design goals is to facilitate the separation of application code from presentation. Typically, the application code contains the business logic of your application, written and maintained in PHP code. This code is maintained by programmers. The presentation is the way your content is presented to the end user, which is written and maintained in template files. The Templates are maintained by template designers."

[http://www.smarty.net/whyuse.php]

Smarty is a "Template/Presentation Framework." It provides the designer with the opportunity to change the presentation of a website by defining variables and using logic (If/else) statements. It can be used for example to create ((WYSIWYCA)) ("what you see is what you can access") websites which show or hide things depending on permissions variables.

!! History
* The very first version of Tiki (October 2002) was using Smarty v2.2.
* Smarty version 3 was introduced in ((Tiki8)) (2011)
* [https://gitlab.com/tikiwiki/tiki/-/merge_requests/1356|Smarty version 4 was introduced] in ((Tiki25)) (2022) (PHP 7.4)
* [https://gitlab.com/tikiwiki/tiki/-/merge_requests/3529|Smarty version 5 was introduced] in ((Tiki27)) (2024) (PHP 8.1 to 8.4) (Expected to be OK until PHP 9.0)
** https://github.com/smarty-php/smarty/discussions/920

!! Default Templates and Custom Templates
The default Smarty template files are in the folder /((Templates)) as .tpl files. They can be edited with any text editor, but it is best to not edit the default version of these templates. 

^Since Tiki 15, if you want to modify a template, copy it and put the copy in the custom theme directory, e.g. themes /__custom_theme_name__/templates (it was /templates/styles/__custom_theme_name__/ prior to Tiki 15).

See ((Themes)) ("How To Create a Custom Theme")  for more details.^

!!! Escaping variables used in Smarty
When modifying templates, it is important to check that variables that display output on screen be escaped except in certain circumstances, to act as a safeguard agains unfiltered user input being displayed back on the page. The question is when to escape and when not to escape? See [http://www.smarty.net/docs/en/language.modifier.escape.tpl]

* If the output of your template will be used in another template __as a variable that will be escaped there__, then there is no need to escape it the first time as it will lead to double escaping.
* If the variable is expected to possibly contain HTML, then it cannot be escaped otherwise the HTML will be displayed as text on screen. In those cases, it is the responsibility of the code that generated the HTML (e.g. the wiki parser to ensure that the HTML output is filtered), and the code of the input user interface to perform filtering in case any user enters any HTML -  only trusted users should be allowed to enter any HTML).
* If the variable is used for redisplaying what the user entered __in an input text field__, then it cannot be escaped otherwise it will lead to double escaping the next time the user submits the form.
* In all other cases, the variable should be escaped using the escape variable.
** Note that if the variable is to be used in a URL, then it must be escaped using the "url" method rather than just the standard method. See [http://www.smarty.net/docs/en/language.modifier.escape.tpl] for more information.

!! Tips
* use the __{literal} {/literal}__ tag to escape Smarty parsing for a block of code, e.g. for a javascript
* __{* comment *}__ is used for commenting in smarty
* __~np~{tr}some text{/tr}~/np~__ is used for strings in the UI that are intended to be translated into other languages (see  ((Internationalization))).
* use the __{wikiplugin} {/wikiplugin}__ tag to include a ((Wiki Plugins|wiki plugin))
+e.g. for nesting ((plugintrackerlist|trackerlist plugins)), use in a trackerlist's template:
+^{wikiplugin _name=trackerlist ignoreRequestItemId=y trackerId=X filterfield=Y filtervalue="{$your_var}"}{/wikiplugin}^
+Note: when a plugin takes values in its __body__, e.g. ((PluginMouseover)), this content should go between the opening and closing __wikiplugin__ tags (this comes from the fact that smarty “block” objects have a body between the open and close tags):
+^{wikiplugin _name=mouseover label='Hello' offsetx='4' offsety='15'}{$your_content}{/wikiplugin}^
* add __&show_smarty_debug=1__ to the real url to inspect smarty variables
+ e.g. ~np~http://www.example.com/tiki-index.php?page=examplepagename&show_smarty_debug=1~/np~
* use __{wiki}wiki syntax here{/wiki}__ to put wiki syntax in smarty templates

!! Samples
!!! Wikiplugin group
The wiki plugin group can be used the same way if you need to set it without an alternative to the condition ({else})
{CODE()}
{wikiplugin _name='group' groups='Admins'}
  I’m a member of the admins group
{/wikiplugin}
{CODE}
However using {ELSE} like you would in the wiki syntax will break the code.
In that case of an alternative to a condition you need to write the condition as follow:
{CODE()}
{if 'Admins'|in_group}
  I’m a member of the admins group
{else}
 I’m not a member of the admins group
{/if}
{CODE}

!!!Using smarty modifier (number format) with data from a pluginList
You can't use directly the modifier ~pp~|number_format~/pp~ in a smarty template on a formatted field from a pluginList.
IE: {CODE()}{$row.prix|number_format}{CODE}
You need to use it on the direct value from the tracker : {CODE()}{$row.tracker_field_catalogueDesBiensPRIX|number_format}{CODE}

!!!Use an URL parameter assigned to a smarty variable
With {$smarty.get.urlParameter} is possible to use an URL parameter directly into your smarty template.
IE: Using a list plugin you generate your URL with an URL parameter like:
~pp~<a href="holidays-camps-childrenList?holiday={$row.tracker_field_holidaysReference}">~/pp~ that will generate
https://yourTiki.com/holidays-camps-childrenList?holidayReference=Christmas

In your smarty template you can reuse then the value to display it or embed a second wikiplugin list
{CODE()}{filter field="tracker_field_holidaycampsNameReference" exact="{/literal}{$smarty.get.holiday}{literal}"}{CODE}

!!!! Using the Tiki language preferences
You can use the selected language to control what is displayed or used in embedded wikiplugin (like an embedded wikiplugin List)

{CODE(wrap="1" caption="Using the language preferences" colors="tiki")}
{if $prefs.language eq fr}Montre ca {else} Show this {/if}
{CODE}

!! See also
* ((PluginSmarty))

!! More information
* [http://www.smarty.net/crashcourse.php]: Crash Course in Smarty
* [http://www.smarty.net/manual/en/]: Smarty Manual
* [https://themes.tiki.org] - a resource for Tiki theme designers. 

!! Alias
* (alias(tpl))
* (alias(Smarty))
* (alias(Smarty Template))