Reference Facet

Utilisez cette page lorsque le guide principal de syntaxe ne suffit plus et que vous avez besoin d'une reference plus profonde sur le comportement de Facet, les objets de contexte, les contrats de helper et les regles de rendu.

Cette page est volontairement dense. C'est le compagnon de reference technique de :

Syntaxe des templates Facet

Ce que cette page couvre

Utilisez cette reference lorsque vous avez besoin de details sur :

les objets de contexte et leurs proprietes courantes
les patterns d'acces aux pages, medias et collections
les contrats de helper pour les images et les maps
les filtres par categorie
le comportement du systeme de Variables
les slots de niveau Layout
les attributs de donnees geres
les references media
les regles de rendu et de securite

Objets de contexte

Les templates Facet ont acces a un ensemble controle d'objets de niveau racine. Les proprietes utiles dependent de la surface de rendu courante, mais le meme modele mental s'applique partout.

`page`

page est l'objet page courant dans le contexte de rendu courant.

Proprietes principales de page

Les proprietes scalaires courantes incluent :

page.id
page.name
page.title
page.url
page.httpUrl
page.path
page.template
page.created
page.modified
page.createdStr
page.modifiedStr
page.status
page.sort
page.numChildren

Usage typique :

<h1>{{ page.title }}</h1>
<p>Updated {{ page.modified | date("F j, Y") }}</p>

Proprietes de statut

Les proprietes booleennes courantes incluent :

page.isPublished
page.isHidden
page.isUnpublished
page.isTrash
page.isNew
page.hasChildren
page.isEditable

Exemple :

{{#if page.hasChildren}}
  <p>This page has child pages.</p>
{{/if}}

page.isEditable est particulièrement utile pour les éléments d’interface qui ne doivent apparaître que pour les éditeurs de la page actuelle :

{{#if page.isEditable}}
  <a href="{{ page.url }}?edit=1">Edit this page</a>
{{/if}}

Proprietes relationnelles

Facet expose couramment des acces relationnels comme :

page.parent
page.parents
page.rootParent
page.children
page.siblings
page.next
page.prev
page.find

Exemples :

{{ page.parent.title }}
{{ page.rootParent.title }}

{{#each page.children as="child"}}
  <a href="{{ child.url }}">{{ child.title }}</a>
{{/each}}

Proprietes media

Les proprietes media courantes incluent :

page.images
page.image
page.files

Exemples :

{{#each page.images as="img"}}
  <img src="{{ img.width(800).webp.url }}" alt="{{ img.description }}">
{{/each}}

{{#each page.files as="file"}}
  <a href="{{ file.url }}">{{ file.filename }}</a>
{{/each}}

Proprietes d'objet image

Les proprietes typiques d'un objet image incluent :

img.url
img.httpUrl
img.filename
img.description
img.width
img.height
img.ext
img.filesize
img.webp.url
img.raw.url

Proprietes d'objet file

Les proprietes typiques d'un objet file incluent :

file.url
file.httpUrl
file.filename
file.description
file.ext
file.filesize

Transformations d'image

Les objets image provenant d'une page ou d'une requete prennent en charge des transformations chainees :

{{ page.image.width(800) }}
{{ page.image.size(600, 400) }}
{{ page.image.size(600, 400).webp.url }}
{{ page.image.raw.url }}

Dans les boucles :

{{#each page.images as="img"}}
  <img src="{{ img.size(400, 300).webp.url }}" alt="{{ img.description }}">
{{/each}}

Methodes de collection

Les helpers de collection courants incluent :

first
last
count
eq(n)
slice(start, length)

Exemples :

{{ page.images.first.url }}
{{ page.images.count }}
{{ page.images.eq(2).url }}

Acces dynamique a un champ

Les champs personnalises d'une page peuvent etre accedes par leur nom :

{{ page.summary }}
{{ page.body }}
{{ page.headline }}
{{ page.field name="my_custom_field" }}

Utilisez cela lorsque la surface de rendu courante depend vraiment de donnees de niveau page. Ne l'utilisez pas pour masquer un contrat de champ de Component faible.

URL localisee

Facet peut exposer des helpers d'URL localisee pour un rendu multilingue conscient de la page :

{{ page.localUrl lang="fr" }}
{{ page.localUrl lang="default" }}

`user`

user represente le contexte utilisateur courant.

Les proprietes courantes incluent :

user.id
user.name
user.title
user.email
user.displayName
user.isLoggedin
user.isGuest
user.isSuperuser
user.language

Usage typique :

{{#if user.isLoggedin}}
  <span>Hello, {{ user.displayName }}!</span>
{{else}}
  <a href="/login/">Log In</a>
{{/if}}

`pages`

pages expose des helpers orientes requete pour des sorties scalaires ou agregees.

Les patterns courants incluent :

pages.count selector="..."
pages.first selector="..."
pages.last selector="..."
pages.titles selector="..." sep=", "
pages.json selector="..."

Exemples :

<p>Total posts: {{ pages.count selector="template=blog-post" }}</p>
<p>Categories: {{ pages.titles selector="template=category" sep=", " }}</p>

Utilisez {{#pages}} lorsque vous avez besoin d'une boucle bloc. Utilisez les helpers inline pages.* pour des sorties scalaires.

`languages` / `lang`

languages et lang exposent le systeme de langues.

Les proprietes courantes incluent :

languages.count
languages.current
languages.default
languages.isMultiLanguage
languages.all
languages.{name}

Exemple :

{{#if languages.isMultiLanguage}}
  Current language: {{ languages.current.title }}
{{/if}}

Dans {{#languages}}, chaque element langue expose couramment :

lang.id
lang.name
lang.title
lang.isDefault
lang.isCurrent
lang.url
lang.httpUrl
lang.locale

`site`

site fournit des valeurs de niveau site.

Les proprietes courantes incluent :

site.name
site.url
site.httpUrl
site.httpHost
site.locale
site.year
site.assets
site.templates
site.adminUrl
site.adminProfileUrl
site.adminLogoutUrl

Un acces de type settings peut egalement etre disponible :

{{ site.setting key="company_name" }}
{{ site.setting key="phone" }}

<a href="{{ site.adminUrl }}">Dashboard</a>
<a href="{{ site.adminProfileUrl }}">Profile</a>
<a href="{{ site.adminLogoutUrl }}">Log out</a>

Utilisez des settings de niveau site pour des valeurs globales stables, pas pour un contenu qui devrait appartenir a une Variable ou a un objet gere de niveau page.

`now`

now fournit les valeurs de temps courant.

Les proprietes courantes incluent :

now.timestamp
now.date
now.datetime
now.year
now.month
now.day

Exemple :

<footer>&copy; {{ now.year }} {{ site.name }}</footer>

`attr`

attr expose les valeurs passees dans une Variable :

{{! Usage: [[my-widget title="Hello" color="blue"]] }}
<div style="color: {{ attr.color | default("black") }}">
  <h3>{{ attr.title | default("Default Title") }}</h3>
</div>

attr doit rester petit et explicite. Si un fragment a besoin d'un grand modele de donnees editable, il veut probablement un Component plutot qu'une Variable.

`loop`

loop est disponible dans les blocs de boucle comme :

{{#each}}
{{#pages}}
{{#languages}}

Proprietes courantes :

loop.index
loop.index1
loop.first
loop.last
loop.length
loop.even
loop.odd

Exemple :

{{#each page.children as="child"}}
  <div class="{{#if loop.odd}}row-alt{{/if}}">
    {{ loop.index1 }}. {{ child.title }}
  </div>
{{/each}}

`this`

Dans {{#each}}, this est l'element courant de la boucle :

{{#each page.children}}
  <a href="{{ this.url }}">{{ this.title }}</a>
{{/each}}

this et un alias nomme pointent normalement vers le meme element courant.

`@index`

@index est un raccourci pour loop.index.

Exemple :

{{#each page.children as="child"}}
  {{#if @index == 0}}
    <h2>{{ child.title }}</h2>
  {{else}}
    <p>{{ child.title }}</p>
  {{/if}}
{{/each}}

Champs de Component au niveau racine

Dans les templates de Component, les champs de l'instance courante de Component sont souvent injectes comme variables de niveau racine :

<h1>{{ title }}</h1>

{{#if showGallery}}
  <div class="gallery">
    {{#each images as="img"}}
      <img src="{{ img.url }}">
    {{/each}}
  </div>
{{/if}}

C'est l'une des raisons pour lesquelles les templates de Component semblent plus simples que des templates generiques de niveau page.

Les noms reserves ne doivent pas etre reutilises a la legere comme noms de champs personnalises s'ils entrent en collision avec des objets de contexte principaux comme :

page
pages
user
languages
lang
site
now
attr
loop
this
@index

Reference des helpers de champ de Component

Facet fonctionne avec plusieurs contrats de helpers specifiques aux Components qui ne sont pas identiques a la sortie generale {{ expr }}.

Helpers de champ image unique

Les champs image uniques prennent couramment en charge :

{field}
{field.raw}
{field.webp}
{field.name}
{field.description}
{field.width(N)}
{field.width(N).webp}
{field.height(N)}
{field.height(N).webp}
{field.size(W,H)}
{field.size(W,H).webp}

Exemple :

<img src="{hero.width(1200).webp}" alt="{hero.description}">
<a href="{photo.raw}" download>Download original</a>

Helpers de champ images multiples

Dans {{#each gallery}}, les elements images prennent couramment en charge :

{{this}}
{{this.raw}}
{{this.webp}}
{{this.name}}
{{this.description}}
{{this.width(N)}}
{{this.width(N).webp}}
{{this.height(N)}}
{{this.height(N).webp}}
{{this.size(W,H)}}
{{this.size(W,H).webp}}

Exemple :

{{#each gallery}}
  <figure>
    <img src="{{this.width(600).webp}}" alt="{{this.description}}">
    <figcaption>{{this.name}}</figcaption>
  </figure>
{{/each}}

Helpers de champ map

Les champs map prennent couramment en charge :

{field}
{field.width(N)}
{field.height(N)}
{field.size(W,H)}

Exemples :

{officeLocation}
{officeLocation.width(600)}
{officeLocation.size(800,500)}

Utilisez map uniquement pour des donnees de localisation structurees, pas pour une simple adresse en texte.

Contrats d'embed geres

Les embeds de workflow geres utilisent typiquement :

data-form-embed
data-review-embed

Exemples :

<div data-form-embed="enterprise-demo-request"></div>
<div data-review-embed="customer-success-reviews"></div>

<div data-form-embed="{contactForm}"></div>
<div data-review-embed="{serviceReview}"></div>

Utilisez des ids fixes pour les workflows possedes par le template et des valeurs pilotees par champ pour les workflows selectionnables par l'auteur.

Reference des filtres

Les filtres transforment les valeurs avant la sortie. La regle la plus importante est simple :

utilisez les filtres pour le formatage
n'utilisez pas les filtres pour masquer un modele objet faible

Filtres de chaine

Les filtres de chaine courants incluent :

escape / e
raw
upper
lower
capitalize
trim
truncate
nl2br
striptags
replace
split
slice
pad
wrap
slug

Exemples :

{{ page.title | upper }}
{{ page.body | striptags | truncate(200, "...") }}
{{ text | nl2br }}
{{ title | slug }}

Filtre de valeur par defaut

default fournit une valeur de repli lorsque l'entree est absente ou de type null selon le contrat pris en charge :

{{ page.subtitle | default("Untitled") }}

Si le comportement exact sur chaine vide importe, preferez une ternaire explicite.

Filtres numeriques

Les filtres numeriques courants incluent :

number
currency
abs
round
ceil
floor

Exemples :

{{ 1234567 | number(0, ".", ",") }}
{{ price | currency("$", 2) }}
{{ ratio | round(2) }}

Filtres de date

Les filtres de date courants incluent :

date
datetime
relative

Exemples :

{{ page.created | date("F j, Y") }}
{{ page.modified | datetime("Y-m-d H:i") }}
{{ page.modified | relative }}

Filtres d'URL

Les filtres orientes URL courants incluent :

url_encode
url

Exemples :

{{ page.title | url_encode }}
{{ website | url }}

Filtre JSON

Utilisez json pour une sortie JSON sure :

{{ data | json }}

Cela est utile lorsque le template a besoin de donnees structurees dans du HTML ou dans une sortie orientee script.

Filtres de tableau et de collection

Les filtres de collection courants incluent :

join
first
last
count
length
reverse
sort
pluck
unique
batch
keys
values
merge

Exemples :

{{ tags | pluck("title") | join(", ") }}
{{ page.children | count }}
{{ items | batch(4) }}

Filtre image

Filtre image courant :

size

Exemple :

{{ page.image | size(600, 400) }}

Filtre de hash

Filtre de hash courant :

md5

Exemple :

{{ user.email | md5 }}

Systeme de Variables

Les Variables sont des fragments de template reutilisables qui peuvent etre inseres partout ou le rendu FaceFlow les prend en charge.

Inclusion de Variables

Inclusion simple :

[[my-variable]]

Avec attributs :

[[my-widget title="Hello World" color="blue" count="5"]]

Structure d'une Variable

Une Variable contient typiquement :

un template HTML
du CSS optionnel
du JS optionnel
des attributs optionnels
un mode de cache

Modes de cache

Les modes courants incluent :

static
dynamic
auto

Utilisez :

static lorsque la sortie est largement compatible cache
dynamic lorsque la sortie depend d'un etat runtime sensible a l'utilisateur ou a la requete
auto lorsque le moteur doit choisir selon le comportement de la Variable

Variables imbriquees

Les Variables peuvent inclure d'autres Variables :

<footer>
  [[copyright-notice year="2026"]]
  [[social-links]]
</footer>

Utilisez l'imbrication pour ameliorer la reutilisation et la clarte, pas pour creer des chaines de dependances profondes et cachees.

Syntaxe de niveau Layout

Les templates orientes Layout s'appuient souvent sur quelques placeholders structurels :

{content}
{header}
{footer}
{siteComponents}

Exemple :

<body>
  {header}
  {siteComponents}
  <main>
    {content}
  </main>
  {footer}
</body>

Ces placeholders appartiennent a la composition du shell et du layout, pas au rendu ordinaire d'une section.

Attributs de donnees

Les attributs de donnees courants orientes runtime incluent :

data-form-embed
data-review-embed
data-fb-map
data-fb-map-field
data-component-*
data-form-ajax
data-variable
data-loading

Utilisez-les lorsque le contrat runtime les documente explicitement. N'inventez pas des attributs paralleles a la legere.

References media

Certains contextes de rendu FaceFlow peuvent exposer des patterns de reference media geres comme :

@image:filename
@file:filename

Ce sont des representations cote implementation d'assets geres. Dans les templates auteurs, preferez les formes de sortie helper ou objet documentees plutot que de vous appuyer sur des references de stockage brutes.

Pipeline de rendu

Un ordre de rendu Facet pratique ressemble generalement a ceci :

charger l'objet FaceFlow proprietaire
resoudre le contexte de rendu courant
injecter les champs de niveau racine et les objets de contexte
evaluer les contrats de helper de champ
evaluer les expressions Facet et les block helpers
resoudre les inserts de Variable
resoudre les marqueurs runtime geres comme Forms, Reviews ou maps
retourner la sortie finale

La lecon de conception importante est que le raccourci de champ de Component, les expressions Facet, les inserts de Variable et les marqueurs runtime geres sont lies mais ne sont pas des etapes identiques.

Modele de securite

Facet est concu comme une couche de template gouvernee plutot que comme un environnement d'execution de code brut.

Regles principales :

pas d'execution arbitraire de code cote serveur
objets racine controles
filtres et types de blocs whitelistes
comportement de requete contraint
sortie brute a utiliser intentionnellement

Traitez cela comme un langage de template sandboxe, pas comme un moteur de script de secours.

Regles pratiques de conception

preferez des frontieres d'objet claires a une logique de template trop clever
gardez une logique de template peu profonde
utilisez des Variables pour les fragments et des Components pour les contrats de section
utilisez des Lists lorsque la requete et la pagination font partie du contrat
verifiez toute syntaxe helper de champ par rapport a la reference de champ avant de l'utiliser
examinez le contenu sensible au cache avant d'introduire du rendu differe

Patterns cookbook

<nav>
  <ul>
    {{#pages selector="parent=1, sort=sort" as="item"}}
      <li><a href="{{ item.url }}">{{ item.title }}</a></li>
    {{/pages}}
  </ul>
</nav>

Liste d'articles de blog

{{#pages selector="template=blog-post, sort=-created, limit=6" as="post"}}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
    <p>{{ post.body | striptags | truncate(250) }}</p>
  </article>
{{else}}
  <p>No blog posts yet.</p>
{{/pages}}

Switcher multilingue

{{#if languages.isMultiLanguage}}
  {{#languages as="lang"}}
    <a href="{{ lang.url }}">{{ lang.title }}</a>
  {{/languages}}
{{/if}}

Breadcrumbs

{{#each page.parents as="p"}}
  <a href="{{ p.url }}">{{ p.title }}</a> /
{{/each}}
<span>{{ page.title }}</span>

Message de bienvenue cache-safe

{{#deferred skeleton-width="10rem" skeleton-height="2rem"}}
  {{#if user.isLoggedin}}
    <span>{{ user.displayName }}</span>
  {{else}}
    <a href="/login/">Sign In</a>
  {{/if}}
{{/deferred}}

FAQ

Quand utiliser `{{#pages}}` plutot que `{{#each}}` ?

utilisez {{#each}} lorsque les donnees existent deja dans le contexte courant
utilisez {{#pages}} lorsque le template doit interroger les donnees

Quelle est la difference entre `{{ }}` et `{{{ }}}` ?

{{ ... }} est une sortie echappee
{{{ ... }}} est une sortie brute

Utilisez la sortie echappee par defaut.

Puis-je imbriquer les boucles ?

Oui, mais seulement lorsque le modele objet reste lisible. Si les boucles imbriquees compensent un contrat de contenu faible, arretez-vous et revoyez le design.

Pourquoi un champ renvoie-t-il `null` ou une sortie vide ?

Causes courantes :

mauvais contexte
mauvais nom de champ
mauvaise famille de syntaxe pour l'objet courant
attente d'un helper sur un champ qui ne le prend pas en charge

Comment deboguer des problemes de template ?

Commencez dans cet ordre :

confirmer le contrat de l'objet proprietaire
confirmer la bonne famille de syntaxe
confirmer les objets de contexte disponibles
reduire le template au plus petit fragment reproductible
puis reconstruire a partir de la

Reference Facet

Reference Facet

Ce que cette page couvre

Objets de contexte

page

Proprietes principales de page

Proprietes de statut

Proprietes relationnelles

Proprietes media

Proprietes d'objet image

Proprietes d'objet file

Transformations d'image

Methodes de collection

Acces dynamique a un champ

URL localisee

user

pages

languages / lang

site

now

attr

loop

this

@index

Champs de Component au niveau racine

Reference des helpers de champ de Component

Helpers de champ image unique

Helpers de champ images multiples

Helpers de champ map

Contrats d'embed geres

Reference des filtres

Filtres de chaine

Filtre de valeur par defaut

Filtres numeriques

Filtres de date

Filtres d'URL

Filtre JSON

Filtres de tableau et de collection

Filtre image

Filtre de hash

Systeme de Variables

Inclusion de Variables

Structure d'une Variable

Modes de cache

Variables imbriquees

Syntaxe de niveau Layout

Attributs de donnees

References media

Pipeline de rendu

Modele de securite

Regles pratiques de conception

Patterns cookbook

Menu de navigation

Liste d'articles de blog

Switcher multilingue

Breadcrumbs

Message de bienvenue cache-safe

FAQ

Quand utiliser {{#pages}} plutot que {{#each}} ?

Quelle est la difference entre {{ }} et {{{ }}} ?

Puis-je imbriquer les boucles ?

Pourquoi un champ renvoie-t-il null ou une sortie vide ?

Comment deboguer des problemes de template ?

Related

`page`

`user`

`pages`

`languages` / `lang`

`site`

`now`

`attr`

`loop`

`this`

`@index`

Quand utiliser `{{#pages}}` plutot que `{{#each}}` ?

Quelle est la difference entre `{{ }}` et `{{{ }}}` ?

Pourquoi un champ renvoie-t-il `null` ou une sortie vide ?