Site : www.tinybutstrong.com
Auteur : skrol29@freesurf.fr
Date : 2003-07-01

*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*
TinyButStrong
version 1.81
*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*.^.*

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

Plan de ce fichier d'aide :
  Présentation
  Résumé des fonctionnalités supportées
  Quelques exemples
  Principes de base
  Installation
  Coté PHP
      méthode CacheAction()
      méthode GetBlockSource()
      méthode LoadTemplate()
      méthode MergeBlock()
      méthode MergeField()
      méthode MergeSpecial()
      méthode Show()
      propriété Render
      propriété Source
      variables globales
  Coté HTML
      les champs-fusion
      les blocs-fusion
      insertion de fichier
      champs de variable Php
      champs système
      affichage conditionnel

 

Présentation :


TinyButStrong est une classe PHP utile pour développer une application en séparant proprement vos scripts PHP de vos pages HTML. Avec TinyButStrong, 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).

TinyButStrong tient son nom du fait qu'il ne présente que 7 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, ODBC, SQL-Server ou ADODB.

TinyButStrong 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. TinyButStrong permet aussi de créer du JavaScript dynamiquement.

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

 

Résumé des fonctionnalités supportées :
Quelques exemples :
haut

$TBS->MergeBlock("Fus","mysql","SELECT * FROM MaTable WHERE id=$id)") ;
 +
Prénom Nom Date
[Fus.Sign_Prenom] [Fus.Sign_Nom;block=row] [Fus.Sign_Date;frm=dd/mm/yyyy]
[Fus.Sign_Prenom] [Fus.Sign_Nom;block=row] [Fus.Sign_Date;frm=dd/mm/yyyy]
Il n'y a aucun nom dans la liste. [Fus;block=row;nodata]
 =>
Prénom Nom Date
Pierre DURANT 01/03/2002
Jean VALJEAN 07/09/2001
Jeanne IPONDRIE 01/03/2002
Paul LE MIEL 05/08/2003
Justin PETITBOUT 01/03/2002
Annie AIMELES 23/12/1999
         
$TBS->MergeField("TitreParagraphe","Un nouveau Monde") ;  +

[TitreParagraphe]
 =>

Un nouveau Monde
         
$TBS->MergeBlock("lst_civilite",array("-","M.","Mme","Mlle")) ; +

=>

         
$TBS->MergeField("x_civilite","Mlle") ; +

=>

 

Principes de base :
haut

Du coté HTML : vous concevez une page qui n'a pas besoin de contenir de script PHP. Dans cette page vous placez des indicateurs TinyButStrong aux endroits où doivent s'afficher les données. Cette page est appelée 'un modèle'.

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

Il existe deux types d'indicateur que vous pouvez placer dans votre modèle : les champs-fusion et les blocs-fusion. L'un pour afficher une donnée simple, et l'autre répéter une zone en se basant sur une source de données.

 

Installation :
haut

1. Copiez le fichier tbs_class.php dans un répertoire de site Web.
2. Référencez ce fichier dans votre programme PHP à l'aide de l'instruction 'include_once' ('require_once' est valable aussi).
Exemple : include_once("tbs_class.php");
3. Délcarez une variable objet qui doit être une nouvelle instance de la classe clsTinyButStrong.
Exemple : $TBS = new clsTinyButStrong ;

 

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 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})

Le système de cache permet d'accélerer 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 identifant pour chaque page sauvegardée (appelée fichier cache), ainsi qu'une période de rafraîchissement (appelé time-out). 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 time-out, alors le contenu du fichier cache est chargé et la fusion se termine. Si la date de création est plus longue que le time-out, 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.

Élément Description
CacheId Une chaîne de caratère qui identifie votre page de façon unique dans le répertoire de cache.
ActTimeOut Doit être le time-out 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 time-out, vous pouvez utiliser l'un des constantes ci-après pour déclacher une action spéciale du systèm 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.

Méthode GetBlockSource() :
haut

 

Retourne le source d'un bloc-fusion.
Seule la première définition du bloc sera retournée à moins que le paramètre Liste soit à True.
Si aucun bloc n'est trouvé, la méthode retourne la valeur False.

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

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

Cette méthode permet de récupérer le source d'un bloc afin de gérer manuelement 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 LoadTemplate() :
haut

 

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

Syntaxe : $TBS->LoadTemplate(string Fichier)

Élément Description
Fichier URL locale ou absolue du modèle à charger.

Méthode MergeBlock() :
haut

  Fusionne un bloc-fusion avec les données d'une source d'enregistrements.
Retourne le nombre d'enregistrements rencontrés.

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 ; ODBC ; SQL-Server ; ADODB.

Vous pouvez aussi coder des fonctions personnalisées pour la lecture des données (voir paragraphe 'source de données personnalisée'). Il existe aussi des fonctions toutes prêtes à la page de support sur le site Web de TinyButStrong.

Syntaxe : int $TBS->MergeBlock(string NomBloc, mixed Source{, string Requête}{, int PageTaille, int PageNum}{, int EnregConnu})
Élément Description
NomBloc Indique le nom du bloc-fusion à fusionner.
Source

Variable ou mot-clé qui désigne la source de données pour la fusion.
Le tableau ci-dessous indique les arguments 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 quand utiliser cet argument selon le type de source de données.
PageTaille Facultatif. Ce paramètre doit être défini si vous voulez activer l'affichage par page.
Indique le nombre d'enregistrement pour une page.
PageNum Facultatif. Ce paramètre 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.
EnregConnu Facultatif. La valeur par défaut est 0.
Ce paramètre n'est utile que lors de l'affichage par page. Il indique le nombre total d'enregistrement connu. Si vous indiquez une valeur supérieur ou égale à zéro, la méthode retourne ce même nombre ou le nombre d'l'enregistrement visité si il est supérieur. Si vous mettez la valeur -1, la méthode retourne le nombre total d'enregistrements dans la source de donnée même au delà de la page demandée.

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" Le texte
Nombre Le mot-clé "num" Un nombre
Tableau PHP Un tableau Php de clés et valeurs -
Un tableau Php contenant des tableaux de clés et valeurs -
MySQL Une ressource de connexion MySql
ou le mot-clé "mysql"		 Une requête SQL
Une ressource de résultat MySql -
ODBC Une ressource de connexion Odbc Une requête SQL
Une ressource de résultat Odbc -
SQL-Server (1) Une ressource de connexion MsSql
ou le mot-clé "mssql"		 Une requête SQL
Une ressource de résultat MsSql -
ADODB (2) Un objet connexion Une requête SQL
Un objet résultat -
Personnalisé
 Un mot-clé, un objet ou une ressource non listé dans ce tableau.
Voir le paragraphe 'source de données personnalisée' ci-après pour plus d'information.		 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.

Coté HTML :

Le modèle HTML doit contenir un, plusieurs ou zéro bloc-fusion correspondant au nom spécifié.
Si un seul bloc-fusion est trouvé :
  Le bloc-fusion est répété autant de fois qu'il y a d'enregistrement dans la source de données.
Les champs-fusion placés dans le bloc-fusion peuvent êtres liés par leur nom.
Chaque champ-fusion lié est remplacé par la valeur correspondante dans l'enregistrement courant.
Exemple : nom du bloc : Bloc1, colonnes retournées par la requête : Champ1,Champ2,Champ3, champs-fusion liés possibles : [bloc1.champ1], [bloc1.champ2], [bloc1.champ3]
(voir plus bas pour la fusion avec une variable PHP Array)

Si plusieurs blocs-fusions sont trouvés :
  Le principe est le même que pour la fusion avec un seul bloc, mais TinyButStrong changera de bloc à chaque enregistrement de façon à alterner la présentation de l'affichage. Cela permet par exemple changer la couleur une ligne sur deux dans un tableau. Voir exemples.

Si aucun bloc-fusion n'est trouvé :
  Les champs-fusion liés sont tout de même fusionnés. Il n'y a pas de répétition de bloc et seul premier enregistrement de la source de données est fusionné.
En d'autres termes, si vous n'avez qu'un seul enregistrement, la définition de bloc n'est pas obligatoire.

Fusion avec du texte :
Tout le bloc est remplacé par le texte spécifié. Les noms de colonnes ne sont pas gérés sauf "#" qui représente le nombre d'enregistrement, celui-ci sera toujours 1 ou 0 si le texte est une chaîne vide.

Fusion avec un nombre :
Le bloc est répété autant de fois que le nombre indiqué. Les noms de colonnes ne sont pas gérés sauf "#" qui représente le numéro d'enregistrement.

Fusion avec une variable PHP Array :
Utilisez le nom de colonne "val" pour afficher la valeur de l'item, et le nom de colonne "key" pour la clé de l'item (PHP permet d'affecter une clé à une valeur d'un tableau).
  Exemple : nom du bloc : Bloc1, champs-fusion possibles : [bloc1.val], [bloc1.key]
Voir autre exemple.
Si votre variable Array contient des valeurs qui sont elles-mêmes des Array, alors c'est différent. La fusion s'opère comme pour un jeu d'enregistrement : chaque sous-Array est considéré comme un enregistrement et leurs clés sont considérées comme les noms des colonnes.

Décompte des enregistrements :
Pour afficher le numéro d'enregistrement, utilisez un champ-fusion avec le nom de colonne "#".
Si vous le placez en dehors du bloc, il affichera le nombre total d'enregistrements.
Exemple : [bloc1.#]

Cas où il n'y a aucun enregistrement à fusionner :
Vous avez la possibilité de définir un bloc-fusion supplémentaire qui s'affiche à la place de tous les autres lorsqu'il n'y a aucun enregistrement dans la source de données. Pour plus de détail, consultez la rubrique de définition de bloc-fusion.

Source de données personnalisée :

Vous avez la possibilité de définir votre propre type de source de données à l'aide de fonctions personalisées.

Lorsque la variable $Source renseignée est une chaîne, un objet ou une ressource non supportée en natif, alors TinyButStrong recherche si il existe les trois fonctions personnalisés correspondant à cette variable.
Les trois fonctions doivent avoir la syntaxe décrite ci-dessous.

function tbsdb_customdb_open(&$Source,&$Requête) {...}
Cette fonction doit ouvrire la requête et retourner un identifiant de resultat qui sera passé aux fonctions ci-après. En cas d'erreur, elle doit retourner la valeur False et peut afficher le message correspondant.

function tbsdb_customdb_fetch(&$Rs{,$NumEnreg}) {...}
Cette fonction doit retourner un tableau associatif correspondant à l'l'enregistrement en cours, avec noms des colonnes et leur valeurs. Elle doit retourner la valeur False lorsqu'il n'y a plus d'enregistrement.
Si vous avez besoin de connaître le numéro de l'enregsitrement en cours (le premier est le numéro 1), vous pouvez ajouter le paramètre $NumEnreg à la définition de votre fonction. Mais c'est facultatif parce que les enregistrements sont appelés dans l'ordre de toute façon.

function tbsdb_customdb_close(&$Rs) {...}
Cette fonction doit femer ou libérer l'identifiant de resultat.
Elle ne retourne aucune valeur.

Le mot-clé 'customdb' dépend du contenu de la variable $Source :
Si $Source est une chaîne, alors le mot-clé correspondant est cette chaîne.
Si $Source est un objet, alors le mot-clé correspondant est le nom de la classe de cet objet.
Si $Source est une ressource, alors le mot-clé correspondant est le type ressource simplifié de manière à avoir des noms de fonctions valides. Par exemple pour connexion Sybase, une ressource de type 'sybase-db link' aura comme mot clé 'sybase_db'.

Vous trouverez le code de plusieurs type de source de données sur la page de support du site Web de TinyButStrong.

   

Méthode MergeField() :
haut

 

Remplace un champs-fusion du modèle par une valeur.

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

Élément Description
NomChamp Le nom du champ. Par exemple "Titre".
Valeur La valeur à afficher.

Coté HTML :
Si plusieurs champs-fusion portent le même nom dans le modèle, ils seront tous remplacés.
Dans la définition du champ-fusion, vous pouvez spécifier un format d'affichage numérique ou date/heure.
Il est aussi possible de forcer (ou empêcher) la conversion de la valeur en HTML. Pour plus d'info, reportez-vous à la rubrique champ-fusion.

Gestion des listes HTML :
TinyButStrong permet de sélectionner une valeur dans une liste HTML. Pour plus d'info, reportez-vous à la rubrique champ-fusion.
Vous pouvez aussi remplir une liste HTML avec le contenu d'un tableau PHP ou d'une requête avec la méthode MergeBlock().

Méthode MergeSpecial() :
haut

 

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

Syntaxe : $TBS->MergeSpecial(string Type)

La paramètre Type doit être l'une des valeurs suivantes :

Valeur Description
'var' Remplace tous les champs de variable Php.
'sys' Remplace tous les champs sytè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ésulat de la fusion. C'est pour cea qu'il est rare d'utiliser MergeSpecial() dans un script.

Méthode Show() :
haut

 

Termine la fusion.

Syntaxe : $TBS->Show()

Pour teminer la fusion, TinyButStrong exécute la fusion des champs système, des champs de variables Php ainsi que d'autres opérations. Par défaut, le résultat est affiché et le script est arrêté mais vous pouvez changer ce comportement à l'aide de la propriété Render.

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 efectuée à la fin de la fusion.
TBS_OUTPUT Indique que le résulat 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é.
Au fur et à mesure des opérations de fusion, cette propriété premet de lire ou modifier le résultat intermédiaire.

Syntaxe : string $TBS->Source

Variables globales :
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 onformat.
- 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.

 

Coté HTML :
haut

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

Il existe deux types d'indicateurs : les champs-fusion et les blocs-fusion.

Un champ-fusion est un indicateur 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-fusion est décrite ci-après.

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

Champ-Fusion :
haut

 

Un champ-fusion est un indicateur 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.
La définition d'un champ-fusion est insensible à la casse.

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

Élément Description
NomChamp Est le nom du champ-fusion.
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-fusion les uns dans les autres.

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 guillements 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 ecadrent le champ champs-fusion ainsi que tout ce qui se trouve entre les deux.
Utilisez friend2 pour effacer les balises seules.
Utilisez friendb pour effacer la balise nom_balise précédente, le champ-fusion, ainsi que tout ce qui se trouve entre les deux.
Utilisez frienda pour effacer la balise nom_balise suivante, le champ-fusion, ainsi que tout ce qui se trouve entre les deux.
Exemple : friendb=br si la donne est vide, le saut de ligne situé avant est effacé.
Les paramètres if then esle sont traités avant le paramètre friend.
selected Ce paramètre sert à sélectionner une valeur dans une liste HTML (dans un formulaire).
Le champ-fusion doit obligatoirement être placée parmi la liste des valeurs. Lors de la fusion, ce champ-fusion sera remplacé par sa donnée qui sera alors la valeur sélectionnée de la liste HTML. Si la valeur n'existe pas déjà dans la liste HTML, elle sera ajoutée. (voir exemples)
comm Ce paramètre permet d'étendre les limites de l'indicateurs jusqu'aux limites de la balise commentaire (Html) qui l'entour.
<!-- [monchamp;comm] ceci est un exemple--> 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).
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.
Il est aussi possible de spécifier des fichier à inclure automatiquement. Pour plus d'information,
consultez la rubrique insertion de fichier.
script=nomfichier Exécute le script PHP juste avant le remplacement de l'indicateur. TinyButStrong met à disposition une variable globale $tbs_CurrVal contenant le texte qui va être affiché à la place de l'indicateur. Cette variable peut être utilisée et modifiée par le script appelé.
Nomfichier peut être une chaîne fixe ou une expression composée de champs de variable PHP qui retourne le chemin du fichier.
Si le paramètre script est utilié avec le paramètre if dont la condition n'est pas vérifiée, alors l'exécution du script est annulée.
getob S'utilise avec le paramètre script.
Détourne les chaînes texte passées à la commande 'echo' lors de l'exécution du script PHP, puis les affiche à la place du champ-fusion.
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é. 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-fusion. Dans ce cas, vous devrez vous assurer que les champs-fusion imbriqués soient fusionnés avant le champ-fusion qui les contient.
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

Permet de définir une fonction évènementielle PHP qui s'exécute juste avant la fusion du champ.
nom_fct doit être le nom d'une fonction PHP utilisateur existante avec la syntaxe suivantes :
  function nom_fct($NomChamp,&$CurrVal) { ... }
$NomChamp représente le nom complet du champ en cours du fusion.
$CurrVal représente la valeur à fusionner.
Le symbole & qui figure devant le nom de variable dans la déclaration de la fonction doivent être conservés afin que cet arguments soient passé par référence.
Attention : si vous modifiez la valeur de $CurrVal, cela se répercute sur la fusion en cours.
protect=val Permet de protéger ou non la donnée à fusionner en remplacant les caractères '[' pour leur équivalent Html '&#91;'. 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 recommendé 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. Le format est une chaîne qui contient une ou plusieurs expressions de mise en forme. Vous pouvez aussi spécifier un format conditionnel qui change selon le signe de la valeur à formater.

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.
- m, mm, mmm, mmmm : numéro du mois, numéros du mois sur deux chiffres, nom du mois court, nom du mois complet.
- 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 dans un format 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éfnir 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 mutlipliée par 100.

Le format numérique peut contenir d'autres chaînes texte. Seule l'expression de zéro placée la plus à droite sera remplacée par la valeur formatée, les autres caractères seront seront conservés.

Exemples :
Valeur Champ-fusion 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 condiditionnels doivent être séparés par un caractère '|'. Chaque format conditionnel est falcultatif.

Exemples :
Valeur Champ-fusion 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)

Sensibilité à la casse :
TinyButStrong est insensible à la casse dans les modèles, y compris pour le codage des champs-fusion.

Bloc-Fusion :
haut

  Un bloc-fusion 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, un bloc-fusion standard est repété autant de fois qu'il ya d'enregistrement ; et les champs-fusion 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']

Vous pouvez définir des blocs-fusion plus élaborés en utilisant
- des paramètres de bloc,
- des blocs multi-sections (alternées ou spéciales),
- des sous-blocs (affichage en série ou multi-colonnes),
- des blocs clone (utilisant une requête paramétrée).

Syntaxes des blocs :

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

Syntaxe explicite :
  On utilise deux indicateurs. L'un pour le début du bloc, l'autre pour la fin du bloc.
HTML...[NomBloc;block=begin]...HTML...[NomBloc;block=end;params].. HTML

Syntaxe relative :
  Le bloc est défini par un couple de balises ouvrante-fermante. Il suffit alors d'un seul indicateur.
HTML ...<nom_balise...>... [NomBloc;block=nom_balise;params] ...</nom_balise...>...HTML

Syntaxe simplifiée :
  On utilise un champ-fusion associé pour définir le bloc de façon relative (voir syntaxe relative ci-dessus).
HTML ...<nom_balise...>... [NomBloc.NomColonne;block=nom_balise;params] ...</nom_balise...>...HTML

Élément Description
NomBloc Est le nom du bloc-fusion.
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 ouvrante <nom_balise...> et la balise fermante </nom_balise...> qui encadrent l'indicateur. Les balises 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 ses indicateurs 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 un indicateur. De plus, on pas besoin de cacher l'indicateur car il 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-fusion et un champ fusion avec un seul indicateur. Cette syntaxe est la plus courante et la plus pratique.

Paramètres des blocs :

Paramètre Description
extend=n
lengthen
prolong
widen 		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 l'indicateur par rapport aux balises spécifiées par le paramètre block. Par défaut cette valeur est à 1.

Exemple :

[bloc1.champ1;block=row;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 l'indicateurs jusqu'aux limites de la balise commentaire (HTML) qui l'entour.
<!-- [bloc1;block=row;comm] ceci est un exemple--> est rigoureusement identique à [bloc1;block=row]
Cette option 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=row] [bloc1.champ2]
[bloc1;block=row;nodata]Il n'y a aucune données.

Pour plus d'information sur les sections, voir le paragraphe 'Blocs multi-sections'.
headergrp=colnom Désigne une section qui sera affiché en entête à chaque changement de valeur de la colonne colnom.
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 'Blocs multi-sections'.
serial Indique que le bloc contient une série de sous-blocs.
Pour plus d'information, voir le paragraphe 'Sous-blocs'.
p1=val1 Indique le début d'un bloc clone. Dans la requête de la source de données, le mot-clé '%p1%' sera remplacée par la valeur val1 du paramètre p1.
Pour plus d'information, voir le paragraphe 'Blocs clone'.
onformat=nom_fct

Permet de définir une fonction évènementielle sur le formatage du bloc.
La fonction sera exécutée avant la fusion de chaque section de détail du bloc.
nom_fct doit être le nom d'une fonction PHP utilisateur existante avec la syntaxe suivantes :
  function nom_fct($NomBloc,&$CurrRec,&$DetailSrc,$RecNum) { ... }
$NomBloc représente le nom du bloc en cours du fusion.
$CurrRec représente l'enregistrement en cours de fusion sous forme de tableau avec clés.
$DetailSrc représente le source de la section avant sa fusion avec l'enregistrement.
$RecNum représente le numéro de l'enregistrement en cours de fusion.
Le symbole & qui figure devant le nom des variables dans la déclaration de la fonction doivent être conservés afin que ces arguments soient passés par référence. Attention : si vous modifiez ces valeurs cela se répercute sur la fusion en cours. Par exemple, si vous codez $CurrRec = False ; cela stop la fusion du bloc. Si vous codez $DetailSrc = '' ; cela annule la fusion uniquement pour l'enregistrement en cours.
if expr1=expr2 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 la valeur est affiché. Sinon le champ est supprimé. Vous pouvez utiliser != au lieu de = pour indiquer une condition d'inégalité.
Les expressions peuvent contenir des champs-fusion. Dans ce cas, vous devrez vous assurer que les champs-fusion imbriqués soient fusionnés avant le champ-fusion qui les contient.
else Indique un bloc conditionnel qui ne s'affiche que si aucune des conditions des autres blocs du même nom de sont vérifiées.

Blocs multi-sections (alternées ou spéciales) :

Lorsque vous définissez plusieurs blocs avec le même nom, ils constituent des sections du bloc.
Les sections qui contient le paramètre nodata ou headergrp sont des sections spéciales décrites dans le tableau plus haut, les autres sont des sections standard.
Si il existe plusieurs sections standards qui se suivent, elles seront alternée à chaque enregistrement. Cela permet de créer des motifs.

Exemple :

[b1.libelle;block=row]
[b1.libelle;block=row]
Rien[b1;block=row;nodata]

L'exemple ci-dessus montre un bloc multi-sections composés de deux sections aletrnées vert-bleu et d'une section spéciale 'nodata'.


Il est possible de combiner les multi-sections avec des sous-blocs ou des blocs clones.

Sous-blocs (affichage en série) :

Les sous-blocs permettent d'afficher une série de plusieurs enregistrements par bloc. Par exemple, cela peut servir pour faire un affichage multi-colonnes.
Vous devez indiquez qu'un bloc contient des sous-blocs en lui ajoutant le paramètre serial. Les sous-blocs devront être contenu dans leur bloc parent et leur nom doit être celui de leur bloc parent suivi de '_' puis de l'indice de série (en commencant par 1).

Sous-bloc vide :
Vous pouvez désigner un sous-bloc qui sera utilisé en remplacement des sous-block inexploités. Ce sous-bloc 'vide' doit avoir l'indice 0. Il peut être placé dans un bloc serial normal en plus des sous-blocs normaux, ou peut être placé seul dans autre bloc serial. Le sous-bloc vide est facultatif.

Exemple :

[bx.;block=row;serial][bx_1.champ1;block=td] [bx_2.champ1;block=td] [bx_3.champ1;block=td]
[bx.;block=row;serial][bx_0;block=td] Vide    

Dans cet exemple il y a un affichage multi-colonnes sur trois colonne avec définition d'une case vide.

Il est possible de combiner des sous-bloc avec des multi-sections ou des blocs clones.

Blocs clone (et requête paramétrée) :

Les blocs clone sont des blocs du même nom et qui seront fusionnés par un seul appel à la méthode MergeBlock(). Ils se distinguent des multi-sections par la présence du paramètre p1 au début d'un bloc clone. Ils peuvent éventuellement avoir d'autres paramètres p2, p3,... mais p1 est obligatoire.

Pour chaque bloc clone, la requête SQL passée à la méthode MergeBlock() est modifée gâces aux paramètres du bloc. Chaque mot-clé '%p1%', '%p2%', '%p3%'... placés dans la requête SQL sera remplacés par les paramètres p1, p2, p3...
Si les valeurs des paramètres sont des chaînes, le paramètre htmlconv=esc peut se réveler utile.

Exemple de définition de trois blocs clone :

Villes de France : [blc.ville;block=row;p1=99]
Villes d'Italie : [blc.ville;block=row;p1=98]
Villes d'Espagne : [blc.ville;block=row;p1=97]

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

Les blocs clone peuvent avoir des multi-sections et des sous-blocs.

Sensibilité à la casse :
TinyButStrong est insensible à la casse dans les modèles, y compris pour le codage des blocs-fusion.

Insertion de fichier :
haut

 
Vous avez la possibilité d'insérer le contenu d'un autre fichier à un endroit voulu dans votre modèle.
  Pour définir un fichier à insérer juste après le chargement du modèle, utilisez un champ-fusion nommé tbs_include.onload.
  Pour définir un fichier à insérer juste avant l'affichage du résultat, utilisez un champ-fusion nommé tbs_include.onshow.
  Pour définir un fichier qui s'insère à un momment choisi par vous dans votre programme PHP, utilisez un champ-fusion avec un autre nom et fusionnez ce champ à l'aide de la méthode MergeField().

Le fichier à inlure est défini par le paramètre file du champ-fusion. La valeur de ce paramètre peut être une expression composée de champs de variable PHP.
.
Syntaxe : HTML ...[nomchamp;file=nomfichier{;script=nomfichier{;once{;htmlconv=val}}}]...HTML

Paramètre Description
file=nomfichier nomfichier est le chemin d'accès du fichier à inclure.
Ce peut être une expression composées de champs-fusion de variables PHP (préfixés 'var.')
script=nomfichier Exécute le script PHP juste avant le remplacement de l'indicateur. TinyButStrong met à disposition une variable globale $tbs_CurrVal contenant le texte qui va être affiché à la place de l'indicateur. Cette variable peut être utilisée et modifiée par le script appelé.
Nomfichier peut être une chaîne fixe ou une expression composée de champs de variable PHP qui retourne le chemin du fichier.
Si le paramètre script est utilié avec le paramètre if dont la condition n'est pas vérifiée, alors l'exécution du script est annulée.
once S'utilise avec le paramètre script. Annule l'exécution du script s'il a déjà été appelé auparavant.
htmlconv=val

Facultatif. Permet de forcer ou empêcher la conversion de contenu du fichier en texte HTML.
La valeur val peut être l'un des mots-clés suivants :
  yes : force la conversion en HTML.
  no : empêche la conversion en HTML.
  look : convertie le contenu du fichier en HTML si aucune balise HTML n'est trouvé à l'intérieur.

Exemples :
 [tbs_include.onload;file='frame_gauche.htm'] : fichier inclu juste après le chargement du modèle.
[tbs_include.onload;file=[var.monfichier]] : fichier inclu juste après le chargement du modèle.
[tbs_include.onshow;file=[var.monfichier]] : fichier inclu juste avant l'affichage du modèle.

Insertion d'une page HTML :
Dans le cas où le fichier inséré est une page HTML, TinyButStrong ne gardera que source compris entre les balises <BODY> et </BODY>.
Ceci permet concevoir le fichier à insérer comme si c'était une page HTML indépendante.

Champs de variable Php :
haut

 

Un champ de variable Php est un champ-fusion 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-fusion standards sont valables pour les champs de variables Php.

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

Les champs-fusion n'ont pas besoin de respecter la casse des variables PHP correspondantes.
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 indicant 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().

Champs système :
haut

 

Un champ système est un champ-fusion qui affiche des données propre au moteur TinyButStrong.
Le nom d'un champ-système doit être un de la liste ci-dessous.
Les paramètres de champs-fusion 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().
sys.merge_time La durée d'exécution de la fusion en seconde avec 8 décimales.
sys.script_time La durée d'exécution du programme en seconde avec 8 décimales.
(à partir de l'instruction 'include_conce' qui charge TinyButStrong)

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().

Affichage conditionnel :
haut

 

Les champs-fusion et des blocs-fusion peuvent contenir des paramètres qui permettent de les afficher ou de les supprimer selon une condition.
La syntaxe des conditions d'affichage est détaillée aux chapitres champs-fusion et blocs-fusion.

Afficher un bloc parmi plusieurs blocs :

Si vous définissez plusieurs blocs avec le même nom, alors un seul sera affiché. Celui qui sera affiché est le premier dont la condition est vérifiée ; les autres seront supprimés.
Vous pouvez aussi utiliser le paramètre 'else' pour définir un bloc qui ne s'affiche que si toutes les autres conditions sont fausses.

Automatiser la fusion des champs des blocs conditionnels :

Si le nom de votre champ ou bloc est préfixé par 'tbs_check.' alors ils sera fusionné automatiquement lors de l'appel de la méthode Show().
Les champs peuvent être nommés 'tbs_check' sans suffixe.

Si vous donnez un nom quelconque à votre champ ou bloc, il ne sera pas fusionné automatiquement et il faudra faire appel à la méthode MergeField() ou MergeBlock() au moment voulu dans votre programme.

Exemples de champs conditionnels :

ex1 :
[var.matin;if [val]=1;then 'bonjour';else 'bonsoir']
  identique à
[tbs_check;if [var.matin]=1;then 'bonjour';else 'bonsoir']

ex2 : href="bouton_[var.allume;if [val]=1;then 'on';else 'off'].gif"

Exemples de blocs conditionnels :

[tbs_check.lot1;block=row;if [var.allume]=1]
Cette ligne est affichée si la variable $allume vaut 1.
[tbs_check.lot1;block=row;if [var.allume]=0]
Cette ligne est affichée si la variable $allume vaut 0.
[tbs_check.lot1;block=row;else]
Cette ligne est affichée dans les autres cas.


 

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