TBS Manuel

Site :	www.tinybutstrong.com
Auteur :	skrol29@freesurf.fr
Date :	2004-03-23

*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*
TinyButStrong
version 1.95
*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*

Template Engine pour Pro et débutants
sous PHP version 4.0.4 ou supérieure

Plan de ce fichier d'aide :

Rubrique	Description

• Présentation
Principes de base
Installation
Mini exemples
• Coté PHP
• Pour commencer
méthode LoadTemplate()	charge le contenu d'un modèle à partir d'un fichier
méthode MergeBlock()	fusionne une partie du modèle avec une source de données
méthode Show()	traitements automatiques et affichage du résultat
• Avancé
méthode CacheAction()	active le système mise en cache des résultats de fusion
méthode GetBlockSource()	retourne le source de la définition d'un bloc
méthode MergeField()	fusionne un champ particulier avec une valeur
méthode MergeNavigationBar()	fusionne une barre de navigation
méthode MergeSpecial()	fusionne les bloc conditionnels, variables Php et autres...
propriété Render	pour modifier les options de fin de fusion
propriété Source	retourne le contenu courrant du résultat de la fusion
variables globales pour TBS	pour lire et modifier les valeurs qui sont en cours de traitement
ajout d'un type de sources de données	pour que TBS reconnaisse un nouveau type de base de données
• Coté HTML
• les champs TBS
définition et propriétés
les champs de variable Php
les champs système
• les blocs TBS
définition et propriétés
sections de bloc
affichage en série (en colonnes)
requêtes dynamiques / sous-blocs
affichage d'une barre de navigation
• Autre
insérer un sous-modèle
insérer le résultat d'un autre script Php
vue d'ensemble de l'affichage conditionnel
• Résumés
paramètres des champs TBS
paramètres des blocs TBS
champs et paramètres de barre de navigation
noms de champs et blocs spéciaux

Plan de ce fichier d'aide :
	Rubrique	Description

	Présentation
	Principes de base
	Installation
	Mini exemples
	Coté PHP
	Pour commencer
	méthode LoadTemplate()	charge le contenu d'un modèle à partir d'un fichier
	méthode MergeBlock()	fusionne une partie du modèle avec une source de données
	méthode Show()	traitements automatiques et affichage du résultat
	Avancé
	méthode CacheAction()	active le système mise en cache des résultats de fusion
	méthode GetBlockSource()	retourne le source de la définition d'un bloc
	méthode MergeField()	fusionne un champ particulier avec une valeur
	méthode MergeNavigationBar()	fusionne une barre de navigation
	méthode MergeSpecial()	fusionne les bloc conditionnels, variables Php et autres...
	propriété Render	pour modifier les options de fin de fusion
	propriété Source	retourne le contenu courrant du résultat de la fusion
	variables globales pour TBS	pour lire et modifier les valeurs qui sont en cours de traitement
	ajout d'un type de sources de données	pour que TBS reconnaisse un nouveau type de base de données
	Coté HTML
	les champs TBS
	définition et propriétés
	les champs de variable Php
	les champs système
	les blocs TBS
	définition et propriétés
	sections de bloc
	affichage en série (en colonnes)
	requêtes dynamiques / sous-blocs
	affichage d'une barre de navigation
	Autre
	insérer un sous-modèle
	insérer le résultat d'un autre script Php
	vue d'ensemble de l'affichage conditionnel
	Résumés
	paramètres des champs TBS
	paramètres des blocs TBS
	champs et paramètres de barre de navigation
	noms de champs et blocs spéciaux

Présentation :

haut

TinyButStrong (TBS) est une classe PHP utile pour développer une application en séparant proprement vos scripts PHP de vos pages HTML. Avec TBS, les pages HTML sont générées dynamiquement en fusionnant un modèle avec des données. C'est ce qu'on appelle un moteur de modèle (Template Engine).

TBS tient son nom du fait qu'il ne présente que 8 fonctions mais qu'il permet de faire le maximum. Il est ••• très très fort ••• pour fusionner des modèles de pages HTML avec vos variables PHP ou vos requêtes MySQL, PostgreSQL, ODBC, SQL-Server ou ADODB.

TBS a été conçu pour que vous puissiez développer avec facilité vos modèles depuis n'importe quel éditeur HTML visuel (comme Dreamweaver ou FrontPage), mais si vous avez l'habitude d'utiliser un éditeur textuel il est tout aussi pratique. TBS permet aussi de créer du JavaScript dynamiquement.

Comme son nom l'indique, TBS et simple à utiliser, puissant et rapide. Il est complètement °~° freeware °~°.

Principes de base :

haut

Du coté HTML :
Vous concevez une page qui n'a pas besoin de contenir de script PHP, ni de programation. Dans cette page vous placez des balises TBS aux endroits où doivent s'afficher les données dynamiques. Cette page est appelée un 'modèle'. Il existe deux types de balises : les 'champs' qui servent à afficher une donnée dynamiquement, et les 'blocs' qui servent à définir une zone, le plus souvent pour afficher les enregistrements d'une source de données.

Du coté PHP :
Vous utilisez une variable objet TBS pour piloter la fusion de votre modèle HTML avec des données. À la fin, TBS affiche le résultat de la fusion.

Installation :

haut

1.	Copiez le fichier tbs_class.php dans un répertoire de votre site Web.
2.	Au début de votre programme PHP, ajoutez les lignes : include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; Remarque : si le fichier tbs_class.php se trouve dans un répertoire différent de celui de votre programme, vous devrez préciser le répertoire devant le nom du fichier.

Explications et détails techniques :
TinyButStrong est un librairie écrite en PHP, c'est un composant à référencer dans vos propres programmes PHP. En terme technique, TinyButStrong est une 'classe' d'objet PHP ; le nom de cette classe est clsTinyButStrong.
La variable $TBS que ajoutez en début de programme sert à piloter la fusion de votre modèle depuis votre application PHP. En terme technique, la variable $TBS est une 'instance' de la classe clsTinyButStrong.

Mini exemples :

haut

Exemple 1 :

Modèle Html	Programme Php	Résultat
<html> <body> [var.message] </body> </html>	<? include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate('template.htm') ; $message = 'Hello' ; $TBS->Show() ; ?>	<html> <body> Hello </body> </html>

Exemple 2 :

Modèle Html	Programme Php	Résultat
<table> <tr><td>[blk.val;block=tr]</td></tr> </table>	<? include_once('tbs_class.php'); $TBS = new clsTinyButStrong ; $TBS->LoadTemplate('template.htm') ; $liste = array('X','Y','Z') ; $TBS->MergeBlock('blk',$liste) ; $TBS->Show() ; ?>	<table> <tr><td>X</td></tr> <tr><td>Y</td></tr> <tr><td>Z</td></tr> </table>

Coté PHP :

Le pilotage de la fusion d'un modèle se fait dans un programme PHP en utilisant une variable objet déclaré à partir de la classe clsTinyButStrong.
Exemple de déclaration : $TBS = new clsTinyButStrong ;
Cet objet vous permet de charger un modèle, piloter sa fusion avec des données, puis afficher le résultat.

Exemple de code PHP :

include_once('tbs_class.php');
$TBS = new clsTinyButStrong ;
$TBS->LoadTemplate('template.htm') ;
$TBS->MergeBlock('ctry','mysql','SELECT * FROM t_coutry') ;
$TBS->Show() ;

Voici la liste des propriétés et méthodes d'un l'objet TinyButStrong :

Méthode LoadTemplate() :

haut

Charge un modèle en vue de son traitement pour la fusion.
Le contenu complet du fichier est enregistré dans la propriété Source de l'objet TinyButStrong.

Syntaxe : $TBS->LoadTemplate(string Fichier{, string HtmlCharSet})

Argument	Description
Fichier	Chemin local ou absolu du fichier modèle à charger.
HtmlCharSet	Facultatif. Indique l'encodage des caractères. La valeur par défaut est '' (chaîne vide) qui équivaut à 'ISO-8859-1' (Latin 1). Si votre modèle utilise un jeu de caractère spécial, indiquez la valeur Html de cet encodage. Dans une page Html, l'encodage se trouve en tête du fichier, dans l'attribut 'content' d'une balise <Meta>. Les encodages supportés par TBS sont les encodages supportés par la fonction htmlentities() de Php. Par exemple : 'BIG5' (chinois) ou 'EUCJP' (japonais). Utilisez la valeur False pour ce paramètre si votre fichier est un fichier texte, et TBS ne convertira pas les valeurs en Html.

Méthode MergeBlock() :

haut

Fusionne un bloc TBS avec les données d'une source d'enregistrements.
Retourne le numéro du dernier enregistrement affiché (le premier porte le numéro 1).

TinyButStrong supporte plusieurs types de sources de données en natif :
Données Php : un tableau ; une chaîne texte, un nombre.
Base de données : MySQL ; PostgreSQL ; ODBC ; SQL-Server ; ADODB.
Mais vous pouvez aussi en ajouter de nouveaux : 'ajout d'un type de sources de données'.

Il existe un mode d'affichage 'Par Page' décrit plus bas.

Syntaxe : int $TBS->MergeBlock(string NomBloc, mixed Source{, string Requête}{, int PageTaille, int PageNum}{, int NbrEnreg})

Argument

Description

NomBloc

Indique le nom du bloc TBS à fusionner.

Source

Variable ou mot-clé qui désigne la source de données pour la fusion.
Le tableau ci-dessous indique les valeurs possibles selon le type de source de données.

Requête

Facultatif. Indique la requête SQL qui retourne les données à fusionner.
Le tableau ci-dessous indique les valeurs possibles selon le type de source de données.

PageTaille

Facultatif. Cet argument doit être défini si vous voulez activer l'affichage par page.
Indique le nombre d'enregistrements pour une page.

PageNum

Facultatif. Cet argument doit être défini si vous voulez activer l'affichage par page.
Indique le numéro de page à afficher. La première page porte le numéro 1.
La valeur spéciale -1 affichera la dernière page du jeu d'enregistrements.

NbrEnreg

Facultatif. Cet argument n'est utile que lors de l'affichage par page. Il permet de modifier le calcul du nombre d'enregistrements retourné par la méthode MergeBlock().

NbrEnreg	Valeur retournée par MergeBlock()
0 :	C'est la valeur par défaut. La méthode retourne le numéro du dernier enregistrement affiché par la page demandée.
-1 :	La méthode lie tous les enregistrements jusqu'à la fin et retourne le nombre total d'enregistrements. Toutefois, seuls les enregistrements de la page demandée seront affichés.
>0 :	La méthode retourne la valeur NbrEnreg. Toutefois, elle retournera le numéro du dernier enregistrement affiché si celui-ci est supérieur à NbrEnreg.

Utilisez ce paramètre pour calculer puis conserver le nombre d'enregistrements total.
Par exemple :

if (isset($_POST['nbr_rec'])) {
$nbr_rec = $_POST['nbr_rec'] ;
} else {
$nbr_rec = -1 ;
}
$nbr_rec = $TBS->MerbeBlock('blk1',$cnx_id,'select * from t_country',$p_size,$p_num,$nbr_rec);

Liaison entre le bloc et les enregistrements :

La méthode MergeBlock() recherche le bloc TBS avec le nom spécifié dans votre modèle. Puis, le bloc TBS est répété autant de fois qu'il y a d'enregistrement dans la source de données.
Pour afficher les données d'un enregistrement, vous devez utiliser un champ TBS lié. Un champ TBS est lié lorsqu'il sont nom est composé du nom du bloc, suivit d'un point et du nom d'une colonne ou d'une clé du jeu d'enregistrements. Un champ liés doit se trouver à l'intérieur du bloc.

Exemple :

Nom du bloc : bloc1
Colonnes retournées par la requête : champ1,champ2,champ3
Champs TBS liés : [bloc1.champ1], [bloc1.champ2], [bloc1.champ3]

Si aucune définition de bloc n'est trouvée dans le modèle, La méthode MergeBlock() fusionnera le premier enregistrement avec tous les champs liés trouvés dans le modèle.

Vous pouvez définir de blocs plus évolués. Pour plus d'information, consultez la rubrique Blocs TBS.

Décompte des enregistrements :

Pour afficher le numéro d'enregistrement, utilisez un champ TBS lié à la colonne virtuelle '#'.
Si vous placez ce champ en dehors du bloc, il affichera le nombre total d'enregistrements.
Exemple : [bloc1.#]

Utilisation des arguments Source et Requête selon le type de source de données :

Type de source de données	Source	Requête
Texte	Le mot-clé 'text'	Un texte
Nombre	Le mot-clé 'num'	Un nombre ou un tableau spécial (voir plus bas)
Tableau PHP	Un tableau Php de clés et de valeurs non tableau.	-
Tableau PHP	Un tableau Php dont les valeurs sont des tableaux qui ont des clés du même nom.	-
MySQL	Une ressource de connexion MySql ou le mot-clé 'mysql'	Une requête SQL
MySQL	Une ressource de résultat MySql	-
PostgreSQL	Une ressource de connexion PostgreSql	Une requête SQL
PostgreSQL	Une ressource de résultat PostgreSql	-
ODBC	Une ressource de connexion Odbc	Une requête SQL
ODBC	Une ressource de résultat Odbc	-
SQL-Server (1)	Une ressource de connexion MsSql ou le mot-clé 'mssql'	Une requête SQL
SQL-Server (1)	Une ressource de résultat MsSql	-
ADODB (2)	Un objet connexion	Une requête SQL
ADODB (2)	Un objet résultat	-
Personnalisé	Un mot-clé, un objet ou une ressource non listé dans ce tableau. Voir le paragraphe 'ajout d'un type de sources de données'.	Une requête SQL ou autre chose.

(1) J'ai personnellement rencontré des problèmes d'accents avec l'utilisation des fonctions pour SQL-Server sous PHP.
(2) Il s'agit de la méthode d'accès aux données ADODB de Microsoft, accessible via la classe COM de Php.

Source de données Php :

- Texte :

L'argument Source doit être égale à 'text'.
Tout le bloc est remplacé par le texte contenu dans la paramètre Requête. Les champs liés ne sont pas gérés sauf '#' qui retourne 1, ou 0 si Requête est une chaîne vide.

- Nombre :

L'argument Source doit être égale à 'num'.
L'argument Requête peut être soit un nombre, soit un tableau.

arg Requête	Jeu d'enregistrements retourné
Nombre :	Ce Requête doit être supérieur ou égale à zéro. Le jeu d'enregistrement retourné est composé d'une colonne 'val' dont la valeur va de 1 à Requête.
Tableau :	Le tableau doit contenir une clé 'min' et une clé 'max' et éventuèlement une clé 'step'. Le jeu d'enregistrement retourné est composé d'une colonne 'val' qui va de la valeur de 'min' à la valeur de 'max'. Exemple : array('min'->101,'max'->150) affichera 50 blocs numérotés de 101 à 150.

- Tableau :

L'argument Source doit être un tableau Php (type Array).
Ce doit être soit un tableau avec des clés et des valeurs non tableau (cas 1), soit un tableau dont les valeurs sont des tableaux qui ont des clés du même nom (cas 2).

Cas 1 :
Exemple :
  ['clé1']=>valeur1
  ['clé2']=>valeur2
  ...
Le jeu d'enregistrement retourné est composé d'une colonne 'key' contenant le nom de la clé, et d'une colonne 'val' contenant la valeur de la clé.

Cas 2 :
Exemple :
  [0] => (['colonne1']=>valeur1-0 ; ['colonne2']=>valeur2-0 ; ...)
  [1] => (['colonne1']=>valeur1-1 ; ['colonne2']=>valeur2-1 ; ...)
  [2] => (['colonne1']=>valeur1-2 ; ['colonne2']=>valeur2-2 ; ...)
  ...
Le jeu d'enregistrement retourné est composé des colonnes 'colonne1', 'colonne2', ... avec leurs valeurs associées.

Mode 'Par Page' :

Le mode affichage 'Par Page' est activé lorsque vous renseignez l'argument PageTaille avec une valeur différente de zéro. L'affichage des données sera alors limité à la page spécifiée par PageNum. Si PageNum a la valeur -1, c'est la denière page qui sera affichée.

Remarque importante :

Bien qu'il soit facile et pratique, le mode 'Par Page' n'est pas optimisé pour un grand nombre d'enregistrements. Si votre affichage est trop lent, ou si votre base de données est trop sollicitée, il est conseillé d'utiliser les fonctions natives de votre système de base de données (si celui-ci gère les requêtes limitées).
Par exemple avec MySQL, utilisez la clause LIMIT.

Explications : compte tenu de la diversité des syntaxes SQL, TinyButStrong n'est pas capable de modifier lui-même une requête afin qu'elle retourne un jeu d'enregistrement limité. Par exemple, il n'est pas capable d'ajouter la clause LIMIT à une requête MySQL.
C'est pourquoi, TinyButStrong doit appeler la requête originale, puis lire les enregistrements un par un en ignorant tous ceux qui se trouvent avant la page demandée. Cela a pour effet de rendre l'affichage d'autant plus lent que la page à atteindre est élevée. Une fois que la page atteinte, TinyButStrong libère la requête sans aller à la fin du jeu d'enregistrement.

Méthode Show() :

haut

Termine la fusion.

Syntaxe : $TBS->Show()

La propriété Render permet de régler le comportement de la méthode Show(). Par défaut, Show() traite les champs TBS spéciaux (champs de variable PHP, champs système, insertion de fichier, blocs conditionnels,...), affiche le résultat de la fusion, puis quitte le programme.

Méthode CacheAction() :

haut

Active le système de cache ou lance une autre opération sur les fichiers de cache.

Syntaxe : bool $TBS->CacheAction(string CacheId {, int ActTimeOut}{, string Dir})

Argument	Description
CacheId	Une chaîne de caractères qui identifie votre page de façon unique dans le répertoire de cache.
ActTimeOut	Doit être le timeout exprimé en seconde ou l'une des constantes ci-après. La valeur par défaut est 3600, c'est à dire une heure.
Dir	Facultatif. Désigne le répertoire où est enregistré le fichier cache. Par défaut il s'agit du répertoire du script.

À la place du timeout, vous pouvez utiliser l'un des constantes ci-après pour déclancher une action spéciale du système de cache.

Constante	Description
TBS_DELETE	Supprime le fichier cache. Si le paramètre CacheId a pour valeur le mot-clé '*' alors tous les fichiers cache du répertoire sont supprimés.
TBS_CANCEL	Annule la mise à jour du fichier cache si il était prévu en fin de fusion.
TBS_CACHENOW	Enregistre le résultat actuel de la fusion dans le fichier cache.

Le système de cache permet d'accélérer l'affichage des pages HTML en n'opérant la fusion qu'à intervalle régulier plutôt que à chaque consultation de la page. Pour cela, vous devez prévoir un identifiant pour chaque page sauvegardée (appelée fichier cache), ainsi qu'une période de rafraîchissement (appelé timeout). Lorsque vous appelez la méthode CacheAction, le système de cache regarde s'il existe déjà une page en cache et relève sa date de création. Si la date de création est plus courte que le timeout, alors le contenu du fichier cache est chargé et la fusion se termine. Si la date de création est plus longue que le timeout, alors le fichier cache est ignoré mais il sera mis à jour lors du prochain appel de la méthode Show() en enregistrant le résultat de la fusion dans ce fichier cache.

Si le fichier cache est chargé, la méthode retourne True, sinon, elle retourne False.
Par défaut, si le fichier est chargé alors le contenu est affiché et le script est arrêté mais vous pouvez changer ce comportement à l'aide de la propriété Render.

Méthode GetBlockSource() :

haut

Retourne le source d'un bloc TBS.
Seule la définition de la première section du bloc sera retournée à moins que l'argument Sections soit à True.
Si aucun bloc n'est trouvé, la méthode retourne la valeur False.

Syntaxe : string $TBS->GetBlockSource(string NomBloc {, boolean Sections})

Argument	Description
NomBloc	Nom du bloc à rechercher.
Sections	Facultatif. La valeur par défaut est False. Si ce paramètre est à True, la méthode retourne un tableau contenant les définitions de toutes les sections du bloc nommé. La première section est retournée dans l'élément [1] du tableau.

Cette méthode permet de récupérer le source d'un bloc afin de gérer manuellement sa fusion.
Si par la suite vous souhaitez remplacer le bloc par du texte, vous pouvez utiliser ma méthode MergeBlock() avec le paramètre 'text'.

Méthode MergeField() :

haut

Remplace un champ TBS du modèle par une valeur.

Syntaxe : $TBS->MergeField(string NomChamp, mixed Valeur)

Argument	Description
NomChamp	Le nom du champ. Par exemple 'Titre'.
Valeur	La valeur à afficher.

Si plusieurs champs portent le même nom dans le modèle, ils seront tous traités.

Méthode MergeNavigationBar() :

haut

Affiche une barre de navigation à partir de blocs TBS et de champs TBS spécifiques.
Pour plus d'info sur la construction d'une barre de navigation, consultez la rubrique 'Affichage d'une barre de navigation'.

Syntaxe : $TBS->MergeNavigationBar(string NomNav, mix Options, int PageNum[, int NbrEnreg, int TaillePage])

Argument

Description

NomNav

Nom de la barre de navigation.

Options

Options d'affichage. Ce doit être un tableau Array avec un ou plusieurs items suivants :

	Clé	Valeur
	'size'	Nombre de page affichées dans la barre de navigation (par défaut = 10).
	'pos'	Position de la barre de navigation par rapport à la page en cours. Utilisez l'un des mots-clé suivants : - 'step' (par défaut) pour que la barre progresse par pas. - 'centred' pour centrer la barre sur la page en cours.

À la place d'un tableau, vous pouvez indiquer directement un entier qui représente le nombre de page affichées. Les autres options seront celles par défaut.

PageNum

Numéro de la page courante.
La première page a le numéro 1. Pour indiquer la dernière page, utilisez la valeur -1.

NbrEnreg

Facultatif. La valeur par défaut est -1.
Indique le nombre d'enregistrements total connus. Si ce nombre est inconnu il faut mettre la valeur -1. Cet argument sert uniquement à calculer le numéro de la dernière page de la barre de navigation.

TaillePage

Facultatif. La valeur par défaut est 1.
Indique le nombre d'enregistrement par page. Il s'utilise conjointement avec NbrEnreg et sert uniquement à calculer le numéro de la dernière page de la barre de navigation.

Exemple :

$TBS->MergeNavigationBar('nav',array('size'=>7,'pos'=>'centred'),$page,$rec_nbr,$page_size);

Méthode MergeSpecial() :

haut

Remplace les champs et blocs spéciaux du type spécifié.

Syntaxe : $TBS->MergeSpecial(string Type)

L'argument Type doit être l'une des valeurs suivantes :

Valeur	Description
'var'	Remplace tous les champs de variable Php.
'sys'	Remplace tous les champs système.
'include'	Remplace les champs et blocs avec une insertion de fichier et qui sont nommés tbs_include.
'check'	Remplace les champs et blocs avec un affichage conditionnel et qui sont nommé tbs_check.

Remarque :
Par défaut, la méthode Show() replace tous les champs et blocs spéciaux juste avant l'affichage du résultat de la fusion. C'est pour cela qu'il est rare d'utiliser MergeSpecial() dans un programme.

Propriété Render :

haut

Détermine comment doit se terminer la fusion.
Sa valeur doit être une combinaison des constantes du tableau ci-dessous.
Par défaut, sa valeur est (TBS_OUTPUT + TBS_EXIT).

Syntaxe : int $TBS->Render

La propriété Render influe sur le comportement des méthodes Show() et CacheAction().

Constante	Description
TBS_NOTHING	Indique que aucune action ci-dessous n'est effectuée à la fin de la fusion.
TBS_OUTPUT	Indique que le résultat de la fusion doit être affiché. (utilisation de la commande PHP Echo)
TBS_EXIT	Indique qu'on doit quitter le script juste après la fin de la fusion.

Propriété Source :

haut

Définie ou renvoie le code HTML sur lequel on applique les opérations de fusion.
Après l'appel à la méthode LoadTemplate(), cette propriété contient le source HTML du modèle demandé.
Cette propriété permet de lire ou modifier le résultat de la fusion, au fur et à mesure des traitements.

Syntaxe : string $TBS->Source

Les variables globales de TinyButStrong :

haut

TinyButStrong fourni certaines variables globales que vous pouvez utiliser dans votre programme PHP.

$tbs_CurrVal représente la valeur en cours lors de la fusion d'un champ.
$tbs_CurrRec représente l'enregistrement en cours lors de la fusion d'un bloc.

Ces variables globales peuvent être utilisées lors de :
- La fusion d'un bloc pour lequel a été défini une fonction évènementielle onsection.
- La fusion d'un champ pour lequel a été défini une fonction évènementielle onformat.
- L'exécution d'un script PHP avec le paramètre script.

Ajout d'un type de source de données :

haut

Il est possible d'ajouter un autre type de source de données non encore supporté en natif par TinyButStrong.
Pour cela, vous devez coder trois fonctions avec des déclarations spécifiques et des noms correspondant au type à ajouter.
N'ajouter pas ces fonctions dans le fichier source de TBS, codez les dans votre programme ou dans un script Php externe.
Vous pouvez trouver des nouveaux types de sources de données sur le site Web de TinyButStrong.

Identifiant TBS :

L'argument $Source que vous passez à la méthode MergeBlock() a un identifier TBS que vous devez utiliser pour la nomination des fonctions.

Si $Source est un objet, alors l'identifiant TBS est le nom de la classe de cet objet.
Si $Source est une ressource, alors l'identifiant TBS est le type de la ressource.
Si $Source est une chaîne texte, alors l'identifiant TBS est cette même chaîne.

Le type de l'argument $Source ne doit ne pas être déjà supporté par TinyButStrong, sinon les fonctions seront ignorées.
L'identifiant TBS peut être arrangé par TBS pour convenir à un nom de fonction.

Exemple :

Si $Source est une connexion Sybase (type de ressource = 'sybase-db link'), alors l'identifiant TBS est 'sysbase_db'.

Déclarations des fonctions :

Les trois fonctions à ajouter dans votre programme doivent avoir les syntaxes suivantes :
Remplacez le mot-clé 'customdb' par l'identifiant TBS identifier de votre type de source de données.

function tbsdb_customdb_open(&$Source,&$Requete) {...}
Cette fonction doit ouvrir la requête demandée, et retourner un identifiant de jeu d'enregistrements.
En cas d'erreur, la fonction doit retourner la valeur False, et peut afficher un message.

Argument	Description
$Source	Il s'agit du même argument passé à la méthode MergeBlock().
$Requête	Il s'agit du même argument passé à la méthode MergeBlock().

Exemple :

function tbsdb_sybase_db_open(&$Source,&$Query) {
return sybase_query($Query,$Source) ;
}

function tbsdb_customdb_fetch(&$Rs{,$RecNum}) {...}
Cette fonction doit retourner un tableau associatif correspondant à l'enregistrement en cours, avec les noms de colonnes et les valeurs. La fonction doit retourner la valeur False quand il n'y a plus d'enregistrement.

Argument	Description
$Rs	L'identifiant de jeu d'enregistrement retourné par la fonction tbsdb_customdb_open().
$RecNum	Facultatif. Le numéro de l'enregistrement attendu. Le premier porte le numéro 1.

Exemple :

function tbsdb_sybase_db_fetch(&$Rs) {
return sybase_fetch_assoc($Rs) ;
}

Si la source de données a besoin du numéro de l'enregistrement demandé, vous pouvez ajouter l'argument $RecNum à la déclaration de la fonction. Mais dans les autres cas, cet argument est facultatif parce que tous les enregistrements seront appelés dans l'ordre de toute façon.

function tbsdb_customdb_close(&$Rs) {...}
Cette fonction doit fermer ou libérer l'identifiant de jeu d'enregistrements.
Elle n'a pas besoin de retourner une valeur.

Argument	Description
$Rs	L'identifiant de jeu d'enregistrement retourné par la fonction tbsdb_customdb_open().

Exemple :

function tbsdb_sybase_db_close(&$Rs) {
return sybase_free_result($Rs) ;
}

Coté HTML :

haut

Vous concevez votre modèle en plaçant des balises TBS aux endroits où doivent figurer les données.

Il existe deux types de balises TBS : les champs et les blocs.

Un champ TBS est une balise TBS qui doit être remplacé par une donnée simple. Il est possible de spécifier un format d'affichage ainsi que d'autres paramètres. La syntaxe des champs TBS est décrite ci-après.

Un bloc TBS est une région qui devra être répétée. Il est défini par une ou deux balises TBS.
Le plus souvent il s'agit d'une ligne d'un tableau HTML. La syntaxe des blocs TBS est décrite ci-après.

Les champs TBS :

haut

Un champ TBS est une balise TBS qui doit être remplacé par une donnée simple.
Il a un nom qui permet de l'identifier et on peut définir des paramètres pour modifier le comportement de l'affichage.

Syntaxe : HTML ... [NomChamp;params] ... HTML

Élément	Description
NomChamp	Le nom du champ. Attention : les noms de champs commençant par sys., var. et tbs_check. sont réservés respectivement pour les champs-système, les champs de variable php, et les champs conditionnels.
params	Facultatif. Un ou plusieurs paramètres de la liste ci-dessous, séparés par des ';'. Certains paramètres peuvent être affectés d'une valeur en utilisant le caractère '='. Exemple : frm=0.00 Si la valeur du paramètre contient des espaces ou des points-virgules, on peut placer cette valeur entre guillemets simples. Par exemple : frm='0 000.00'. Il est possible d'imbriquer des champs TBS les uns dans les autres. Cela veut dire que vous pouvez écrire ceci : [var.v1; if [var.v2]=1]. Mais : - pour les champs [var.*], vous devez vous assurer que v2 sera fusionné avant v1. - pour les champ de blocs, vous devez vous assurer que la colonne v2 est avantla colonne v1.

Paramètre

Description

htmlconv=val

Permet de forcer ou empêcher la conversion de la donnée en texte Html.
La valeur val peut être l'un des mots-clés suivants :

	yes :	(valeur par défaut) force la conversion en Html avec sauts de ligne.
	nobr :	force la conversion en Html sans les sauts de ligne (utile pour la balise <pre> par exemple).
	wsp :	préserve les espaces blancs (utile pour les espaces de début de ligne).
	no :	empêche la conversion en Html. Utile pour modifier du code Javascript ou modifier le source HTML.
	look :	convertie la donnée en Html si aucune balise Html n'est trouvé dans cette donnée.
	esc :	pas de conversion Html et double les caractères guillemets simples (').

. (point)

Si la donnée est vide, on affiche un espace Html insécable. Utile pour les cellules d'un tableau.

ifempty=val

Si la donnée est vide, on la remplace par la valeur indiquée.

friend=nom_balise

Si la donnée est vide, on efface les balises Html nom_balise ouvrante et fermante qui encadrent le champs ainsi que tout ce qui se trouve entre les deux. Le champ peut être placé à l'intérieur de la balise.

Exemple :
(<a href="[var.link;friend=a]">cliquez ici</a>)
Résultat pour $link='www.tbs.com' : (<a href="www.tbs.com">cliquez ici</a>)
Résultat pour $link='' : ()

- Utilisez friend2 pour effacer les balises mais en laissant ce qui se trouve entre les deux.

Exemple :
(<a href="mailto:[blk.email;friend2=a]">[blk.nom]</a>)
Résultat pour$email='moi@tbs.com' : (<a href="mailto:moi@tbs.com">MonNom</a>)
Résultat pour$email='' : (MonNom)

- Utilisez friendb pour effacer la balise nom_balise placée avant le champ, ainsi que tout ce qui se trouve entre la balise et le champ si la valeur est vide.
Exemple1 : <img href="[var.lien;friendb=img]">
Exemple2 : <br> [var.adresse;friendb=br]

- Utilisez frienda pour effacer la balise nom_balise placée après le champ, ainsi que tout ce qui se trouve entre la balise et le champ si la valeur est vide.
Exemple : [var.adresse;frienda=br]<br>

Remarque : les paramètres if then else sont traités avant le paramètre friend.

selected

Ce paramètre sert à sélectionner un item dans une liste, des radio-boutons ou des cases-à-chocher positionnés dans un formulaire Html. Il faut s'assurer au préalable que les items soientt déjà crées (fusionnés).

Liste Html :
Utilisez le paramètre select sans lui donner de valeur. Le champ TBS doit obligatoirement être placée parmi la liste des items. Quand le champ TBS est fusionné, il sera supprimé, mais l'item qui a la même valeur que le champ sera sélectionné. Si la valeur n'est pas trouvé, un nouvel item est ajouté.

Radio-boutons et cases-à-cocher :
Utilisez le paramètre select en lui donnant comme valeur le nom des radio-bouton ou cases-à-cocher à traiter. Le champs TBS doit obligatoirement être placé à l'intérieur du formulaire. Quand le champ TBS est fusionné, il sera supprimé mais l'item qui a la même valeur que le champ sera sélectionné.

Multi-sélection :
Pour les listes, les radios-boutons ou les cases-à-cocher, vous pouvez faire une multi-sélection donnant à la valeur du champ TBS un tableau Php.

comm

Ce paramètre permet d'étendre les limites du champ jusqu'aux limites de la balise commentaire (Html) qui l'entoure.
 est rigoureusement identique à [monchamp]
C'est particulièrement pratique pour l'élaboration du modèle avec un éditeur HTML visuel (tel que Dreamweaver ou FrontPage).

noerr

Empêche l'affichage de certains messages d'erreurs TBS. Quand un message peut être annulé, cela est mentionné dans le message.

file=nomfichier

Remplace le champ par le contenu du fichier. Nomfichier peut être une chaîne fixe ou une expression composée de champs de variable PHP qui retourne le chemin du fichier.
L'utilisation de ce paramètre est détaillée dans la rubrique insertion de fichier.

script=nomfichier

Exécute le script PHP juste avant le remplacement du champ. Depuis ce script, vous pouvez lire et modifier la valeur du champ grâce à la variable globale $tbs_CurrVal.
Nomfichier peut être une chaîne fixe ou une expression composée de champs de variable PHP qui retourne le chemin du fichier.
Remarques :
- Le script sera exécuté comme si il était codé dans une fonction. Par conséquent, les variables globales ne seront pas reconnues dans le script appelé sauf si vous les déclarez à l'aide de l'instruction Php global ou que vous utilisez $GLOBALS.
- L'exécution du script est annulée si le champ TBS contient le paramètre if avec une confition fausse.
Pour plus de détail sur l'exécution de script Php, consultez la rubrique 'Insérer le résultat d'un script Php'.

getob

S'utilise avec le paramètre script.
Indique que le texte affiché par les commandes echo() du script Php remplacent la valeur du champ TBS.

once

S'utilise avec le paramètre script.
Annule l'exécution du script s'il a déjà été appelé auparavant.

if expr1=expr2

Affiche la donnée que si la condition est vérifiée.
Si expr1 et expr2 sont des chaînes identiques (à la casse près), alors la valeur est affichée. Sinon le champ est supprimé. Vous pouvez utiliser != au lieu de = pour indiquer une condition d'inégalité. Vous pouvez utiliser le mot-clé [val] dans les expressions pour représenter la valeur de la donnée.
Les expressions peuvent contenir des champs TBS, mais vous devez vous assurer qu'ils soient fusionnés avant le champ contenant.

then val1

Si le paramètre if a été défini et que sa condition est vérifiée, alors la donnée sera replacée par val1.
Vous pouvez utiliser le mot-clé [val] dans l'expression pour représenter la valeur de la donnée.

else val2

Si le paramètre if a été défini et que sa condition n'est pas vérifiée, alors la donnée sera replacée par val2.
Vous pouvez utiliser le mot-clé [val] dans l'expression pour représenter la valeur de la donnée.

onformat=nom_fct

Indique le nom d'un fonction PHP utilisateur qui sera exécutée avant la fusion du champ. La fonction nom_fct doit avoir la syntaxe suivante :
function nom_fct($NomBloc,&$CurrVal) { ... }

Paramètre	Description
$NomBloc	Retourne le nom du champ qui appel la fonction (lecture seule).
$CurrVal	Retourne la valeur en cours (lecture/écriture ; ne pas oublier le & dans la déclaration de la variable).

protect=val

Permet de protéger ou non la donnée à fusionner en remplaçant les caractères '[' pour leur équivalent Html '['. La valeur val peut être l'un des mots-clés suivants :
yes : (valeur par défaut) la donnée est protégée.
no : la donnée n'est pas protégée.
Par défaut, toutes données fusionnées avec un modèle sont protégées sauf s'il s'agit de l'inclusion d'un autre fichier. Il est fortement recommandé de protéger les valeurs affichées lorsque qu'il s'agit de données saisies librement comme sur un forum par exemple.

max=val

Indique le nombre maximum de caractères à afficher. Au delà de cette limite, la donnée est tronquée, et des points de suspensions "..." sont ajoutés à la fin.

frm=format

Spécifie un format d'affichage pour une donnée de type date/heure ou numérique. Pour un numérique, il est possible d'utiliser un format conditionnel qui change selon le signe de la valeur.

Format date/heure :

Il s'agit d'un format semblable au format VisualBasic. Les mots-clés suivants sont reconnus :

d, dd, ddd, dddd :	numéro du jour, numéro du jour sur deux chiffres, nom du jour court, nom du jour complet. Utilisez le paramètre locale pour afficher des noms locaux.
xx	affiche st, nd, rd ou th selon le numéro du jour.
m, mm, mmm, mmmm :	numéro du mois, numéros du mois sur deux chiffres, nom du mois court, nom du mois complet. Utilisez le paramètre locale pour afficher des noms locaux.
yy, yyyy :	année sur deux chiffes, années complète.
hh, nn, ss :	heure, minutes, seconde sur deux chiffres.

Les autres caractères sont conservés.
Il est possible de mettre de protéger des chaînes texte en les plaçant entre guillemets simples ou double.

Exemples :
[chp;frm=dd/mm/yyyy] affichera 21/12/2002
[chp;frm='yyyy-mm-dd hh:nn:ss'] affichera 2002-12-21 15:45:03

Format numérique :

Pour définir la partie décimale, utilisez un expression du type '0x0...' où 'x' est le séparateur de décimal, et '0...' est une répétition de zéro correspondant au nombre de décimales.
S'il n'y a aucune décimale, utilisez le format '0.' (avec un point).

Pour définir un séparateur de milliers, utilisez une expression du type '0z000x...' où 'z' est le séparateur de milliers. S'il n'y a aucune décimale, utilisez le format '0z000.' (avec un point).

Si le format contient le caractère '%', alors la valeur affichée sera multipliée par 100. Le caractère '%' reste affiché.

Le format numérique peut contenir d'autres chaînes texte. Mais seule l'expression de zéro placée la plus à droite sera considérée comme un format, les autres caractères seront conservés.

Exemples :

Valeur	Champ	Affichage
2456,1426	[chp;frm='0,000']	2456,143
	[chp;frm='$ 0 000,00']	$ 2 456,14
	[chp;frm='$ 0 000.']	2 456
0,2537	[chp;frm='0,00 %']	25,37%
	[chp;frm='coef 0,00']	coef 0,25

Formats conditionnels :

Il est possible de définir jusqu'a 4 formats conditionnels selon que la valeur est respectivement positive, négative, zéro ou nulle (ou chaîne vide). Les formats conditionnels doivent être séparés par un caractère '|'. Chaque format conditionnel est facultatif.

Exemples :

Valeur	Champ	Affichage
2456,1426	[chp;frm='+0,00\|-(0,00)\|*\|vide']	+2456,14
-156,333	[chp;frm='+0,00\|-(0,00)\|*\|vide']	-(156,33)
0	[chp;frm='+0,00\|-(0,00)\|*\|vide']	*
null	[chp;frm='+0,00\|-(0,00)\|*\|vide']	vide
-8,75	[chp;frm='+0,00\|-(0,00)']	-(8,75)

locale

S'utilise avec le paramètre frm.
Indique que le format spécifié par frm doit afficher des noms de jours et de mois locaux.
Les informations de localisation peuvent être modifiés avec la fonction PHP setlocale().

Les champs de variable Php :

haut

Un champ de variable Php est un champ qui affiche une variable Php.
Son nom doit être composé du mot-clé 'var.' suivi du nom de la variable Php.
Les paramètres de champs standards sont valables pour les champs de variables Php.

Par exemple [var.php_version] sera remplacé par "4.2.3".

Les variables utilisateurs ainsi que variables prédéfinies peuvent être fusionnées mais elles doivent être globales. Les variables de type Object et Ressource sont ignorées.

Il est possible de fusionner une variable tableau en indiquant l'item du tableau à l'aide d'un point.
Par exemple : [var.montableau.item]

Quand sont fusionnés les champs de variable Php ?
Les champs de variable Php sont fusionnés à l'appel de la méthode Show(), c'est à dire juste avant l'affichage du résultat de la fusion. Mais vous pouvez forcer la fusion à tout moment avec la méthode MergeSpecial().

Les champs système :

haut

Un champ système est un champ TBS qui affiche des données fournies par le système TinyButStrong.
Le nom d'un champ système doit être un de la liste ci-dessous.
Les paramètres de champs TBS standards sont valables pour les champs-système.

Exemple : Date du jour : [sys.now;frm='dd/mm/yyyy']

Nom	Description
sys.now	Date et heure du serveur.
sys.version	La version de TinyButStrong.
sys.script_name	Le nom du fichier PHP en cours d'exécution.
sys.template_name	Le nom du dernier fichier modèle chargé. Il s'agit du nom tel que indiqué lors de l'appel à la méthode LoadTemplate().
sys.template_date	La date de création du dernier fichier modèle chargé.
sys.template_path	Le répertoire du dernier fichier modèle chargé. Il s'agit du répertoire tel que indiqué lors de l'appel à la méthode LoadTemplate().

Quand sont fusionnés les champs système ?
Les champ système sont fusionnés à l'appel de la méthode Show(), c'est à dire juste avant l'affichage du résultat de la fusion. Mais vous pouvez forcer la fusion à tout moment avec la méthode MergeSpecial().

Les blocs TBS :

haut

Un bloc TBS permet d'afficher les données d'une source d'enregistrements.
La fusion entre un bloc et des données est réalisée grâce à la méthode MergeBlock().

Lors de la fusion, le bloc TBS est répété autant de fois qu'il y a d'enregistrements ; et les champs TBS associés sont remplacés par les valeurs des colonnes.
Un champ fusion associé au bloc Bloc1 et qui affiche la valeur de la colonne ColonneA doit être nommé Bloc1.ColonneA
Exemple : [Bloc1.ColonneA;frm='dd-mm-yyyy']

Deux blocs portant le même nom seront considérés comme deux sections du même bloc (voir sections de bloc).

Syntaxes des blocs :

Il existe trois syntaxes possibles pour définir un bloc TBS :

Syntaxe explicite :

On utilise deux balises TBS. L'une pour le début du bloc, l'autre pour la fin du bloc.

Exemple :
HTML...[NomBloc;block=begin;params]...HTML...[NomBloc;block=end]...HTML

Les balises TBS de définition du bloc seront supprimées lors de la fusion.

Syntaxe relative :

Le bloc est défini par un couple de balises Html ouvrante-fermante. Il suffit alors d'une seule balise TBS.

Exemple :
HTML...<nom_balise...>...[NomBloc;block=nom_balise;params]...</nom_balise...>...HTML

La balise TBS de définition du bloc doit se trouver n'import où entre le couple de balises Html.
Cette balise TBs sera supprimée lors de la fusion.

Syntaxe simplifiée :

On utilise un champ TBS associé pour définir le bloc de façon relative (voir syntaxe relative ci-dessus).

Exemple :
HTML...<nom_balise...>...[NomBloc.NomColonne;block=nom_balise;params]...</nom_balise...>...HTML

Le champ TBS qui contient la définition du bloc doit se trouver entre le couple de balises Html.
Mais ce n'est pas obligatoirement le premier champ TBS du bloc.

Élément	Description
NomBloc	Est le nom du bloc.
block=begin	Désigne le début du bloc.
block=end	Désigne la fin du bloc.
block= nom_balise	Désigne un bloc qui en compris entre la balise Html ouvrante <nom_balise...> et la balise fermante </nom_balise...> qui encadrent la balise TBS. Les balises Html ouvrantes et fermantes font partie du bloc. - row peut être utilisé comme alias pour désigner la ligne d'un tableau. block=row équivaut à block=tr. - opt peut être utilisé comme alias pour désigner un item d'un liste Html. block=opt équivaut à block=option.
params	Facultatif. Un ou plusieurs paramètres de la liste ci-dessous. Séparés par des ';'.

Quelle syntaxe utiliser ?

La syntaxe 'explicite' est rarement utilisée avec des éditeurs visuels parce que les balises TBS doivent souvent être placés entre deux balises Html. Par contre, elle convient assez bien pour des éditeurs textuels.

La syntaxe 'relative' permet de désigner un bloc avec seulement une balise TBS. De plus, on pas besoin de cacher la balise TBS car elle sera supprimée lors de l'affichage. Cette syntaxe est assez pratique.

La syntaxe 'simplifiée' est réellement simple. Elle permet de définir un bloc TBS et un champ TBS avec une seule balise TBS. Cette syntaxe est la plus courante et la plus pratique.

Astuce :
Vous pouvez utiliser la syntaxe 'relative' ou 'simplifiée' avec des balises presonnelles ayant la norme Html.
Exemple :
<balise_perso>Bonjour [blk1.colonne1;block=balise_perso], comment allez vous ?</balise_perso>

Paramètres des blocs :

Paramètre

Description

extend=n

S'utilise avec la syntaxe relative ou simplifiée.
Étend la définition du bloc sur les n couple(s) de balises supplémentaire(s) qui suivent.
Cela permet, par exemple, de définir un bloc sur deux lignes d'un tableau.
La valeur de n doit être un entier différent de 0.
Si n est négatif, le bloc est étendu sur les couples de balises précédentes.

encaps=num

Indique le niveau d'encapsulation de la balise TBS par rapport aux balises Html spécifiées par le paramètre block. Par défaut cette valeur est à 1.

Exemple :

[bloc1.champ1;block=tr;encaps=2]

[bloc1.champ2]

Dans l'exemple ci-dessus, la ligne bleu sera dupliquée lors de la fusion car on a 'encaps=2'.
Si on met 'encaps=1' ou si on retire le paramètre, ce sera la ligne rose qui sera dupliquée lors de la fusion.

comm

Ce paramètre permet d'étendre les limites de la balise TBS jusqu'aux limites de la balise commentaire Html qui l'entoure.
 est rigoureusement identique à [bloc1;block=tr]
Ce paramètre facilite l'élaboration du modèle avec un éditeur HTML visuel (tel que Dreamweaver ou FrontPage).

nodata

Désigne une section qui ne s'affiche que s'il n'y a aucune donnée à fusionner.

Exemple :

[bloc1.champ1;block=tr]	[bloc1.champ2]
[bloc1;block=tr;nodata]Il n'y a aucune donnée.

Pour plus d'information sur les sections, voir le paragraphe 'sections de bloc'.

headergrp=colnom

Désigne une section qui sera affiché chaque fois que la colonne colnom. prend une valeur différente de la précédente. colnom doit être un nom de colonne valide retourné par la source de données.
Vous pouvez définir plusieurs sections headergrp sur des colonnes différentes.

Pour plus d'information sur les sections, voir le paragraphe 'sections de bloc'.

serial

Indique que le bloc est un bloc principal qui contient une série de blocs secondaires.
Pour plus d'information, voir le paragraphe 'Affichage en série (en colonne)'.

p1=val1

Signal l'utilisation d'une requête dynamique. Toutes les occurrences de la chaîne '%p1%' trouvées dans la requête passée à la méthode MergeBlock() sont remplacées par la valeur val1.
Pour plus d'information, voir le paragraphe 'Requêtes dynamiques / sous blocs'.

onsection=nom_fct

Indique le nom d'un fonction PHP utilisateur qui sera exécutée pendant la fusion du bloc. La fonction est appelée à chaque fois qu'un enregsitrement est affiché. La fonction nom_fct doit avoir la syntaxe suivante :
function nom_fct($NomBloc,&$CurrRec,&$DetailSrc,$RecNum) { ... }

Paramètre	Description
$NomBloc	Retourne le nom du bloc qui appel la fonction (lecture seule).
$CurrRec	Retourne un tableau associatif contenant l'enregistrement en cours (lecture/écriture ; ne pas oublier le & dans l'entête de la fonction). Si vous affectez la valeur False à cette variable, cela termine la fusion du bloc comme si c'était la fin du jeu d'enregistrement.
$DetailSrc	Retourne le source de la section en cours (lecture/écriture ; ne pas oublier le & dans l'entête de la fonction). Si vous affectez la valeur '' à cette variable, cela annule l'affichage de cet enregsitrement.
$RecNum	Retourne le numéro de l'enregistrement en cours (lecture seule, le premier enregistrement est le numéro 1).

if expr1=expr2

S'utilise uniquement avec les champs tbs_check. Affiche le bloc que si la condition est vérifiée.
Si expr1 et expr2 sont des chaînes identiques (à la casse près), alors le bloc est affiché. Sinon le bloc est supprimé. Vous pouvez utiliser != au lieu de = pour indiquer une condition d'inégalité.
Les expressions peuvent contenir des champs TBS mais vous devez vous assurez qe ces champs TBS soient fusionnés avant le traitement du bloc.

else

S'utilise uniquement avec les champs tbs_check. Indique un bloc conditionnel qui ne doit s'afficher que si aucun des autres blocs du même nom n'a été affiché.

Sections de bloc :

haut

Différents blocs portant le même nom seront considérés comme des sections du même bloc.
Les sections peuvent servir pour :
- alterner la présentation (sections normales),
- afficher quelque chose si il n'y a aucun enregistrement (section NoData),
- afficher un entête à chaque changement de la valeur d'une colonne (section HeaderGrp).

Sections normales :

Quand vous définissez plusieurs sections normales, elles seront utilisées de façon alternatives à chaque enregistrement.

Exemple :

[b1.libelle;block=tr]

Dans cet exemple, le bloc nommé 'b1' contient deux sections normales. Les enregistrements seront affichés alternativement avec un fond vert puis un fond bleu.

Section NoData :

Affiche la section si la source de données de contient aucun enregistrement.
La section NoData est définie en ajoutant le paramètre nodata.

Exemple :

[b1.libelle;block=tr]

Il n'y a rien[b1;block=tr;nodata]

Section HeaderGrp :

Affiche une section entête à chaque fois que la valeur d'une colonne du jeu d'enregistrement change.
Une section Header est définie en ajoutant le paramètre headergrp=nom_colonne.

Exemple :

Année [b1.annee;block=tr;headergrp=annee]
[b1.libelle]	[b1.montant;block=tr]

Affichage en série (en colonnes) :

haut

L'affichage en série permet d'afficher plusieurs enregistrements dans un même bloc. Pour cela, on utilise un bloc principal et des blocs secondaires.

Exemple :

Enr 1

Enr 2

Enr 3

Enr 4

Enr 5

Enr 6

Enr 7

Enr 8

Enr 9

...

Dans cet exemple, les blocs principaux sont les lignes bleues du tableau, les blocs secondaires sont les cases roses.

Syntaxe :
Le bloc principal et ses blocs secondaires sont fusionnés à l'aide d'un seul appel à la méthode MergeBock(). Le bloc principal doit être défini en utilisant le paramètre serial. Les blocs secondaires doivent être inclus dans le bloc principal. Leur nom de bloc doit être celui du bloc principal suivi de "_" puis du numéro d'ordre d'affichage.

Exemple :

[bx;block=tr;serial][bx_1.txt;block=td]

[bx_2.txt;block=td]

[bx_3.txt;block=td]

[bx_4.txt;block=td]

Le code PHP correspondant est :
$TBS->MergeBlock('bx',$cnx_id,'SELECT txt FROM t_info ORDER BY txt')

Bloc secondaire vide :
Vous pouvez désigner un bloc secondaire spécial qui sera utilisé en remplacement des blocs secondaires inexploités (sans enregistrement). Ce bloc secondaire "vide" doit avoir l'indice 0. Il peut être placé dans un bloc principal avec les blocs secondaires normaux, ou alors seul dans autre bloc serial. Le bloc secondaire "vide" est facultatif.

Exemple :

[bx;block=tr;serial][bx_1.txt;block=td]

[bx_2.txt;block=td]

[bx_3.txt;block=td]

[bx_4.txt;block=td]

[bx;block=tr;serial][bx_0;block=td] Vide

Remarque :
L'affichage en série marche aussi avec les sections de bloc et les requêtes dynamiques.

Requêtes dynamiques / sous-blocs :

haut

Principe des requêtes dynamiques :

Il est possible d'utiliser la méthode MergeBlock() avec une requête dynamique.
Dans votre modèle, vous devez définir un bloc en ajoutant les paramètres p1, p2, p3,... avec leurs valeurs.
La requête passée à la méthode MergeBlock() doit contenir des marqeurs %p1%, %p2%, %p3%, ... pour acueillir les valeurs des paramètres p1, p2, p3,... .

Chaque section du bloc à fusionner contenant un paramètre p1 sera traité comme un bloc à part pour lequel on ré-exécute la requête dynamique. Les sections du bloc sui n'ont pas de paramètre p1 sont rattachées à la section avec paramètre p1 qui précède.

Exemple :

[blk.ville;block=tr;p1='france']

[blk.pays]

[blk.ville;block=tr;p1='us']

[blk.pays]

Code PHP correspondant :
$TBS->MergeBlock('blk',$cnx_id,"SELECT ville,pays FROM t_geo WHERE (pays='%p1%')")

Résultat de la fusion :

Paris	france
Toulouse	france

Washington	us
Boston	us

Utilisation avec des sous-blocs :

Les requêtes dynamiques vous permettent de réaliser simplement un système de bloc-principal / sous-blocs. Voici comment vous pouvez faire :
- Créez un bloc principal, puis un sous-bloc contenu dans le bloc principal.
- Liez-les en ajoutant au sous-bloc un paramètre p1 qui prend pour valeur un champ du bloc principal.
- Du côté PHP, fusionnez d'abord le bloc principal, puis le sous-bloc.

Exemple :

Pays : [princ.pays;block=table]

[sub.ville;block=tr;p1=[main.pays_id]]

Code PHP correspondant :
$TBS->MergeBlock('princ',$cnx_id,'SELECT pays,pays_id FROM t_pays')
$TBS->MergeBlock('sub',$cnx_id,'SELECT ville FROM t_ville WHERE (pays_id=%p1%)')

Résultat de la fusion :

Pays : France

Paris

Toulouse

Pays : Allemagne

Berlin

Munique

Pays : Espagne

Madrid

Barcelone

Remarques :
- Le paramètre htmlconv=esc permet de passer à la requête des valeurs chaînes protégées.
- Les les requêtes dynamiques marchent aussi avec les sections de bloc et l'affichages en série.

Affichage d'une barre de navigation :

haut

TinyButStrong est capable d'afficher une barre de navigation à partir de blocs spécifiques.
La barre est fusionnée grâce à la méthode MergeNavigationBar().

Exemple :

[nav.page;block=td]

[nav.page;block=td;currpage]

Code Php utilisé :
$TBS->MergeNavigationBar('nav',10,17) ;

Résultat de la fusion:

Remarque : cet exemple n'affiche pas de lien.

Voici les éléments que vous pouvez utiliser pour construire votre barre de navigation :
- Utilisez un bloc TBS normal pour afficher les numéros de pages normales.
- Utilisez un autre bloc TBS du même nom mais avec le paramètre currpage pour afficher la page courante de façon différente.
- Utilisez les champs suivants où vous voulez (dans un bloc ou hors d'un bloc) :

Nom du champ	Description
page	Retourne le numéro d'une page normale accessible depuis la barre de navigation. Ce champ doit être contenu dans un bloc.
curr	Retourne le numéro de la page courante.
first	Retourne le numéro de la première page (1).
prev	Retourne le numéro de la page précédente.
next	Retourne le numéro de la page suivante.
last	Retourne le numéro de la dernière page si il est connu, sinon, retourne -1.

(Tous les éléments doivent être préfixés par le nom du navigateur suivi d'un point. Comme pour un bloc normal.)

Astuce :
Si vous utilisez le paramètre endpoint sur ces champs, alors lorsque la page courante est sur la première ou la dernière page, les champs correspondants retourneront une chaîne vide ('') au lieu d'un numéro de page. Cela permet de gérer des exceptions d'affichage avec la propriété friend par exemple.

Exemple :
<a href="script.php?page=[nav.first;endpoint;friend2=a]">Début</a>

Dans cet exemple, le lien sera supprimé lorsque la page courante est la première page.

Insérer un sous-modèle :

haut

Si un champ TBS contient le paramètre file, alors ce champ sera remplacé par le contenu du fichier désigné au moment de la fusion de ce champ. La valeur du paramètre file peut être une chaîne texte ou une expression composée de champs de variable Php [var.*] et de mots-clés [val] (voir définition de champ TBS).

TinyButStrong récupère le contenu du fichier source tel quel. Si c'est un script Php, ce script ne sera pas exécuté. Pour insérer le résultat d'un script Php, voir la rubrique 'Insérer le résultat d'une script Php'.
Si le fichier à insérer est un fichier Html, TinyButStrong ne conservera que le corps du fichier (délimité par les balises <body> et </body>).
Le paramètre htmlconv (facultatif) permet de préciser si le contenu du fichier doit être converti en Html ou non. Par défaut il n'est pas converti en Html.

Exemples :

[var.page_entete;file=[val]]

[var.page_pied;file=pied.htm;htmlconv=yes]

Préciser à quel moment est inséré le sous-modèle :

Utilisez les champs spéciaux nommés tbs_include.onload et tbs_include.onshow pour préciser à quel moment le champ doit être fusionné.
- Un champ nommé tbs_include.onload est fusionné automatiquement lors de l'appel à la méthode LoadTemplate(), juste après le chargement du modèle.
- Un champ nommé tbs_include.onshow est fusionné automatiquement lors de l'appel à la méthode Show().

Exemples :

[tbs_include.onload;file=[var.article]]

[tbs_include.onshow;file=pied.htm]

Insérer le résultat d'un script Php :

haut

Si un champ TBS contient le paramètre script, alors le script désigné sera exécuté au moment de la fusion de ce champ. La valeur du paramètre script peut être une chaîne texte ou une expression composée de champs de variable Php [var.*] ou du mot clé [val] (voir définition de champ TBS).

Exemples :

[var.traitement_special;script=[val];getob]

[tbs_include.onshow;script=fin.php;once]

Vous pouvez utiliser les variables globales de TinyButStrong dans votre script.

Portée des variables :

Le script sera exécuté comme si il était codé dans une fonction. Par conséquent, les variables globales ne seront pas reconnues dans le script appelé sauf si vous les déclarez à l'aide de l'instruction Php global ou que vous utilisez $GLOBALS.

Redirection des commandes d'affichage :

Si votre script Php contient des commandes d'affichage (telles que echo), alors le texte sera affiché normalement ; c'est à dire instantanément et donc avant le résultat de la fusion du modèle. Pour éviter ce comportement, vous pouvez utilisez le paramètre getob qui permet de rediriger le texte à la place du champ TBS.

Avec getob : les textes passés à la commande echo seront affichés à la place du champ TBS.

Sans getob: les textes passés à la commande echo seront affichés normalement, c'est à dire instantanément avant le résultat de la fusion.

Empêcher le script de s'exécuter plusieurs fois :

Si le nom du script risque d'apparaître plusieurs fois dans vos champ TBS, vous pouvez utiliser le paramètre once afin de limiter le script à une seule exécution.

Préciser à quel moment est exécuté le script :

Vous pouvez utiliser les champs spéciaux nommés tbs_include.onload et tbs_include.onshow pour préciser à quel moment le script doit être exécuté. Pour plus 'info sur ces champs spéciaux, consultez la rubrique 'Insérer un sous-modèle'.

Affichage conditionnel :

haut

TinyButStrong offre plusieurs outils pour gérer l'affichage conditionnel d'un champ ou d'un bloc.
Pour un champ qui retourne une valeur, vous pouvez utiliser les paramètres des champs standards, rappelés ci-après. Pour les autres cas, vous pouvez utiliser les balises TBS spéciales nommées tbs_check. Elles ne retournent pas de valeur et sont dédiées à l'affichage conditionnel. Leur utilisation est détaillée ci-après.

Paramètres d'affichage conditionnel pour un champ qui retourne une valeur :

Pour plus d'information sur la définition d'un champ, consultez la rubrique Les champs TBS.

	Paramètre	Description
	. (point)	Affiche un espace insécable Html si la valeur du champ est vide.
	ifempty=valeur2	Affiche valeur2 si la valeur du champ est vide.
	friend=tag	Supprime une balise ou un couple de balise si la valeur du champ est vide.
	if condition then valeur1 else valeur2	Affiche valeur1 ou valeur2 selon que la condition est vérifiée ou non.
	frm=format1\|format2\|format3\|format4	Change le format numérique ou date/heure selon que la valeur du champ est positive, négative, zéro ou vide.

Utilisation des balises tbs_check :

Les balises TBS nommées tbs_check sont des balises spéciales qui sont traitées automatiquement lors de l'exécution de la méthode Show() ou MergeSpecial(). On peut s'en servir pour un bloc ou un champ.

-> Sans suffixe :
Une balise tbs_check sans suffixe représente un champ. Il s'utilise avec les paramètres if, then et else afin d'afficher une valeur ou une autre selon la condition.

Exemple : [tbs_check;if [var.matin]=1;then 'bonjour';else 'bonsoir']

-> Avec suffixe :
Une balise tbs_check avec un suffixe représente un bloc. Il doit avoir un paramètre 'block' défini. Les blocks tbs_check avec le même suffixe sont dans un même groupe. Dans un groupe, le premier bloc avec une condition vérifiée sera affiché, les autres seront supprimés.
À l'aide du paramètre 'else', vous pouvez définir un block supplémentaire qui s'affiche lorsque aucune condition n'est véfifiée dans le groupe.

Exemple :

[tbs_check.lot1;block=tr;if [var.allume]=1]
Cette ligne est affichée si la variable $allume vaut 1.

[tbs_check.lot1;block=tr;if [var.allume]=0]
Cette ligne est affichée si la variable $allume vaut 0.

[tbs_check.lot1;block=tr;else]
Cette ligne est affichée dans les autres cas.

Résumés :

haut

Paramètres de champ TBS :

haut

Paramètre	Résumé
htmlconv	Mode de conversion Html pour la valeur du champ.
. (point)	Si la valeur du champ est vide, affiche un espace insécable.
ifempty	Si la valeur du champ est vide, affiche une autre valeur.
friend	Si la valeur du champ est vide, supprime des balises proches.
if	Si la condition est vérifiée, change la valeur affichée.
then	S'utilise avec if.
else	S'utilise avec if.
onformat	Exécute une fonction Php de l'utilisateur qui modifie la fusion du champ.
max	Limite le nombre de caractères affichés.
frm	Applique un format date-heure ou numérique.
locale	S'utilise avec frm. Affiche des noms de jours et de mois locaux.
protect	Mode de protection sur les caractères '['.
selected	Sélectionne un item dans une liste Html.
comm	Étend les limites du champ à la balise commentaire qui l'entoure.
noerr	Empêche l'affichage de certaines erreur TBS.
file	Insert le contenu du fichier.
script	Exécute le script Php.
getob	S'utilise avec script. Récupère les textes affichés par echo et les place à l'emplacement du champ.
once	S'utilise avec script. Empêche le script de s'exécuter plusieurs fois.

Paramètres de bloc TBS :

haut

Paramètre	Résumé
block	Défini les limites du bloc.
extend	Étend les limites du bloc sur plusieurs balises Html successives.
encaps	Étend les limites du bloc sur plusieurs balises Html encapsulées.
comm	Étend les limites du bloc à la balise Html commentaire..
nodata	Désigne la section qui s'affiche lorsqu'il n'y a aucun enregistrement dans la source de données.
headergrp	Désigne une section qui sera affiché que lorsque la valeur d'une colonne change.
serial	Désigne une section qui contient une série de plusieurs enregistrements.
p1	Envoie un paramètre à la requête dynamique de la source de données.
onsection	Exécute une fonction Php de l'utilisateur qui modifie la fusion de la section.
if	S'utilise avec tbs_check. Affiche le bloc si la condition est vérifiée.
else	S'utilise avec tbs_check. Affiche le bloc si aucune condition n'est vérifiée.

Champs et paramètres de barre de navigation :

haut

Champ	Résumé
nav.page	Affiche le numéro d'une page.
nav.curr	Affiche le numéro de la page en cours.
nav.first	Affiche le numéro de la première page (toujours 1).
nav.prev	Affiche le numéro de la page précédante.
nav.next	Affiche le numéro de la page suivante.
nav.last	Affiche le numéro de la dernière page (-1 si inconnu).

Paramètre	Résumé
currpage	Indique que la section ne s'affiche que pour la page en cours.
endpoint	Retourne une chaîne vide si la page courante est la première page ou la denière page.

Noms de blocs et champs spéciaux :

haut

Nom	Résumé
val	Le mot-clé [val] peut être utilisé dans des paramètres de champs pour représenter la valeur de ce champ.
var.*	Affiche une variable Php.
sys.*	Affiche une information du système TinyButStrong.
tbs_include.onload	Champ fusionné automatiquement au chargement du modèle.
tbs_include.onshow	Champ fusionné automatiquement à l'affichage du modèle.
tbs_check	Champ automatique avec conditions d'affichage.
tbs_check.*	Bloc ou groupe de blocs automatiques avec condition d'affichage.

.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.:*~*:._.: