Présentation

CopixZone est un tag essentiellement destiné à permettre aux designers de templates d'appeler des zones depuis Smarty.

Ce tag peut fonctionner selon 3 modes, déterminés selon les paramètres :

Mode basique

Mode par défaut, utilisé si aucun des paramètres marqués "Javascript" ou "AJAX" n'est utilisé.

CopixZone::process() est appelé immédiatement et son résultat est inclus dans la page générée.

Mode Javascript

Ce mode est activé si un paramètre marqué "Javascript" ou "AJAX" est utilisé.

Tout comme dans le mode basique, CopixZone::process() est appelé immédiatement et son résultat est inclus dans la page générée.

Toutefois, ce contenu est encapsulé dans une balise DIV qui va servir à gérer les événements Javascript.

Si text ou idClick est fourni, la zone sera cachée par défaut et il faudra cliquer sur le texte où l'élément DOM identifié par "idClick".

Mode AJAX

Ce mode est activé si le paramètre ajax est utilisé.

Ce mode est similaire au mode Javascript à ceci près que CopixZone::process() n'est pas appelé : les paramètres de la zone sont stockés en session et seule une balise DIV vide est générée.

Le contenu de la zone sera généré via une requête AJAX lorsque la balise DIV recevra l'événement "display". Cela peut se produire soit en envoyant soi-même l'événément, soit en utilisant text ou idClick.

La requête AJAX fait appel à l'action "generictools|ajax|getZone". Le système est prévu pour garder les paramètres de zone confidentiels. En outre, CopixZone::process() ne sera appelée qu'une seule fois : la première fois qu'on demande l'affichage de la zone.

Exemple Smarty

{copixzone process=idZone param1=value param2=value2}

{* équivaut à l'appel PHP *}
{* CopixZone::process ('idZone', array ('param1'=>'value', 'param2'=>'value2')); *}

Paramètres

Pour chaque paramètre est indiqué entre parenthèse le mode de fonctionnement que son utilisation implique.

process (basique)

Chaîne, obligatoire: nom de la zone.

zoneParams (basique)

Tableau: tableau de paramètres à passer à la zone, correspond au deuxième argument de CopixZone::process().

Exemple :

Code PHP:

<?php
$tpl = new CopixTpl();
$tpl->assign('params', array('x'=>5, 'truc'=>8));
return $tpl->fetch('monTemplate.tpl');
?>

Contenu de monTemplate.tpl:

{copixzone process='module|zoneId' zoneParams=$params}

{* équivaut à : *}
{* CopixZone::process ('module|zoneId', array ('x' => 5, 'truc' => 8)); *}

zoneParams_* (basique)

Mixed : paramètres supplémentaires à passer à la zone. Ils sont ajoutés au contenu de zoneParams sans le préfixe "zoneParams_". Cela permet de remplacer des valeurs par défaut de zoneParams ou de passer des paramètres de zone qui ont le même nom que des paramètres du tag.

Exemple :

Code PHP:

<?php
$tpl = new CopixTpl();
$tpl->assign('params', array('x'=>5, 'truc'=>8));
return $tpl->fetch('monTemplate.tpl');
?>

Contenu de monTemplate.tpl:

{copixzone process="monModule|maZone" zoneParams_process="trucmuche"}
{* équivaut à : *}
{* CopixZone::process ('monModule|maZone', array ('process' => 'trucmuche')); *}

{copixzone process="monModule|maZone" zoneParams=$params zoneParams_val="trucmuche" zoneParams_x=22}
{* équivaut à : *}
{* CopixZone::process ('monModule|maZone', array ('x' => 22, 'truc' => 8, 'val' => 'trucmuche'))); *}

required (basique)

Booléen :

• si ce paramètre est défini, il change le comportement du tag lorsque le module qui définit la zone n'est pas installé :

true

Emet une erreur.

false

Ne génère aucun code.

• si ce paramètre est omis, aucune vérification n'est effectuée.

{* Si le module modulePasInstalle n'est pas installé, génère une erreur *}
{copixzone process="modulePasInstalle|idZone" required=true}

{* si le module modulePasInstalle n'est pas installé, alors rien ne sera affiché ici *}
{copixzone process="modulePasInstalle|idZone" required=false}

NOTE : Le paramètre required n'agit que sur la présence du MODULE auquel appartient la zone, et pas sur la zone en elle même. Si vous spécifiez une zone qui n'existe pas dans un module actif, une erreur sera tout de même générée.

id (Javascript)

Chaîne : identifiant de la balise DOM qui est générée pour assurer le fonctionnement des modes Javascript et AJAX.

Si ce paramètre n'est pas précisé alors que le tag est en mode Javascript ou AJAX, un identifiant aléatoire est généré.

{copixzone id="monId" process="ZoneId"}

Générera l'équivalent du code suivant :

<div id="monId"><?php echo CopixZone::process ("monId", array ()); ?></div>

idClick (Javascript)

Chaîne : identifiant d'un élément DOM qui permet d'afficher/cacher le contenu de la zone.

<div id="clicker">Montrer/cacher</div>
{* La zone sera cachée par défaut et cliquer sur le div précédent affichera/cachera la zone. *}
{copixzone process="modulePasInstalle|idZone" idClick="clicker"}

text (Javascript)

Chaîne : texte à ajouter pour afficher/cacher le contenu de la zone.

Ce texte est ajouté dans une balise SPAN juste avant la zone. Si idClick est défini, il est utilisé comme attribut "id" de la balise, sinon il est généré aléatoirement.

{* La zone sera cachée par défaut et précédée d'un texte "Montrer/cacher" sur lequel on pourra cliquer. *}
{copixzone process="modulePasInstalle|idZone" text="Montrer/cacher"}

extra (basique)

Chaîne : attributs à ajouter à la balise de la zone.

{* Ajoute un bord rouge à la zone. *}
{copixzone process="modulePasInstalle|idZone" extra="style='border:solid red 1px'"}

ajax (AJAX)

Booléen : demande la création d'une zone AJAX.

La zone est cachée par défaut et l'exécution de la zone est repoussée jusqu'au moment où elle sera affichée.

auto (AJAX)

Booléen : force le chargement de la zone AJAX dès que possible.

Ne fonctionne que si AJAX est vrai.

onDisplay (Javascript)

Chaîne : code Javascript à exécuter à l'affichage de la zone.

Nécessite d'avoir utilisé idClick, text ou ajax.

{* Affiche un popup "zone affichée !" lorsque l'on affiche la zone *}
{copixzone process="modulePasInstalle|idZone" text="Montrer/cacher" onDisplay="alert('zone affichée !');"}

onComplete (Javascript)

Chaîne : code Javascript à exécuter lorsque le chargement de la zone est terminée ou lorsqu'on affiche la zone.

Nécessite d'avoir utilisé idClick, text ou ajax.

Note: si vous n'utiliser pas ajax, onComplete est strictement équivalent à onDisplay.

{* Affiche un popup "zone terminée !" lorsque l'on cache la zone *}
{copixzone process="modulePasInstalle|idZone" text="Montrer/cacher" onHide="alert('zone terminée !');"}

onHide (Javascript)

Chaîne : code Javascript à exécuter lorsque la zone est cachée.

Nécessite d'avoir utilisé idClick, text ou ajax.

{* Affiche un popup "zone cachée !" lorsque l'on cache la zone *}
{copixzone process="modulePasInstalle|idZone" text="Montrer/cacher" onHide="alert('zone cachée !');"}

assign (basique)

Chaîne: nom d'une variable Smarty à laquelle assigner le code généré par ce tag.

Ce paramètre n'est disponible que dans la version Smarty du tag.

{copixzone process=idZone param1=value param2=value2 assign=variable}

{* plus loin *}
{$variable}

Autres paramètres (basique)

Tous les autres paramètres du tag sont ajoutés aux paramètres passés à la zone.

{copixzone process=idZone param1=value param2=value2}

{* équivaut à l'appel PHP *}
{* CopixZone::process ('idZone', array ('param1'=>'value', 'param2'=>'value2')); *}

Evénements DOM

Lorsque l'un des paramètres text, idClick ou ajax est utilisé, la balise générée gère les événéments suivants:

display

Montre la zone. Déclenche un événement "load" pour forcer le chargement.

hide

Cache la zone.

load

Pour une zone non-AJAX, déclenche l'événement "complete". Pour une zone AJAX :

• lors du premier affichage : charge le contenu en AJAX ; l'événément "complete" est déclenché à la fin du chargement.
• aux affichages suivants, se comporte comme une zone non-AJAX.

complete

Déclenché lorsque la phase de chargement et d'affichage est terminée. Pour une zone non-AJAX, c'est l'équivalent de "display".