Clientes

Estructura de un cliente y opciones de pankosmia_metadata.json

Tabla de contenidos

Qué es un cliente

Un cliente es una aplicación web (React, compilada con Vite) servida por el servidor Pankosmia en /clients/<nombre>. El panel, los ajustes y cada gestor de contenido (core-contenthandler_*) son clientes. Un producto incluye un cliente listándolo en CLIENTn de app_config.env (y por tanto en libClients de buildSpec.json). La compilación copia entonces su salida build/, package.json, pankosmia_metadata.json y storage_id.json (si existe) en lib/clients/<nombre del repositorio>.

Estructura de un cliente

Elemento Qué hace
pankosmia_metadata.json Declara el cliente al servidor y a los demás clientes (véase abajo).
package.json Dependencias y scripts. homepage es /clients/<nombre>.
vite.config.js Configuración de Vite: base es /clients/<nombre>/, el servidor de desarrollo tiene su propio puerto y /api se redirige al servidor Pankosmia (puerto 19119).
index.html, public/ Estructura de la página y archivos estáticos.
src/index.jsx Punto de entrada. Envuelve la app en el componente SpSpa de la RCL con requireNet, titleKey (pages:<id>:title) y currentId (el id de los metadatos).
src/App.jsx, src/components/ Las páginas y componentes del cliente.
build/ Salida de vite build, la carpeta que el servidor sirve realmente.
storage_id.json Un UUID generado para el cliente (escrito por scripts/write-storage-id.js antes de start, dev y build), cuando el cliente lo usa.

pankosmia_metadata.json

Este archivo es el documento de identidad de un cliente. El servidor lo lee para listar el cliente (/api/list-clients) y publicar lo que puede hacer (/api/client-interfaces), y las traducciones que contiene alimentan el árbol i18n. Campos:

Campo Tipo Qué hace
id cadena Identificador único del cliente. Es el nombre de la sección en el árbol i18n (pages:<id>:...), el currentId que se pasa a SpSpa, e identifica al cliente en el menú.
require.net booleano Si es true, el cliente necesita internet. Su entrada de menú se desactiva sin conexión, y una página que usa requireNet muestra un mensaje de acceso denegado sin conexión.
require.debug booleano Si es true, el cliente es una herramienta de desarrollo: aparece en la sección Depuración del menú, que solo se muestra con el modo de depuración activado. Si es false o no existe, el cliente está en el menú normal.
minServerVersion cadena Versión mínima del servidor (por ejemplo 0.20.3). La aplicación no se ejecuta si el servidor es más antiguo que el mínimo requerido por un cliente.
exclude_from_menu booleano Si es true, el cliente no aparece en el menú de la cabecera. Sigue accesible por su URL y desde enlaces de otros clientes.
exclude_from_dashboard booleano Si es true, el cliente se quita del panel, por ejemplo su entrada en el botón Crear.
i18n objeto Traducciones del cliente. Cada clave es un nombre con un texto por código de idioma. title y summary son convencionales. Véase la página i18n.
endpoints objeto Las acciones que el cliente ofrece a otros clientes, por tipo de documento (véase abajo).

Ejemplos

El cliente de ajustes está oculto tanto del menú como del panel:

{
  "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 gestor de contenido solo para desarrolladores (require.debug), mostrado en la sección Depuración del menú:

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

endpoints

Los gestores de contenido usan endpoints para decir a los demás clientes qué pueden hacer con un tipo de documento (un sabor como textTranslation). Los otros clientes lo leen desde /api/client-interfaces y construyen sus menús a partir de él, así que un gestor no necesita ser conocido por su nombre. Cada acción es una lista de entradas (edit es una única entrada) con estos campos:

  • doc: una descripción para desarrolladores.
  • label: una clave i18n (por ejemplo pages:core-contenthandler_obs:create_content_obs) que se muestra al usuario.
  • url: la página del cliente que se abre, relativa a /clients/<id>/.
  • placeHolders: documenta las variables usadas en url, como %%REPO_PATH%%, sustituida por la ruta del repositorio en formato <X>/<Y>/<Z>.
  • subMenu: solo para export, agrupa las entradas por formato (usfm, pdf…).

Acciones en uso:

Acción Uso
create_document Entradas del botón Crear del panel.
edit El cliente que abre un repositorio de este tipo de documento.
new_book, import_book, delete_book Acciones sobre un repositorio, ofrecidas en el cliente Contenido.
export Formatos de exportación de un repositorio, por formato en subMenu.
about_repo, manager, initDocument, importContent Otras entradas leídas por el panel.
download_resources Página para descargar recursos (cliente de repositorios remotos). 
{
  "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#"
      }
    }
  }
}