Sourcefabric Manuals

 English |  Español |  Français |  Italiano |  Português |  Русский |  Shqip

Newscoop 4.2 Cookbook

Basic syntax

The Newscoop template engine was built on Smarty, so the Newscoop template language is actually an extension of the Smarty template language. For details of the Smarty template language please read: http://smarty.net/manual/en/smarty.for.designers.php

All template tags are enclosed within delimiters. By default in Smarty these are the single curly brackets { and } but they can be changed. In Newscoop we use the double curly brackets {{ and }} for template tag delimiters.

For the examples in this Cookbook, we will assume that you are using the default Newscoop delimiters. All content outside of delimiters is displayed as static content, or unchanged. When the template engine encounters template tags, it attempts to interpret them, and displays the appropriate output in their place.

The following sub-chapters, which were copied from the Smarty manual, will familiarize you with the Smarty syntax.

Attributes

Most of the functions take attributes that specify or modify their behaviour. Attributes to Smarty functions are much like HTML attributes. Static values don't have to be enclosed in quotes, but it is recommended for literal strings. Variables may also be used, and should not be in quotes.

Some attributes require boolean values (TRUE or FALSE). These can be specified as either unquoted true, on, and yes; or false, off, and no. 

{{include file='header.tpl'}}
{{include file='header.tpl' attrib_name='attrib value'}}
{{include file=$includeFile}}
{{include file=#includeFile# title='Smarty is cool'}}

 {{html_select_date display_days=yes}}
  {{mailto address='smarty@example.com'}}
   <select name='company_id'>
    {{html_options options=$companies selected=$company_id}}
   </select>

Comments

Template comments are surrounded by asterisks, and then surrounded by the delimiter tags like this: 

{{* this is a comment *}}
Comments are NOT displayed in the final output of the template, unlike <!-- HTML comments -->. These are useful for making internal notes in the templates which no one will see.
{{* I am a template comment, I don't exist in the compiled output  *}}
<html>
<head>
<title>{{$title}}</title>
</head>
<body>
{{* another single line comment  *}}
<!-- HTML comment that is sent to the browser -->
{{* this multiline
   comment is
   not sent to browser
*}}
{{*********************************************************
Multi line comment block with credits block
  @ author:         bg@example.com
  @ maintainer:     support@example.com
  @ para:           var that sets block style
  @ css:            the style output
**********************************************************}}
{{* The header file with the main logo and stuff  *}}
{{include file='header.tpl'}}
{{* Dev note:  the $includeFile var is assigned in foo.php script  *}}
<!-- Displays main content block -->
{{include file=$includeFile}}
{{* this <select> block is redundant *}}
{{*
<select name="company">
  {{html_options options=$vals selected=$selected_id}}
</select>
*}}
<!-- Show header from affiliate is disabled -->
{{* $affiliate|upper *}}
{{* you cannot nest comments *}}
{{*
<select name="company">
  {{* <option value="0">-- none -- </option> *}}
  {{html_options options=$vals selected=$selected_id}}
</select>
*}}
{{* cvs tag for a template, below the 36 SHOULD be an american currency
. however its converted in cvs.. *}}
{{* &#36;Id: Exp &#36; *}}
{{* $Id: *}}
</body>
</html>

Embedding vars in double quotes

Smarty will recognize assigned variables embedded in "double quotes" so long as the variable name contains only numbers, letters, under_scores and square brackets []. See the PHP naming documentation at http://php.net/language.variables for more detail.

With any other characters, for example a .period or $object>reference, then the variable must be surrounded by `backticks`.

You cannot embed modifiers, they must always be applied outside of quotes. 

{{func var="test $foo test"}}       <-- sees $foo
{{func var="test $foo_bar test"}}   <-- sees $foo_bar
{{func var="test $foo[0] test"}}    <-- sees $foo[0]
{{func var="test $foo[bar] test"}}  <-- sees $foo[bar]
{{func var="test $foo.bar test"}}   <-- sees $foo (not $foo.bar)
{{func var="test `$foo.bar` test"}} <-- sees $foo.bar
{{func var="test `$foo.bar` test"|escape}} <-- modifiers outside quotes!

Here are some practical examples: 

{{* will replace $tpl_name with value *}}
{{include file="subdir/$tpl_name.tpl"}}

{{* doesn't replace $tpl_name *}}
{{include file='subdir/$tpl_name.tpl'}}

{{* must have backticks as it contains a . *}}
{{cycle values="one,two,`$smarty.config.myval`"}}

{{*  same as $module['contact'].'.tpl' in a php script *}}
{{include file="`$module.contact`.tpl"}}

{{*  same as $module[$view].'.tpl' in a php script *}}
{{include file="$module.$view.tpl"}}

Escaping Smarty parsing

It is sometimes desirable or even necessary to have Smarty ignore sections it would otherwise parse. A classic example is embedding Javascript or CSS code in a template. The problem arises as those languages use the { and } characters which are also the default delimiters for Smarty.

The simplest thing is to avoid the situation altogether by separating your Javascript and CSS code into their own files and then using standard HTML methods to access them.

Including literal content is possible using literal../literal blocks. Similar to HTML entity usage, you can use ldelim, rdelim or $smarty.ldelim to display the current delimiters.

Functions

Every Smarty tag either prints a variable or invokes some sort of function. These are processed and displayed by enclosing the function and its attributes within delimiters like so: funcname attr1='val1' attr2='val2'. 

{{config_load file='colors.conf'}}
{{include file='header.tpl'}}
{{insert file='banner_ads.tpl' title='Smarty is cool'}}
{{if $logged_in}}
    Welcome, <font >{{$name}}!</font>
{{else}}
    hi, {{$name}}
{{/if}}
{{include file='footer.tpl' ad=$random_id}}
  • Both built-in functions and custom functions have the same syntax within templates.
  • Built-in functions are the inner workings of Smarty, such as if, section and strip. There should be no need to change or modify them.
  • Custom functions are additional functions implemented via plugins. They can be modified to your liking, or you can create new ones. html_options and popup are examples of custom functions.

Math

Math can be applied directly to variable values. 

{{$foo+1}}

{{$foo*$bar}}

{{* some more complicated examples *}}

{{$foo->bar-$bar[1]*$baz->foo->bar()-3*7}}

{{if ($foo+$bar.test%$baz*134232+10+$b+10)}}

{{$foo|truncate:"`$fooTruncCount/$barTruncFactor-1`"}}

{{assign var="foo" value="`$foo+$bar`"}}

Variable modifiers

Modifiers can be applied to variables, custom functions 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 behaviour. 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. 

{{* apply modifier to a variable *}}
{{$title|upper}}

{{* modifier with parameters *}}
{{$title|truncate:40:'...'}}

{{* apply modifier to a function parameter *}}
{{html_table loop=$myvar|upper}}

{{* with parameters *}}
{{html_table loop=$myvar|truncate:40:'...'}}

{{* apply modifier to literal string *}}
{{'foobar'|upper}}

{{* 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'}}

{{* using  php's str_repeat *}}
{{'='|str_repeat:80}}

{{* php's count *}}
{{$myArray|@count}}

{{* php's shuffle on servers's ip *}}
{{$smarty.server.SERVER_ADDR|shuffle}}

{{* this will uppercase and truncate the whole array *}}
 <select name="name_id">
  {{html_options output=$myArray|upper|truncate:20}}
 </select>

If you apply a modifier to an array variable instead of a single value variable, the modifier will be applied to every value in that array. If you really want the modifier to work on an entire array as a value, you must prepend the modifier name with an @ symbol.

For example: 

{{$articleTitle|@count}}

will print out the number of elements in the $articleTitle array using the php count() function as a modifier.

Modifiers are autoloaded from the $plugins_dir or can be registered explicitly with the register_modifier() function. The later is useful for sharing a function between PHP scripts and Smarty templates.

All PHP functions can be used as modifiers implicitly, as demonstrated in the example above. However, using PHP functions as modifiers has two little pitfalls:

First - sometimes the order of the function-parameters is not the desirable one. Formatting $foo with {{"%2.f"|sprintf:$foo}} actually works, but asks for the more intuitive, like {{$foo|string_format:"%2.f"}} that is provided by the Smarty distribution.

Secondly - if $security is enabled, all PHP functions that are to be used as modifiers have to be declared trusted in the MODIFIER_FUNCS element of the $security_settings array

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: 

{{$articleTitle}}
{{$articleTitle|upper|spacify}}
{{$articleTitle|lower|spacify|truncate}}
{{$articleTitle|lower|truncate:30|spacify}}
{{$articleTitle|lower|spacify|truncate:30:". . ."}}

Variables

Template variables start with the $dollar sign. They can contain numbers, letters and underscores, much like a PHP variable. You can reference arrays by index numerically or non-numerically. Also reference object properties and methods.

Config file variables are an exception to the $dollar syntax and are instead referenced with surrounding #hashmarks#, or via the $smarty.config variable. 

{{$foo}}        <-- displaying a simple variable (non array/object)

{{$foo[4]}}     <-- display the 5th element of a zero-indexed array

{{$foo.bar}}    <-- display the "bar" key value of an array, similar to PHP $foo['bar']

{{$foo.$bar}}   <-- display variable key value of an array, similar to PHP $foo[$bar]

{{$foo->bar}}   <-- display the object property "bar"

{{$foo->bar()}} <-- display the return value of object method "bar"

{{#foo#}}       <-- display the config file variable "foo"

{{$smarty.config.foo}} <-- synonym for {{#foo#}}

{{$foo[bar]}}   <-- syntax only valid in a section loop, see {{section}}

{{assign var=foo value='baa'}}{{$foo}} <--  displays "baa", see {{assign}}

Many other combinations are allowed: 

{{$foo.bar.baz}}
{{$foo.$bar.$baz}}
{{$foo[4].baz}}
{{$foo[4].$baz}}
{{$foo.bar.baz[4]}}

{{$foo->bar($baz,2,$bar)}} <-- passing parameters

{{"foo"}}       <-- static values are allowed

{{* display the server variable "SERVER_NAME" ($_SERVER['SERVER_NAME'])*}}
{{$smarty.server.SERVER_NAME}}

There has been error in communication with Booktype server. Not sure right now where is the problem.

You should refresh this page.