C’est quoi un template ?¶

Un template est la réponse que retourne NTeABot à la suite d’une requête utilisateur. Pour chaque intent (action) d’un field, il faut créer un fichier de template correspondant à la langue de la requête et de même nom pour le matcher.

Dans notre cas, notre field cooltravelfield traite de deux langues, donc notre dossier templates aura deux sous-dossiers (en, fr) dans lequel il faudra construire des fichiers YAML de template pour traiter chaque langue.

templates
  fr
    cooltravel_template.yaml
  en
    cooltravel_template.yaml

Un template est aussi un fichier YAML avec la structure suivante:

# cooltravelfield/templates/fr/cooltravel_template.yaml
---
action: BookTrain
params: 
  startedPlace: 
    required: true
    template: "Quel est votre point de départ ?"
    form: text
    from: input
  targetPlace: 
    required: true
    template: "Quelle est votre destination d'arrivée ?"
    form: text
    from: input
  travelAgencyName: 
    required: true
    template: "Dans quelle agence de voyage souhaites-tu faire ce voyage ?"
    form: text
    from: input
  cooltravelHtml: 
    required: true
    template: ""
    form: html
    from: action    
language: en
responses:
  found:
  - ["D'accord, je regarde ça pour toi!", "{cooltravelHtml}"]
  - ["Bonne idée, je jette un coup d'oeil!", "{cooltravelHtml}"]
  - ["Ok, je cherche des trains disponibles...", "Super, j'ai trouvé ces trains", "{cooltravelHtml}"]
  nofound:
  - ["OK je regarde cela pour toi"]
  - ["Désolé, je n'ai pas trouvé de réservation disponible pour ta recherche."]

---
action: BookBus
params: 
  startedPlace: 
    required: true
    template: "Quel est votre ville  de départ ?"
    form: text
    from: input
  targetPlace: 
    required: true
    template: "Quelle est votre destination d'arrivée ?"
    form: text
    from: input
  travelAgencyName: 
    required: true
    template: "Dans quelle agence de voyage souhaites-tu faire ce voyage ?"
    form: text
    from: input
  cooltravelHtml: 
    required: true
    template: ""
    form: html
    from: action    
language: en
responses:
  found:
  - ["D'accord, je regarde les bus de {startedPlace} à {targetPlace}", "{cooltravelHtml}"]
  - ["Bonne idée, je jette un coup d'oeil!", "{cooltravelHtml}"]
  - ["Ok, je regarde si je trouve des bus disponibles...", "Super, j'ai trouvé ces   bus!", "{cooltravelHtml}"]
  nofound:
  - ["OK je regarde cela pour toi..."]
  - ["Désolé, je n'ai pas trouvé de réservation disponible pour ta recherche."]

---

Les constituants d’un template¶

• action donne le nom de l’action défini dans l’intent: ici BookBus et BookTrain
• params défini les paramètres utilisateurs capturés de l’intent et éventuellement les paramètres injectés par le traitement de l’action.
• language défini la langue utilisée pour rédiger les reponses du template. Cette langue correspond au nom du dossier parent.
• responses permet de lister les réponses possibles de NTeABot. Une réponse de NTeABot contient différents types de format selon qu’une réponse est retournée par l’action found ou pas nofound. Ces blocs peuvent contenir plusieurs sous-réponses qui se séquencent intéractivement dans un tableau: ["Bonne idée, je jette un coup d'oeil!", "{cooltravelHtml}"]. Il existe deux types de réponses:
  • Les réponses de type text sont des chaines de caractères simples: "Bonne idée, je jette un coup d'oeil!". Ces réponses de type text peuvent contenir des paramètres de forme form: text venant de l’action from: action ou de l’input from: input.
  • Les réponses de type html sont les réponses injectées par le fichier Python de l’action: "{cooltravelHtml}" (cooltravelHtml est le nom de la variable qui sera retourné par le fichier request Python ).

---

Les paramètres d’un template¶

Les paramètres du template ont les caractéristiques suivantes:

• Ils viennent soit des utilisateurs from: input (extraits de la requête utilisateur), soit des actions from: action (injecté par le fichier Python). Pour le cas de from: action, le nom du paramètre doit être identique au nom de la variable injectée par le fichier Python.
• Ils sont de type textuels form: text (chaine de caractères) et de type HTML form: html.
• Ils sont facultatifs required: false ou obligatoire required: true.
• S’ils sont obligatoires required: true, ils doivent admettre un template supplémentaire template: "Quel est votre ville de départ ?". NTeABot oblige alors l’utilisateur à renseigner ce paramètre avant d’exécution l’action proprement dite. Le message envoyé à l’utilisateur sera la valeur template du paramètre.

Les éléments suivants illustrent les cas possibles de définition d’un paramètre:

startedPlace: 
    required: true
    template: "Quel est votre ville  de départ ?"
    form: text
    from: input

cooltravelHtml: 
    required: true
    template: ""
    form: html
    from: action

cooltravelTime: 
    required: true
    template: ""
    form: text
    from: action

cooltravelDate: 
    required: false
    template: ""
    form: text
    from: input

Construire un template HTML¶

Nos templates sont construits sous la base du moteur de template Python Jinja. Il serait bien pour vous d’y jeter un coup d’oeil avant de continuer cette section.

Si vous avez déclaré "{cooltravelHtml}" dans une des réponses du template ["Bonne idée, je jette un coup d'oeil!", "{cooltravelHtml}"], ça veut dire que la requête de votre fichier Python où est traitée votre action BookBus doit renvoyer une variable cooltravelHtml contenant la structure HTML voulue.

Vous devez donc créer dans votre dossier templates un fichier HTML portant le même nom de cette variable cooltravelHtml.html. Le contenu de cooltravelHtml.html sera par exemple:

{# Template for card resume for NTeABot : #}
<div class="blb-slideshow"  style="width:245px; margin:auto">
    <ul class="xxx" style="width:{{cooltravelHtml|length * 245}}px">
    {% for item in cooltravelHtml -%}
        <li style="width:245px">
            <div>
                <div class="blb-dico-titre">
                    <h2><i class="em em-closed_book"></i> {{item['travel_name']}}</h2>
                    <span class="blb-dico-small">{{ item['travel_description']}}</span>
                </div>
                <div class="blb-dico-text">{{item['travel_hour']}}</div>
                <div class="blb-dico-auteur">{{item['travel_price']}}</div>
            <div>
        </li>
    {%- endfor %}
    </ul>
</div>
<a class="blb-nav-slideshow-left"><img width="25" src="https://apis.ntealan.net/nteabot/static/img/left.png"></a>
<a class="blb-nav-slideshow-right"><img width="25" src="https://apis.ntealan.net/nteabot/static/img/right.png"></a>

Ce fichier utilise le template de navigation par défaut (slide show) de NTeABot:

<div class="blb-slideshow"  style="width:245px; margin:auto">
    {# ici le contenu html de l'action de votre field #}
</div>
<a class="blb-nav-slideshow-left"><img width="25" src="https://apis.ntealan.net/nteabot/static/img/left.png"></a>
<a class="blb-nav-slideshow-right"><img width="25" src="https://apis.ntealan.net/nteabot/static/img/right.png"></a>

Vous pouvez si vous le souhaitez, créer vos propres templates HTML en veuillant juste à placer les styles css (sans aucunes librairies externes comme boostrap) directement dans les balises HTML. Les liens ou images insérés dans les balises doivent être absolus.

<div class="blb-slideshow"  style="width:245px; margin:auto">
    <div style="padding:5px; font-size: 12px">
        <span style="color: gray; float:left"> </span>
        <p>
            <div style="background-image: url(https://mysite.org/static/imag.png)">
            ...
            <div>
        </p>
    </div>
</div>

---

Les templates par défaut de NTeABot¶

Si vous le souhaitez, vous pouvez utiliser les templates par défaut de NTeABot. Nous avons actuellement 8 :

Templates	Paramètres	Exemples
ntb_array_dico	- short_name - description - publication - author
ntb_array_html	- article
ntb_array_image	- logo - url - title - content
ntb_list_text	- text - value
ntb_array_video
ntb_login
ntb_resume
ntb_video

Pour les utiliser, il vous suffira de le déclarer dans vos templates et de construires le fichier request de manière à macher les paramètres du templates aux sorties de la requête. cf. la section request.