Références de page

Les valeurs de content et de props d'un composant résolvent quatre familles de références au moment du rendu :

Une page rendue depuis du markdown expose en plus $frontmatter.*. Une cinquième référence, $session.<champ>, résout dans le navigateur plutôt qu'au rendu.

Les paramètres de requête comme entrées de page

Le bloc query d'une page ouvre des paramètres de requête d'URL comme entrées de page, référençables par $query.<nom> partout où la substitution $vars s'applique. Chacun déclare une liste blanche fermée et une valeur par défaut.

name: my-app
pages:
  - name: dashboard
    path: /dashboard
    query:
      period:
        default: 7d
        enum: [24h, 7d, 30d]
    components:
      - { type: text, content: 'Showing the last $query.period' }

/dashboard affiche 7d ; /dashboard?period=30d affiche 30d.

Une valeur inconnue se rabat sur la valeur par défaut — la page ne répond jamais 400. Une chaîne de requête est fournie par qui détient le lien, et un signet périmé n'est pas une condition d'erreur : une valeur non reconnue s'affiche donc exactement comme si le paramètre était absent. Borner l'ensemble accepté borne aussi l'espace des réponses à un rendu par valeur autorisée, et c'est ce qui garde la page cachable par valeur.

default doit faire partie de son propre enum, et chaque nom de propriété doit être en kebab-case minuscule ; les deux sont vérifiés au démarrage.

Contraindre un segment de route

Le bloc params d'une page contraint un :segment à un ensemble fermé fourni par un point de lecture. Un segment hors de l'ensemble répond 404 plutôt que d'afficher une page vide — la même distinction que l'explorateur d'enregistrements fait entre « n'existe pas » et « est vide ».

Une fenêtre glissante relative

Un lecteur d'analytique veut des instants absolus, et $query.period substitue l'identifiant de préréglage 7d, qui n'est pas un horodatage. Le bloc window d'une page referme cet écart : il déclare une liste fermée d'intervalles relatifs sélectionnés depuis l'URL, et résout celui qui est choisi en instants concrets au rendu.

name: my-app
pages:
  - name: analytics
    path: /analytics
    window:
      param: period
      default: 7d
      presets:
        - { id: 24h, granularity: hour, label: last 24 hours }
        - { id: 7d }
        - { id: 30d }
    components:
      - type: text
        content: Measured over the $window.label.

Cinq références résolvent, une fois par rendu :

Un identifiant de préréglage est un intervalle : un entier positif suivi de h, d ou w, comme 24h, 7d, 2w. Les mois et les années sont absents parce qu'aucun des deux n'a de longueur fixe — « un mois avant le 31 mars » n'a pas de réponse unique défendable. La granularité et le libellé se déduisent de l'intervalle et peuvent chacun être surchargés par préréglage.

Elles résolvent une seule fois par rendu, contre un instant unique. Des panneaux qui liraient chacun l'horloge pour leur propre compte verraient leurs fenêtres diverger de la durée du rendu, et une page qui rapporte deux périodes à la fois vous invite à les comparer.

Une valeur non reconnue se rabat sur la valeur par défaut et répond 200, exactement comme query. Garder la liste fermée est aussi ce qui garde la page cachable : l'ensemble atteignable est d'un rendu par préréglage, et un rendu en cache porte à la fois le préréglage et un instant de fin arrondi à la minute, de sorte qu'un chiffre n'est jamais servi sous un horodatage auquel il n'a pas été mesuré.

default doit nommer l'un des préréglages déclarés, les identifiants doivent être uniques, et param ne peut pas masquer un nom de propriété query ; les trois sont vérifiés au démarrage.

Portée à l'utilisateur courant

$currentUser résout par requête pendant le rendu serveur, et n'est jamais mis en cache d'un utilisateur à l'autre.

name: my-app
tables:
  - name: projects
    fields:
      - { name: name, type: single-line-text }
pages:
  - name: Projects
    path: /projects
    components:
      - type: table
        dataSource:
          table: projects
          filter:
            - { field: id, operator: in, value: '$currentUser.assignments.projects' }

Un filtre $currentUser rend la page authentifiée. En résoudre un sans session répond 401 Unauthorized — c'est distinct de la garde access de la page, qui redirige ou répond 404. Une section de barre latérale qui rencontre la même condition est retirée silencieusement plutôt que de faire échouer la page.

Texte lié à la session

$session.<champ> résout le champ de session de l'appelant connecté lui-même — email, name, role ou id — à l'intérieur du content d'un composant. C'est la contrepartie côté navigateur de $currentUser, et le lieu de résolution fait toute la différence : $currentUser est substitué côté serveur à chaque requête, $session une fois la page servie. C'est ce qui permet à une salutation liée à la session de vivre sur une page en cache statique sans que le cache porte jamais l'identité d'un lecteur jusqu'au suivant.

Un jeton qui ne résout rien — un appelant anonyme, ou un champ que le compte ne porte pas — devient la chaîne vide.

Segments optionnels

Un jeton nu ne peut pas porter sa propre ponctuation. Une salutation écrite Welcome, $session.name est bien formée et fautive deux fois : le serveur n'a pas de session, donc les octets servis se lisent Welcome, avec une virgule en suspens pour tout lecteur sans JavaScript, et un appelant connecté dont le compte ne porte pas de nom d'affichage lit la même chose. La virgule appartient au nom, et la forme jeton n'a aucun moyen de le dire.

Enveloppez le littéral et son jeton entre crochets pour en faire une seule unité grammaticale :

name: my-app
pages:
  - name: Dashboard
    path: /dashboard
    components:
      - type: text
        element: h1
        content: 'Welcome[, $session.name]'

Un appelant connecté avec un nom d'affichage lit Welcome, Alice Johnson ; un appelant anonyme, ou connecté sans nom d'affichage, lit Welcome.

Un segment est tout ou rien : chaque jeton qu'il contient doit résoudre vers une valeur non vide, sinon le segment entier disparaît — crochets, littéraux et tout le reste. Une unité à moitié résolue est précisément la ponctuation en suspens que le segment existe pour éviter. Les segments ne s'imbriquent pas, et l'un d'eux ne peut pas en contenir un autre.

Des crochets ne forment un segment que si un jeton de session vit à l'intérieur. Une phrase comme Status [draft] ne porte aucun jeton de session : elle s'affiche verbatim, crochets compris — les crochets sont de la prose ordinaire, et un texte qui n'a jamais demandé cette grammaire n'est pas touché par elle. Un jeton hors de tout crochet est lui aussi inchangé : il résout, ou il devient la chaîne vide.

Le serveur retire chaque segment optionnel et l'hydratation le rajoute. Ce sens est délibéré : un titre qui se lit Welcome puis s'allonge est lisible à chaque instant, là où un titre qui arrive vide et se remplit est un décalage de mise en page sur la première chose qu'un lecteur regarde.

Pages connexes

• Liaison de données — la dataSource qui produit $record.
• Présentation des pages — vars et le reste du tableau des propriétés de page.
• Langues — les clés $t: et la façon dont une page résout sa langue.
• Mises en page, barres latérales et accès — la garde access et sa réponse différente.