Inclusions ("includes") et macros

Des pages dans des pages

Notre discussion sur les outlines et les renderers vous a peut être conduit à vous poser les questions suivantes : "C'est clair, les outlines peuvent faire des choses merveilleuses pour moi si ma page Web consiste entièrement en un seul type d'objet. Par exemple, si toute ma page Web est une liste avec disques. Mais comment faire si je veux inclure une liste avec disques dans une partie de ma page Web ? Le renderer pour créer des tableaux est sympa, mais en général, je ne veux pas d'une page Web qui soit constituée d'un unique tableau. Alors que faire ? Je ne peux pas changer de renderer au beau milieu d'un outline ? Et que faire si je veux utiliser un texte wp pour ma page, en insérant dedans une liste générée à partir d'un outline ?"

Non vous ne pouvez pas changer de renderer au milieu d'un outline. La solution réside dans l'utilisation d'un mécanisme intitulé "Include". Frontier vous permet d'insérer une page Web traitée par son renderer, à l'intérieur d'une autre page Web.

Pour comprendre comment cela fonctionne, revenons à notre pageTrois -- celle qui comporte une liste de choses à faire. Enlevez les directives #title et le #renderOutlineWith. Cette page n'a pas besoin de titre puisque nous allons l'insérer dans une autre page, ni de directive #renderOutlineWith puisque nous désirons utiliser le renderer par défaut.

À présent, allez dans la pageDeux et ajoutez à la fin de celle-ci la ligne suivante (faites attention à la reproduire très exactement) :

    {renderObject(@websites.monPremierSite.pageTrois)}

Maintenant prévisualisez pageDeux. Pas mal, hein ?

La syntaxe ici est {renderObject(@xxx)}, où à "xxx" vous substituez le nom exact et complet de l'entrée de la base de données que vous désirez inclure. N'oubliez aucun des éléments composant l'adresse, spécialement le "@" sinon des choses bizarres risquent d'arriver.

Vous pouvez faire un Include comme celui que vous venez de faire avec n'importe quel type de page Web. Vous pouvez inclure n'importe quoi dans n'importe quoi d'autre avec de bons résultats. En clair, vous pouvez utiliser ce mécanisme non seulement pour pour combiner un type de page Web avec un autre type de page Web (par exemple en intégrant une liste issue d'un outline dans une page de type texte wp, comme décrit au-dessus), mais aussi pour assembler un document à partir de paragraphes standard.

Par exemple, vous pourriez avoir un paragraphe assez volumineux concernant des aspects légaux que vous utilisez en plusieurs endroits à travers toutes vos pages. Si ce paragraphe est inclus à chaque fois avec le mécanisme Include, il sera alors aisé de faire des changements uniquement dans l'entrée de la base de données qui contient ce paragraphe, au lieu d'avoir à lancer une recherche/remplacement à travers toutes les pages Web qui le contiennent.

La syntaxe des macros

La syntaxe de la commande {renderObject(@xxx)}, avec des accolades, indique qu'il s'agit d'une macro. Une macro est simplement une ligne écrite en UserTalk. La macro exécute cette ligne de UserTalk ("la joue", "l'évalue", ou n'importe quelle autre expression qui vous semble la plus appropriée) et la remplace par le résultat obtenu.

Par exemple, si vous mettez {3 + 4} dans votre page Web, cela sera remplacé par 7 parce que "3 + 4" est une expression UserTalk valide, et quand Frontier exécute cette ligne, le résultat est 7.

Si vous mettez {user.prefs.name} dans votre page Web, cela sera remplacé par votre nom car "user.prefs.name" est une expression valide en UserTalk qui indique à Frontier d'aller chercher la valeur de l'objet user.prefs.name dans la base de données.

Dans le cas de {renderObject(@xxx)}, nous utilisons une expression d'UserTalk qui dit à Frontier de chercher un script appelé renderObject et existant dans la base de données, et de prendre @xxx comme paramètre et de lancer ce script.

Quelques faits à propos des macros

Vous pouvez écrire vos propres scripts de macro dès que vous avez appris à programmer en UserTalk. Vous pouvez stocker ces scripts n'importe où dans la base de données. Mais il y a des endroits plus indiqués que d'autres à cause de la manière dont Frontier cherche dans la base de données les entrées auxquelles il est fait référence dans les appels de macro.

Voici la règle. Si, dans le paramètre d'une macro, vous faites référence à un objet de la banque de données, Frontier cherchera d'abord dans la table tools de votre site Web, puis dans user.html.macros, puis dans html.data.standardMacros (où se trouve renderObject), et finalement dans la table désignée depuis html.data.adrPageTable (ce qui permet aux directives #define, #defineScript, et aux directives personnelles de fonctionner -- nous reviendrons là-dessus bientôt). Si rien de cela ne fonctionne, Frontier cherchera dans l'ensemble de la base de données.

Incidemment, pageheader et pagefooter résident aussi dans html.data.standartMacros. Vous vous souvenez d'eux, ils apparaissent dans le modèle default. Et s'ils sont également enclos dans des accolades, c'est parce que ce sont des scripts executés à travers une macro. Ah ! tout devient clair, maintenant !

Au passage, cela signifie que vous ne pouvez pas utiliser d'accolades dans vos pages Web, parce que si vous faites cela, Frontier pensera qu'il s'agit d'une macro et il cherchera à interpréter ce qui est entre les accolades comme une expression en UserTalk. Bien sûr, il y a moyen d'échapper à cela si vous avez besoin d'utiliser des accolades de manière littérale : vous n'avez besoin que de mettre une barre oblique inversée devant l'accolade ouvrante (celle de gauche).

De plus, Frontier ne percevra pas comme macro ce qui est enclos dans des guillemets (les chaînes de caractères littérales) ou à l'intérieur de chevrons (les balises HTML). Le processus qui sous-tend le renderer considère qu'ils sont tabous, et il n'y touche pas. Cependant, vous pouvez désactiver cette protection en mettant une barre oblique inversée devant le premier guillemet ou le premier chevron.

Ce qui est entre accolades peut être n'importe quelle expression écrite en UserTalk. Elle n'a pas besoin d'appeler un script pour s'exécuter, bien que ce soit souvent le cas. Ainsi, même si vous ne connaissez qu'un peu de UserTalk, vous pouvez obligez Frontier à "calculer" certain textes sans avoir besoin d'écrire tout un script pour le faire. À quel moment cette page a t'elle été produite ?

    Dernière mise à jour de cette page : {clock.now()}.

Combien font 2 fois 2 ?

    2 fois 2 font : {2 * 2}.

Est-ce que cela vous donne envie d'apprendre UserTalk ?

   Oui c'est {string.nthField("faux/vrai/dommage/heureux", "/", 2)}, 
    J'eusse aimé savoir {nameOf(root[sizeof(root)-2])}talk.