SPIP plugin: Dynamic Articles with TBS

Dynamic Articles with TinyButStrong
version 1.0 (2009-08-12)
a content plugin for SPIP
(help file updated on 2009-08-12)

This plug-in allows to include dynamic contents in SPIP articles using the TinyButStrong Template Engine. The possibilities of dynamic content are very rich. For example, it can be listing data from MySQL tables, or it can complete user interface asking and processing data given by the user.
TinyButStrong is very well adapted for CMS because, unlike other Template Engines, it allows to have templates build with visual or WYSIWYG editors.

Requirement:

SPIP version 1.9 or higher, including 2.0 or higher.

Installation:

Install the plugin using the normal SPIP procedure, using the manual or the automatic way.
Direct link for auto install: http://www.tinybutstrong.com/download/download.php?sid=136&file=./spip_plugin_tinybutstrong.zip

How it works:

Since the plug-in is installed and activated in the SPIP website, you can use 3 types of tags (Direct MergeBlock, External Script and Internal Script) that you can put anywhere in your articles.
Because adding active content in articles can be powerfull, the plug-in has also several options to manage security levels that can be tuned for all articles or for specific articles.

Please note:

•	You can have several [tbs] tags in the same article. They will be processed in order.
•	All [tbs] tags can be placed anywhere, they will be deleted before the display.
•	You can tune several options at the file "plugins\tinybutstrong\tinybutstrong_options.php".
•	The plugin works on an article after typographical shortcuts for SPIP and SPIP's tags are replaced, and after it is saved in cache. The plugin works just before the article is displayed.
•	The plugin in doesn't work when the description of the article is display (like when displaying a list of articles). In order to avoid dynamic tags to be displayed in the article description, you can use the SPIP shortcut <intro></intro> to define a part of the article to be the description.
•	The SPIP shortcut <HTML></HTML> enables you to leave a part of the article source as is.

This help file assumes that you understand the basic concepts of Template Engines and more specifically the TinyButStrong Template Engine.

TYPE #1: Direct MergeBlock

Syntax: [tbs]mergeblock=blockname;db=dbname;sql=sqlstatement[/tbs]

This type of tag takes the current article as current template and performs a TBS->MergeBlock() over it.
The result of the merging is displayed instead of the original article.
There is no need to code any PHP to use this type of tag.

blockname:	Name of the TBS block to merge. Assuming that such a block exists in the current article.
dbname:	Optional. Name of the database where to use the SQL statement. The database must be available with the current SPIP connection. You can specify the keyword %current% for the SPIP database. If you want to connect to a database with another account and password, you must use another type of tag because this one cannot do it.
sqlstatement:	The SQL statement that should return the data to display. In order to facilitate the usage of operators '<' and '>' in the SQL statement, the plugin automatically replaces strings '-+' and '+-' with those operators. You can prevent this behavior by adding the parameter sql_preserve in the [tbs] tag. Example: [tbs]mergeblock=u;sql=SELECT name FROM t_user WHERE id+-0[/tbs] is the same as [[tbs]mergeblock=u;sql=SELECT name FROM t_user WHERE id>0;sql_preserve[/tbs]

Example:

SPIP article:

<intro>Dynamic article example: Direct MergeBlock</intro>
[tbs]mergeblock=u;sql=SELECT * FROM spip_meta ORDER BY nom[/tbs]
|| List of meta info ||
| {{name}} |
| [u.nom;block=tr] |

You can notice that the TBS block is define with block=tr. This is because the plugin works the article after text formatting shortcuts for SPIP are replaced. "|" are shortcuts for a table presnetation, they will be replaced with <table><tr> and <td> tags.

TYPE #2: External script

Syntax: [tbs]script=scriptname.php;db=dbname[/tbs]

This type of tag is the same as the previous one but instead of a simple TBS->MergeBlock(), it run the specified PHP script.
The script should drive the merging assuming that the current article is already loaded as the current template. There is no need to call TBS->Show() because the plugin will do it. Please note that your PHP script is run in the same context as a function and that the local variable $TBS contains the ready to use TBS instance. The local variable $PrmLst contains the parameters of the [tbs] tag if you need it.

scriptname.php:

The PHP script to run. You can specify a path. The default path for all scripts can also be specified in the plug-in options.

dbname:

Optional. Name of the database to select before the script is run. The database must be available with the current SPIP connection. You can specify the keyword %current% for the SPIP database.
If you want to connect to a database with another account and password, then your script must open this connection by itself, and you should specify explicitly the new open connected for any use of MergeBlock().

Example

SPIP article:

<intro>Dynamic article example: External script</intro>
[tbs]script=myappli.php[/tbs]

| {{ID}} | {{Title}} |
| [u.id_article;block=tr] | [u.titre] |

myappli.php: (external script using the same MySQL connection and database)

<?php
$key = (isset($_GET['key'])) ? intval($_GET['key']) : 0;
$TBS->MergeBlock('u','mysql','SELECT titre, id_article FROM spip_articles WHERE id_article='.$key);
?>

myappli.php: (external script using a different MySQL connection)

<?php
$key = (isset($_GET['key'])) ? intval($_GET['key']) : 0;
$cid2 = mysql_connect('localhost', 'user', 'password');
$TBS->MergeBlock('u', $cid2, 'SELECT subname, name FROM table1 WHERE key='.$key);
mysql_close($cid2);
?>

TYPE #3: Internal script

Syntax: [tbs]embedded;db=dbname[/tbs]

This type of tag is the same as the previous one but instead of an external script, it run the parts of PHP code which are embedded in the current article. This can be very dangerous because all PHP commands are available. The parts of PHP code must be placed between tags . Those tags are compatible with HTML comment tags, which means that they won't destroy the article looking, but they cannot be seen is visual mode. You must edit them by editing the HTML source. The PHP code is deleted before the article is displayed.

dbname:

Example:

SPIP article:

<intro>Dynamic article example: Internal script</intro>
[tbs]embedded[/tbs]

| {{ID}} | {{Title}} |
| [u.id_article;block=tr] | [u.titre] |

Tag embedded in the SPIP article:

<HTML></HTML>