Diff: Special Smarty Templating/Plugin Features

 Ownership:  rw-rw-r-- Garvin docuteam
 Modified:  18 May 11, 14:38
 Modified by:  Garvin Hicking (Garvin)
Rev.:  16 (Old)
 
 Ownership:  rw-rw-r-- Garvin docuteam
 Modified:  18 May 11, 17:14
 Modified by:  Don Chambers (chambers)
Rev.:  17 (Current)


+ %TITLE%

<toc>

++ Plugins

Inside any Smarty .tpl file you can manually execute certain plugins. You can use these Smarty functions:

+ %TITLE%

<toc>

++ Plugins

Inside any Smarty .tpl file you can manually execute certain plugins. You can use these Smarty functions:

* {serendipity_printSidebar side="left|right|hidden|*"}<br>Returns a sidebar. The "side" parameter specifies which sidebar plugins to fetch. "*" means all plugins.
* {serendipity_printSidebar side="left|right|hidden|*" template="yourtemplate.tpl"}<br>Returns a sidebar. The "side" parameter specifies which sidebar plugins to fetch. "*" means all plugins. The optional "template" parameter specifies the name of the template file used to emit each sidebar. Sidebar.tpl will be used to emit sidebars if custom template file is not specified.

* {serendipity_hookPlugin hook="hookname" hookAll="true|false" data=$eventData addData=$addData}<br>This allows to execute any plugins to call via the Event Plugin API. Using this execution method you can also execute your own created event hooks. The "hook" parameter specifies the used hook name, if "hookAll" is set to true, any plugin hook can executed. If it is not set or set to false, only the hooks "frontend_header", "entries_header", "entries_footer" and "frontend_comment" can be executed via Smarty. Via the "data" and "addData" variables you can pass custom variables to the PHP Plugin API functions.

* {serendipity_showPlugin class="serendipity_your_nugget" id="serendipity_your_plugin:21323223efsd22aa" side="left|right|hidden|*" negate="null|true"}<br>This allows to emit any sidebar plugin at your choses location. Either specify the "class" or "id" parameter (NOT both!) to indicate which plugin(s) should be called. The "class" attributes specifies a Plugin classname like serendipity_plugin_flickr, and would return the output of all installed plugins. If you specify the "id" attribute, you need the actual plugin ID found in the serendipity_plugins DB table. Via the "side" parameter you can restrict the output to a certain sidebar.<br>Note that if you use this method to show a plugin for the left or right sidebar, that output is already displayed in your sidebar. You can set a plugin to hidden inside the Plugin Configuration Administration, and then make the Smarty function emit this hidden plugin, because hidden plugins are not contained in the sidebar. The "negate" attributes will reverse the output to show all plugins not matching the side/id/class restrictions.

* {serendipity_getFile file="xxx"}<br>Returns the absolute HTTP path to a file inside your template directory. Those calls are used to fetch files like Icons or Plugins which may be template-dependant

* {serendipity_printComments entry="123" mode="..."}<br>Fetches all comments (using comments.tpl) to a certain entry id. The mode specifies threaded or chronological mode.

* {serendipity_printTrackbacks entry="123"}<br>Fetches all trackbacks to a certain entry id.

* {serendipity_fetchPrintEntries}<br>(Serendipity 1.0-alpha and up)<br>Prints a list of entries with a lot of special parameters:

<code>
[FETCHING]
category:
(int)
The category ID (seperate multiple with ";") to fetch entries from

viewAuthor:
(int)
The author ID (seperate multiple with ";") to fetch entries from

page:
(int)
The number of the page for paginating entries

id:
(int)
The ID of an entry. If given, only a single entry will be fetched.
If left empty, multiple entries are fetched.

range:
(mixed)
Restricts fetching entries to a specific timespan. Behaves
differently depending on the type:

Numeric:
YYYYMMDD - Shows all entries from YYYY-MM-DD.
If DD is "00", it will show all entries from that month.
If DD is any other number, it will show entries
of that specific day.

2-Dimensional Array:
Key #0 - Specifies the start timestamp (unix seconds)
Key #1 - Specifies the end timestamp (unix seconds)

Other (null, 3-dimensional Array, ...):
Entries newer than $modified_since will be fetched

full
(boolean)
Indicates if the full entry will be fetched (body+extended: TRUE),
or only the body (FALSE).

limit
(string)
Holds a "Y" or "X, Y" string that tells which entries to fetch.
X is the first entry offset, Y is number of entries. If not set,
the global fetchLimit will be applied (15 entries by default)

fetchDrafts
(boolean)
Indicates whether drafts should be fetched (TRUE) or not

modified_since
(int)
Holds a unix timestamp to be used in conjunction with $range,
to fetch all entries newer than this timestamp

orderby
(string)
Holds the SQL "ORDER BY" statement.

filter_sql
(string)
Can contain any SQL code to inject into the central SQL statement
for fetching the entry

noCache
(boolean)
If set to TRUE, all entries will be fetched from scratch and any
caching is ignored

noSticky
(boolean)
If set to TRUE, all sticky entries will NOT be fetched.

select_key
(string)
Can contain a SQL statement on which keys to select.
Plugins can also set this, pay attention!

group_by
(string)
Can contain a SQL statement on how to group the query.
Plugins can also set this, pay attention!

returncode
(string)
If set to "array", the array of entries will be returned.
"flat-array" will only return the articles without their entryproperties.
"single" will only return a 1-dimensional array.
"query" will only return the used SQL.

joinauthors
(bool)
Should an SQL-join be made to the AUTHORS DB table?

joincategories
(bool)
Should an SQL-join be made to the CATEGORIES DB table?

joinown
(string)
SQL-Parts to add to the "JOIN" query

entryprops
(string)
Condition list of commaseparated entryproperties that
an entry must have to be displayed.
Eexample: "ep_CustomField='customVal',ep_CustomField2='customVal2'")
(Available only in s9y >= 1.3)

[PRINTING]
template:
(string)
Name of the template file to print entries with

preview:
(boolean)
Indicates if this is a preview

block
(string)
The name of the SMARTY block that this gets parsed into

use_hooks
(boolean)
Indicates whether to apply footer/header event hooks

use_footer
(boolean)
Indicates whether the pagination footer should be displayed

groupmode
(string)
Indicates whether the input $entries array is already grouped
in preparation for the smarty $entries output array [TRUE], or
if it shall be grouped by date [FALSE]

skip_smarty_hooks
(boolean)
If TRUE, no plugins will be executed at all

skip_smarty_hook
(mixed)
Can be set to an array of plugin hooks to NOT execute

prevent_reset
(boolean)
If set to TRUE, the smarty $entries array will NOT be
cleared (to prevent possible duplicate output of entries)
</code>

++ Modifiers

The following modifiers are currently available:

* {$variable|makeFilename}<br>This transforms a variable into a valid HTTP URL name

* {$variable|xhtml_target}<br>This will either return a HTML compliant target attribute (with $variable as target name) or return a XHTML compliant ((Java Script)) window.open() command. The actual returned value is determined by your Blog's configuration directive whether XHTML compliance is activated.

* {$variable|formatTime:"%d.%m.%Y":true}<br>This returns a properly formatted timestamp depending on the blog's language. The first parameter are valid sprintf() values, the third parameter specifies whether a probably configured server time zone offset difference is applied (true) or not (false).

++ Insert your own PHP-Code

Each template can have a special file "config.inc.php" inside its directory. This file is usually not existing within the default template. But you can add it to your template directory to perform special PHP operations. In Serendipity 0.7 you could place that code directly into layout.php, but since that file got removed, you now need to enter PHP code at a seperate place.

The config.inc.php file is executed from Serendipity immediately after the Smarty framework has been created. That means, at this point you can enter any PHP code you like to modify things of the Smarty framework.

You could, for instance, create your own Smarty modifier with this code:

<code>
<?php
$serendipity['smarty']->register_function('my_custom_function', 'my_custom_function');

function my_custom_function($params, &$smarty) {
return 'I customized this: ' . $params['stuff'];
}
?>
</code>

By using that, you could access that registered function within all .tpl files. See the ((http://smarty.php.net)(Smarty)) Documentation for the API of Smarty.

The config.inc.php file can also be used for any other PHP code you may want to execute before displaying any output.

If you want to include any foreign PHP scripts in the Serendipity pages, you can do that using the ((http://smarty.php.net/manual/en/language.function.include.php.php)(Smarty {include_php})) function within any of your templates *.tpl files. The include_php function is not available in Smarty's "Secure Mode", so you have to disable that by adding this to your templates config.inc.php.file:

<code>
<?php
$serendipity['smarty']->security = false;
?>
</code>

(Leave out the <?php ?> tags if your config.inc.php file already has those)

Once you disabled the secure mode, you can use

<code>
{include_php file="/path/to/your/custom.php"}
</code>

for example in the index.tpl file at any place you need the output.

If you want to include foreign PHP scripts to show them on your own page, consider using the "External PHP" or "Wrap URL" event plugins available via Spartacus - or of course, creating your own simple PHP Serendipity Plugin. Head over to the ((http://www.s9y.org/43.html)(Plugin API Docs)) for more information about this.

++ Smarty/PHP Markup within entries

The "Markup: Smarty" plugin allows you to insert Smarty markup into your entries, complete with the power Smarty offers you. PHP within entries is not allowed, as it imposes a huge security risk.

Of course you can use the method of a config.inc.php file as described above to register your custom PHP code, which you can then re-use inside your entry code!

So you can declare a my_magic_function() which executes the PHP code you want, and if you register the function inside the config.inc.php file you can re-use it in your entry.

++ "Custom Fields"

Serendipity 0.9 allows you to define custom fields within your entry, which you can display within an entry.

That means, you can create two custom fields called Listening and Playing (don't use whitespace or special characters for fieldnames). Create an entry, and fill in values for those two fields. Now edit your entries.tpl template and place the Smarty Codes

Now listening to: {$entry.properties.ep_Listening}

Now playing: {$entry.properties.ep_Playing}

anywhere you like inside the entry loop. Remember to prefix your property keyname with ep_. Then you'll see those fields at the place you configured. You can also add the usual Smarty markup to check if a variable is empty, and add some DIV or other tags to surround your output.

Now if you don't want to show actually typed customFields of an entry, but instead make your own plugin insert stuff at that place, you can do that either by the custom function calls mentioned above, or by making your plugin alter the $entry['properties'] array to inject new content.

Your plugin can just hook into one of the events where entries are fetched ('entry_display' or 'frontend_display' or even 'frontend_entryproperties') and then just set your $eventData property index to what you want to be displayed later on. As your template already contains the display code from above, it will just pick up the new $entry['properties'] data from your custom plugin and show it, just as if you entered it on the entry creation screen.

++ Showing entries in foreign webpages

You can quite easily "show" Serendipity entries from other parts of your website, if PHP is available there and you have filesystem access to the Serendipity installation.

You can use the following PHP code to include the Serendipity framework and use the Serendipty API to display entries:

<code>
<?php
// 1: Switch to the Serendipity path. We need to use chdir so that the s9y framework can use its relative calls.
chdir('/home/www/public_html/blog/');

// 2: Start the Serendipity API
include 'serendipity_config.inc.php';

// 3: Start Smarty templating
serendipity_smarty_init();

// 4: Get the latest entries
$entries = serendipity_fetchEntries(null, true,1);

// 5: Put all the variables into Smarty
serendipity_printEntries($entries);

// 6: Get the template file
$tpl = serendipity_getTemplateFile('entries.tpl', 'serendipityPath');

// 7: Format and output the entries
$serendipity['smarty']->display($tpl);

// 8: Go back to where you came from
chdir('/home/www/public_html/');
?>
</code>

You can adapt each of the serendipity_fetchEntries() / serendipity_printEntries() calls to suit your needs. You can of course also pass any other template file instead of entries.tpl to the serendipity_getTemplateFile() call, so that you can have a custom layout for your entries in the PHP application, and use the default entries.tpl template in the real Serendipity installation.

To look up possible commands, check out the include/functions_entries.inc.php file of your Serendipity installation to see phpDoc comments above the functions for which parameters you can use.
* {serendipity_hookPlugin hook="hookname" hookAll="true|false" data=$eventData addData=$addData}<br>This allows to execute any plugins to call via the Event Plugin API. Using this execution method you can also execute your own created event hooks. The "hook" parameter specifies the used hook name, if "hookAll" is set to true, any plugin hook can executed. If it is not set or set to false, only the hooks "frontend_header", "entries_header", "entries_footer" and "frontend_comment" can be executed via Smarty. Via the "data" and "addData" variables you can pass custom variables to the PHP Plugin API functions.

* {serendipity_showPlugin class="serendipity_your_nugget" id="serendipity_your_plugin:21323223efsd22aa" side="left|right|hidden|*" negate="null|true"}<br>This allows to emit any sidebar plugin at your choses location. Either specify the "class" or "id" parameter (NOT both!) to indicate which plugin(s) should be called. The "class" attributes specifies a Plugin classname like serendipity_plugin_flickr, and would return the output of all installed plugins. If you specify the "id" attribute, you need the actual plugin ID found in the serendipity_plugins DB table. Via the "side" parameter you can restrict the output to a certain sidebar.<br>Note that if you use this method to show a plugin for the left or right sidebar, that output is already displayed in your sidebar. You can set a plugin to hidden inside the Plugin Configuration Administration, and then make the Smarty function emit this hidden plugin, because hidden plugins are not contained in the sidebar. The "negate" attributes will reverse the output to show all plugins not matching the side/id/class restrictions.

* {serendipity_getFile file="xxx"}<br>Returns the absolute HTTP path to a file inside your template directory. Those calls are used to fetch files like Icons or Plugins which may be template-dependant

* {serendipity_printComments entry="123" mode="..."}<br>Fetches all comments (using comments.tpl) to a certain entry id. The mode specifies threaded or chronological mode.

* {serendipity_printTrackbacks entry="123"}<br>Fetches all trackbacks to a certain entry id.

* {serendipity_fetchPrintEntries}<br>(Serendipity 1.0-alpha and up)<br>Prints a list of entries with a lot of special parameters:

<code>
[FETCHING]
category:
(int)
The category ID (seperate multiple with ";") to fetch entries from

viewAuthor:
(int)
The author ID (seperate multiple with ";") to fetch entries from

page:
(int)
The number of the page for paginating entries

id:
(int)
The ID of an entry. If given, only a single entry will be fetched.
If left empty, multiple entries are fetched.

range:
(mixed)
Restricts fetching entries to a specific timespan. Behaves
differently depending on the type:

Numeric:
YYYYMMDD - Shows all entries from YYYY-MM-DD.
If DD is "00", it will show all entries from that month.
If DD is any other number, it will show entries
of that specific day.

2-Dimensional Array:
Key #0 - Specifies the start timestamp (unix seconds)
Key #1 - Specifies the end timestamp (unix seconds)

Other (null, 3-dimensional Array, ...):
Entries newer than $modified_since will be fetched

full
(boolean)
Indicates if the full entry will be fetched (body+extended: TRUE),
or only the body (FALSE).

limit
(string)
Holds a "Y" or "X, Y" string that tells which entries to fetch.
X is the first entry offset, Y is number of entries. If not set,
the global fetchLimit will be applied (15 entries by default)

fetchDrafts
(boolean)
Indicates whether drafts should be fetched (TRUE) or not

modified_since
(int)
Holds a unix timestamp to be used in conjunction with $range,
to fetch all entries newer than this timestamp

orderby
(string)
Holds the SQL "ORDER BY" statement.

filter_sql
(string)
Can contain any SQL code to inject into the central SQL statement
for fetching the entry

noCache
(boolean)
If set to TRUE, all entries will be fetched from scratch and any
caching is ignored

noSticky
(boolean)
If set to TRUE, all sticky entries will NOT be fetched.

select_key
(string)
Can contain a SQL statement on which keys to select.
Plugins can also set this, pay attention!

group_by
(string)
Can contain a SQL statement on how to group the query.
Plugins can also set this, pay attention!

returncode
(string)
If set to "array", the array of entries will be returned.
"flat-array" will only return the articles without their entryproperties.
"single" will only return a 1-dimensional array.
"query" will only return the used SQL.

joinauthors
(bool)
Should an SQL-join be made to the AUTHORS DB table?

joincategories
(bool)
Should an SQL-join be made to the CATEGORIES DB table?

joinown
(string)
SQL-Parts to add to the "JOIN" query

entryprops
(string)
Condition list of commaseparated entryproperties that
an entry must have to be displayed.
Eexample: "ep_CustomField='customVal',ep_CustomField2='customVal2'")
(Available only in s9y >= 1.3)

[PRINTING]
template:
(string)
Name of the template file to print entries with

preview:
(boolean)
Indicates if this is a preview

block
(string)
The name of the SMARTY block that this gets parsed into

use_hooks
(boolean)
Indicates whether to apply footer/header event hooks

use_footer
(boolean)
Indicates whether the pagination footer should be displayed

groupmode
(string)
Indicates whether the input $entries array is already grouped
in preparation for the smarty $entries output array [TRUE], or
if it shall be grouped by date [FALSE]

skip_smarty_hooks
(boolean)
If TRUE, no plugins will be executed at all

skip_smarty_hook
(mixed)
Can be set to an array of plugin hooks to NOT execute

prevent_reset
(boolean)
If set to TRUE, the smarty $entries array will NOT be
cleared (to prevent possible duplicate output of entries)
</code>

++ Modifiers

The following modifiers are currently available:

* {$variable|makeFilename}<br>This transforms a variable into a valid HTTP URL name

* {$variable|xhtml_target}<br>This will either return a HTML compliant target attribute (with $variable as target name) or return a XHTML compliant ((Java Script)) window.open() command. The actual returned value is determined by your Blog's configuration directive whether XHTML compliance is activated.

* {$variable|formatTime:"%d.%m.%Y":true}<br>This returns a properly formatted timestamp depending on the blog's language. The first parameter are valid sprintf() values, the third parameter specifies whether a probably configured server time zone offset difference is applied (true) or not (false).

++ Insert your own PHP-Code

Each template can have a special file "config.inc.php" inside its directory. This file is usually not existing within the default template. But you can add it to your template directory to perform special PHP operations. In Serendipity 0.7 you could place that code directly into layout.php, but since that file got removed, you now need to enter PHP code at a seperate place.

The config.inc.php file is executed from Serendipity immediately after the Smarty framework has been created. That means, at this point you can enter any PHP code you like to modify things of the Smarty framework.

You could, for instance, create your own Smarty modifier with this code:

<code>
<?php
$serendipity['smarty']->register_function('my_custom_function', 'my_custom_function');

function my_custom_function($params, &$smarty) {
return 'I customized this: ' . $params['stuff'];
}
?>
</code>

By using that, you could access that registered function within all .tpl files. See the ((http://smarty.php.net)(Smarty)) Documentation for the API of Smarty.

The config.inc.php file can also be used for any other PHP code you may want to execute before displaying any output.

If you want to include any foreign PHP scripts in the Serendipity pages, you can do that using the ((http://smarty.php.net/manual/en/language.function.include.php.php)(Smarty {include_php})) function within any of your templates *.tpl files. The include_php function is not available in Smarty's "Secure Mode", so you have to disable that by adding this to your templates config.inc.php.file:

<code>
<?php
$serendipity['smarty']->security = false;
?>
</code>

(Leave out the <?php ?> tags if your config.inc.php file already has those)

Once you disabled the secure mode, you can use

<code>
{include_php file="/path/to/your/custom.php"}
</code>

for example in the index.tpl file at any place you need the output.

If you want to include foreign PHP scripts to show them on your own page, consider using the "External PHP" or "Wrap URL" event plugins available via Spartacus - or of course, creating your own simple PHP Serendipity Plugin. Head over to the ((http://www.s9y.org/43.html)(Plugin API Docs)) for more information about this.

++ Smarty/PHP Markup within entries

The "Markup: Smarty" plugin allows you to insert Smarty markup into your entries, complete with the power Smarty offers you. PHP within entries is not allowed, as it imposes a huge security risk.

Of course you can use the method of a config.inc.php file as described above to register your custom PHP code, which you can then re-use inside your entry code!

So you can declare a my_magic_function() which executes the PHP code you want, and if you register the function inside the config.inc.php file you can re-use it in your entry.

++ "Custom Fields"

Serendipity 0.9 allows you to define custom fields within your entry, which you can display within an entry.

That means, you can create two custom fields called Listening and Playing (don't use whitespace or special characters for fieldnames). Create an entry, and fill in values for those two fields. Now edit your entries.tpl template and place the Smarty Codes

Now listening to: {$entry.properties.ep_Listening}

Now playing: {$entry.properties.ep_Playing}

anywhere you like inside the entry loop. Remember to prefix your property keyname with ep_. Then you'll see those fields at the place you configured. You can also add the usual Smarty markup to check if a variable is empty, and add some DIV or other tags to surround your output.

Now if you don't want to show actually typed customFields of an entry, but instead make your own plugin insert stuff at that place, you can do that either by the custom function calls mentioned above, or by making your plugin alter the $entry['properties'] array to inject new content.

Your plugin can just hook into one of the events where entries are fetched ('entry_display' or 'frontend_display' or even 'frontend_entryproperties') and then just set your $eventData property index to what you want to be displayed later on. As your template already contains the display code from above, it will just pick up the new $entry['properties'] data from your custom plugin and show it, just as if you entered it on the entry creation screen.

++ Showing entries in foreign webpages

You can quite easily "show" Serendipity entries from other parts of your website, if PHP is available there and you have filesystem access to the Serendipity installation.

You can use the following PHP code to include the Serendipity framework and use the Serendipty API to display entries:

<code>
<?php
// 1: Switch to the Serendipity path. We need to use chdir so that the s9y framework can use its relative calls.
chdir('/home/www/public_html/blog/');

// 2: Start the Serendipity API
include 'serendipity_config.inc.php';

// 3: Start Smarty templating
serendipity_smarty_init();

// 4: Get the latest entries
$entries = serendipity_fetchEntries(null, true,1);

// 5: Put all the variables into Smarty
serendipity_printEntries($entries);

// 6: Get the template file
$tpl = serendipity_getTemplateFile('entries.tpl', 'serendipityPath');

// 7: Format and output the entries
$serendipity['smarty']->display($tpl);

// 8: Go back to where you came from
chdir('/home/www/public_html/');
?>
</code>

You can adapt each of the serendipity_fetchEntries() / serendipity_printEntries() calls to suit your needs. You can of course also pass any other template file instead of entries.tpl to the serendipity_getTemplateFile() call, so that you can have a custom layout for your entries in the PHP application, and use the default entries.tpl template in the real Serendipity installation.

To look up possible commands, check out the include/functions_entries.inc.php file of your Serendipity installation to see phpDoc comments above the functions for which parameters you can use.

Legend

 Removed 
 Changed 
 Added