L’essentiel de ce que vous faites avec l’API tourne autour de trois objets. Une story est un article. Elle appartient à un espace et a un propriétaire, un utilisateur. Cette page décrit chacun d’eux et les objets qui s’y rattachent. La référence GraphQL donne la liste complète des champs.

Story

Tout contenu d’une plateforme est une Story. Une story a un propriétaire (son user), un space et au moins une version.

Version

Une StoryVersion contient le contenu de la story à un moment donné : le titre, le corps, les assets, les attributs et le fait qu’elle soit publiée ou non. story.version renvoie la dernière version publiée dans la langue préférée de l’utilisateur ; passez lang pour choisir une langue, ou uuid pour lire une version précise.

Traductions

Une story peut être traduite dans toutes les langues autorisées par les paramètres de la plateforme. Une nouvelle version ne modifie qu’une langue, mais elle contient toutes les traductions qui existent à ce moment-là. Si une story a une version en français et que vous publiez une nouvelle version en anglais, celle-ci contient votre texte anglais et le texte français de la dernière version française, inchangé.

Corps

Le corps est un RichContent. Quand vous en écrivez un, vous donnez un format et le contenu dans markup :

Format	Usage
`MARKDOWN`	Le Markdown tel que les autres outils l’exportent : CommonMark plus les tableaux, les notes de bas de page et les listes de tâches.
`MARKDOWN_ELIUM`	Le Markdown avec les directives Elium (encadrés, sections repliables, assets). Format Markdown en entrée en est la référence.
`HTML`	N’importe quel HTML. Elium fait correspondre les balises à sa propre structure du mieux possible.
`HTML_ELIUM`	Le HTML canonique d’Elium, avec des éléments `el-*` pour les blocs Elium. Exact et sans perte.
`SLATE`	Le format interne de l’éditeur (Slate).

Quel que soit le format, Elium convertit le corps dans sa structure interne. Pour du contenu que vous générez, le Markdown est le plus simple. Pour copier du contenu depuis un autre système sans rien perdre, utilisez HTML_ELIUM.

Attributs

Un attribut est un champ structuré défini par un modèle (voir plus bas) : une date, un nombre, une valeur texte, un choix. Le ValueWrapperType de la référence liste les types de valeur. Les attributs sont versionnés avec la story, mais ils ne sont pas traduits.

Builtins

Les builtins ont la même forme que les attributs, mais ils ne sont pas définis par un modèle. Ils contiennent les métadonnées de base de toute story, comme son titre ou sa source.

Modèle

Un modèle est un StorySchema dans l’API. Vous pouvez en appliquer un à la création d’une story, avec schemaId. Le modèle donne sa forme à la story : il peut être traduit, et il peut définir un titre par défaut, un ensemble d’attributs et un corps avec du texte et des emplacements de blocs.

Assets

Un asset relie un fichier, une URL ou un autre objet à une story. La plupart des assets font partie du corps ou sont l’asset principal de la story. L’énumération AssetType liste les types d’assets : FILE, URL, USER, STORY, EMAIL, CLOUD_FILE, CLOUD_FOLDER et DRAWING.

Vous lisez les assets via version.assets. Les deux types courants sont FileAsset, un fichier importé, et URLAsset, un lien externe. Leur champ embed contient ce que vous cherchez le plus souvent : l’adresse de téléchargement, les miniatures et les métadonnées d’un fichier, ou l’extrait d’une page web (un résumé structuré de celle-ci). Lire une story avec ses assets en montre un exemple.

Asset principal et couverture

Une story peut avoir un asset principal, en général un FileAsset ou un URLAsset. Elium en tire la miniature de la story. Pour utiliser une autre image, définissez un coverAsset, toujours un FileAsset et en pratique une image.

Actions

story.actions indique ce que l’utilisateur courant peut faire de la story : edit, delete, deleteVersion, etc. Lisez-le avant d’appeler une mutation, comme l’explique Erreurs.

Espace

Un Space est un conteneur de stories. Les types d’espace décrit les espaces tels que les utilisateurs les voient. Quand vous créez une story, vous donnez un spaceId ; null la range dans le contenu personnel de l’utilisateur.

Un groupe d’espaces contient plusieurs espaces. Il n’y a pas de lien direct entre une story et un groupe d’espaces.

Utilisateur

Toute story a besoin d’un User à sa création : cet utilisateur en devient le propriétaire. Quand un utilisateur crée ou publie une version, il est aussi ajouté aux contributeurs de la story.

Ce qu’un utilisateur peut voir et modifier dépend de ses rôles sur la plateforme et dans chaque espace. Droits et visibilités explique les règles ; l’API les applique à chaque appel.