7.7. KT - Karrigell Templates

KT est un moteur de modèles simple pour les "services Karrigell" (.ks) et les scripts Python. Les buts de KT sont de:
  • fournir un système de modèles simple, sans programmation (la logique, les boucles, etc. sont gérées dans les scripts en Python)
  • supporter le système intégré de traduction de Karrigell
  • supporter la substitution de variables
  • prendre en charge l'inclusion d'autres modèles

7.7.1 Syntaxe du langage de modèles KT

Les modèles KT sont enregistrés avec l'extension .kt. Le langage utilise les balises suivantes, qui sont insérées dans d'autres parties de texte, typiquement HTML.

Balise d'inclusion

   @[template_url]

Inclut le modèle spécifié par template_url. Les URLs sont traitées de la même façon que dans la fonction Import(). Les chemins relatifs sont pris en charge, et sont relatifs au modèle parent. Les inclusions sont traitées récursivement, de façon que des modèles fils puissent inclure d'autres modèles

Balise de substitution

   $identifiant
   $objet.attribut
   $dictionnaire.clef

Substitue un identifiant par sa valeur. Les identifiants peuvent être de simples noms de variables ou peuvent être des objets ou des dictionnaires. Si on utilise des dictionnaires, les clés doivent avoir la forme d'un identifiant Python valide

Balise de traduction

   _[chaîne à traduire]

Traduit la chaîne de caractères en utilisant le système de traduction intégré de Karrigell. Il s'agit de l'équivalent de la fonction _() des script .ks et Python et de la syntaxe <%_ %> de Python Inside HTML

Combinaison de balises

   @[$identifier]
   _[$identifier]

Les inclusions peuvent être controlées par le script appelant en donnant à l'identifiant la valeur de l'url d'un modèle. Les styles $objet.attribut et $dictionnaire.clef peuvent également être utilisés. Ceci apporte un haut niveau de flexibilité dans la façon d'utiliser les modèles. Par exemple, un modèle maître peut contenir l'habillage basique de la page, puis différents modèles fils y sont insérés sous le contrôle du script appelant

Si un $identifiant n'est pas défini, ou a la valeur False, alors aucune inclusion n'est effectuée. Ceci permet au script appelant de "désactiver" une inclusion

En théorie les $identifiants peuvent être placés dans des balises de traduction, mais ce n'est pas recommandé. Il vaut mieux effectuer les traductions dans le script appelant en utilisant la fonction _()

7.7.2 Appel de KT depuis un script

Les valeurs à inclure dans les modèles sont passées par le script comme arguments à mots-clés : 

   print KT(url_modele, var1=var1, var2=var2, data=dict, ligne=ligne, this=THIS, ...)

L'url du modèle pointe vers le fichier de modèle KT, avec les mêmes règles de résolution que la fonction Import()

La syntaxe **dict est aussi supportée : 

   print KT(url_modele, **dict)

Pour faciliter les choses, la fonction intégrée Python locals() peut être affectée à un argument mot-clé, ce qui rend l'espace de noms local disponible dans le modèle: 

   print KT(url_modele, data=locals())

7.7.3 Traitement

Les modèles sont traités de la façon suivante
  1. toutes les inclusions sont traitées récursivement pour construire un modèle consolidé. Les $identifiants dans les balises @[] sont étendus en premier. Si un $identifiant n'est pas défini ou a la valeur False, aucune inclusion n'est effectuée et aucune erreur n'est signalée. Ceci permet au script appelant de "désactiver" une inclusion. Les références circulaires sont détectées et une RecursionError est déclenchée si un modèle essaie de s'inclure lui-même, ou si un modèle fils essaie d'inclure son parent
  2. toutes les autres substitutions sont effectuées sur le modèle consolidé
  3. les traductions sont effectuées

7.7.4 Gestion des traductions

L'outil d'administration pour les traductions reconnaît les fichiers kt. Il extrait automatiquement les chaînes de caractères à traduire à partir des balises _[] de la même façon qu'il les extrait des appels à la fonction _() dans les scripts .py, .hip et .ks et des balises <%_ %> pour .pih

7.7.5 Unicode

KT convertit tout le texte en Unicode en utilisant le codage UTF-8, et retourne une chaîne Unicode

7.7.6 Exemple

Voici un exemple de modèle KT, appelé template/maitre.kt: 

<html>
<head>
<link rel="stylesheet" href="$this.baseurl/css/mon.css">
<title>MonAppli $data.titre</title>
</head>
<body>
@[$data.bodytmpl]
<hr>
<i>_[Powered by Karrigell]</i>
<p />
</body>
</html>

Notez la façon dont THIS est passé à KT et utilisé pour définir l'url de la feuille de style CSS

La balise @[$data.bodytmpl] inclut un autre modèle, dont le nom est contenu dans l'identifiant $data.bodytmpl. Dans cet exemple, nous donnerons à $data.bodytmpl la value index.kt

index.kt contient ce code: 

<h1>Bienvenue à la page d'accueil de $data.qui !<h1>

Ce morceau de code montre comme le modèle serait appelé depuis un script ks appelé /monappli.ks" 

def index():
    SET_UNICODE_OUT("utf-8")
    titre = ' -  accueil'
    qui = 'Tartempion'
    bodytmpl = 'index.kt'
    print KT('modele/maitre.kt', data=locals(), this=THIS)

Si la langue du navigateur du lecteur est English, l'appel de /monappli.kt/index produit ce code html: 

<html>
<head>
<link rel="stylesheet" href="/css/mon.css">
<title>MonAppli - accueil</title>
</head>
<body>
<h1>Bienvenue sur la page d'accueil de Tartempion !</h1>
<hr>
<i>Powered by Karrigell</i>
<p />
</body>
</html>

Si la langue du navigateur est Français, et que la traduction de "Powered by Karrigell" a été saisie dans l'outil d'administration, le résultat serait : 

<html>
<head>
<link rel="stylesheet" href="/css/mon.css">
<title>MonAppli - accueil</title>
</head>
<body>
<h1>Bienvenue sur la page d'accueil de Tartempion !</h1>
<hr>
<i>Motorisé par Karrigell</i>
<p />
</body>
</html>