Clients

Structure d’un client et options de pankosmia_metadata.json

Table des matières

Qu’est-ce qu’un client

Un client est une application web (React, construite avec Vite) servie par le serveur Pankosmia à l’adresse /clients/<nom>. Le tableau de bord, les paramètres et chaque gestionnaire de contenu (core-contenthandler_*) sont des clients. Un produit inclut un client en le listant dans CLIENTn de app_config.env (donc dans libClients de buildSpec.json). Le build copie alors son dossier build/, package.json, pankosmia_metadata.json et storage_id.json (s’il existe) dans lib/clients/<nom du dépôt>.

Structure d’un client

Élément Rôle
pankosmia_metadata.json Déclare le client au serveur et aux autres clients (voir plus bas).
package.json Dépendances et scripts. homepage vaut /clients/<nom>.
vite.config.js Configuration de Vite : base vaut /clients/<nom>/, le serveur de développement a son propre port, et /api est redirigé vers le serveur Pankosmia (port 19119).
index.html, public/ Squelette de la page et fichiers statiques.
src/index.jsx Point d’entrée. Il enveloppe l’application dans le composant SpSpa de la RCL avec requireNet, titleKey (pages:<id>:title) et currentId (l’id des métadonnées).
src/App.jsx, src/components/ Les pages et composants du client.
build/ Résultat de vite build, le dossier réellement servi par le serveur.
storage_id.json Un UUID généré pour le client (écrit par scripts/write-storage-id.js avant start, dev et build), lorsque le client l’utilise.

pankosmia_metadata.json

Ce fichier est la carte d’identité d’un client. Le serveur le lit pour lister le client (/api/list-clients) et pour publier ce qu’il sait faire (/api/client-interfaces), et les traductions qu’il contient alimentent l’arbre i18n. Champs :

Champ Type Rôle
id chaîne Identifiant unique du client. C’est le nom de la section dans l’arbre i18n (pages:<id>:...), le currentId donné à SpSpa, et il identifie le client dans le menu.
require.net booléen Si true, le client a besoin d’internet. Son entrée de menu est désactivée hors ligne, et une page utilisant requireNet affiche un message d’accès refusé hors ligne.
require.debug booléen Si true, le client est un outil de développement : il est listé dans la section Débogage du menu, qui n’apparaît que si le mode débogage est activé. Si false ou absent, le client est dans le menu normal.
minServerVersion chaîne Version minimale du serveur (par exemple 0.20.3). L’application ne démarre pas si le serveur est plus ancien que le minimum requis par un client.
exclude_from_menu booléen Si true, le client n’est pas listé dans le menu de l’en-tête. Il reste accessible par son URL et par des liens d’autres clients.
exclude_from_dashboard booléen Si true, le client est retiré du tableau de bord, par exemple son entrée dans le bouton Créer.
i18n objet Traductions du client. Chaque clé est un nom avec un texte par code de langue. title et summary sont conventionnels. Voir la page i18n.
endpoints objet Les actions que le client offre aux autres clients, par type de document (voir plus bas).

Exemples

Le client des paramètres est masqué à la fois du menu et du tableau de bord :

{
  "id": "core-settings",
  "require": { "net": false },
  "minServerVersion": "0.20.3",
  "exclude_from_menu": true,
  "exclude_from_dashboard": true,
  "i18n": {
    "title": { "en": "Settings", "fr": "Paramètres" }
  }
}

Un gestionnaire de contenu réservé aux développeurs (require.debug), affiché dans la section Débogage du menu :

{
  "id": "contenthandler-template",
  "require": { "net": false, "debug": true },
  "i18n": {
    "title": { "en": "contenthandler-template" }
  }
}

endpoints

Les gestionnaires de contenu utilisent endpoints pour dire aux autres clients ce qu’ils savent faire avec un type de document (une saveur comme textTranslation). Les autres clients le lisent via /api/client-interfaces et construisent leurs menus à partir de celui-ci : un gestionnaire n’a donc pas besoin d’être connu par son nom. Chaque action est une liste d’entrées (edit est une entrée unique) avec ces champs :

  • doc : une description pour les développeurs.
  • label : une clé i18n (par exemple pages:core-contenthandler_obs:create_content_obs) affichée à l’utilisateur.
  • url : la page du client à ouvrir, relative à /clients/<id>/.
  • placeHolders : documente les variables utilisées dans url, comme %%REPO_PATH%%, remplacée par le chemin du dépôt au format <X>/<Y>/<Z>.
  • subMenu : uniquement pour export, regroupe les entrées par format (usfm, pdf…).

Actions utilisées :

Action Utilisation
create_document Entrées du bouton Créer du tableau de bord.
edit Le client qui ouvre un dépôt de ce type de document.
new_book, import_book, delete_book Actions sur un dépôt, proposées dans le client Contenu.
export Formats d’export d’un dépôt, par format dans subMenu.
about_repo, manager, initDocument, importContent Autres entrées lues par le tableau de bord.
download_resources Page de téléchargement de ressources (client des dépôts distants). 
{
  "id": "core-contenthandler_obs",
  "endpoints": {
    "textStories": {
      "create_document": [
        {
          "doc": "Create a document for OBS",
          "label": "pages:core-contenthandler_obs:create_content_obs",
          "url": "/createDocument/obsContent"
        }
      ],
      "edit": {
        "doc": "main page for workspace",
        "label": "pages:core-client-workspace:main",
        "url": "core-local-workspace#"
      }
    }
  }
}