Les fondamentaux

Présentation

'Read the “', Présentation, '” section'

Les modules d’extension de StudioCMS sont un outil puissant qui vous permet d’étendre les fonctionnalités de StudioCMS. Ils offrent un moyen simple et flexible d’ajouter de nouvelles fonctionnalités à votre projet StudioCMS. Voici une description des modules d’extension de StudioCMS et de leur fonctionnement.

Que sont les modules d’extension ?

'Read the “', Que sont les modules d’extension ?, '” section'

Les modules d’extension de StudioCMS sont similaires aux intégrations Astro, mais ils intègrent des informations supplémentaires à l’objet fonction. Ces informations sont utilisées par StudioCMS pour déterminer comment le module d’extension doit être chargé et utilisé. Les modules d’extension de StudioCMS permettent d’étendre les fonctionnalités de StudioCMS en ajoutant de nouvelles fonctionnalités ou en modifiant celles existantes.

Le type des modules d’extension de StudioCMS

'Read the “', Le type des modules d’extension de StudioCMS, '” section'

type StudioCMSPlugin = {
  /**
   * Identifiant du module d’extension à partir du package.json
   */
  identifier: string;

  /**
   * Libellé du module d’extension à afficher dans le tableau de bord de StudioCMS
   */
  name: string;

  /**
   * Version minimale de StudioCMS requise pour que le module d’extension fonctionne
   */
  studiocmsMinimumVersion: string;

  /**
   * Intégration(s) Astro fournie(s) par le module d’extension
   */
  integration?: AstroIntegration | AstroIntegration[] | undefined;

  /**
   * Si cela est vrai, le module d’extension permettra la génération du plan du site
   */
  triggerSitemap?: boolean;

  /**
   * Permet au module d’extension d’ajouter des points de terminaison de plan de site
   */
  sitemaps?: Array<{

    /**
     * Nom du module d’extension
     */
    pluginName: string;

    /**
     * Chemin d’accès au fichier de point de terminaison XML du plan du site
     */
    sitemapXMLEndpointPath: string | URL;
  }> | undefined;

  /**
   * Permet au module d’extension d’ajouter des éléments de grille de tableau de bord personnalisés
   */
  dashboardGridItems?: Array<{

    /**
     * Nom de l’élément de la grille
     */
    name: string;

    /**
     * Étendue de l’élément de grille
     */
    span: 1 | 2 | 3;

    /**
     * Variante de carte de l’élément de grille
     */
    variant: 'default' | 'filled';

    /**
     * Autorisation requise pour visualiser l’élément de la grille
     */
    requiresPermission?: "owner" | "admin" | "editor" | "visitor";

    /**
     * Informations d’en-tête de l’élément de grille
     */
    header?: {

      /**
       * Titre de l’élément de la grille
       */
      title: string;

      /**
       * Icône de l’élément de la grille
       */
      icon?: HeroIconName;
    };

    /**
     * Informations sur le corps de l’élément de la grille
     */
    body?: {

      /**
       * Contenu HTML de l’élément de la grille
       */
      html: string;

      /**
       * Composant affiché dans l’élément de grille
       */
      components?: Record<string, string>;

      /**
       * Options d’assainissement du contenu HTML
       */
      sanitizeOpts?: SanitizeOptions;
    };
  }> | undefined;

  /**
   * Si cela existe, le module d’extension aura sa propre page de paramètres
   */
  settingsPage: {

    /**
     * Champs selon les spécifications
     */
    fields: SettingsField[];

    /**
     * Le point de terminaison des paramètres
     *
     * Doit exporter une APIRoute nommée `onSave` qui s’exécute lorsque la page des paramètres est enregistrée
     */
    endpoint: string,
  } | undefined;

  /**
   * Liens de navigation à utiliser avec le module d’extension `@studiocms/blog` et d’autres modules d’extension pour afficher des liens dans le front-end
   */
  frontendNavigationLinks: Array<{
    label: string;
    href: string;
  }>;

  /**
   * Définition du type de page. Si cette option est présente, le module d’extension souhaite pouvoir modifier le processus de création de page.
   */
  pageTypes: Array<{

    /**
     * Libellé affiché dans l’entrée de sélection
     */
    label: string;

    /**
     * Identifiant enregistré dans la base de données
     * @example
     * // Un type de page unique par module d’extension
     * 'studiocms'
     * '@studiocms/blog'
     * // Plusieurs types de pages par module d’extension (utilisez des identifiants uniques pour chaque type pour éviter les conflits)
     * '@mystudiocms/plugin:pageType1'
     * '@mystudiocms/plugin:pageType2'
     * '@mystudiocms/plugin:pageType3'
     * '@mystudiocms/plugin:pageType4'
     */
    identifier: string;

    /**
     * Description affichée sous l’en-tête « Contenu de la page » si ce type est sélectionné
     */
    description: string;

    /**
     * Le chemin vers le composant réel affiché pour le contenu de la page
     *
     * Le composant doit avoir une propriété `content` qui est une chaîne de caractères pour pouvoir afficher le contenu actuel.
     *
     * **À NOTER :** Actuellement, vous devez utiliser l’identifiant de formulaire `page-content` pour la sortie du contenu. Votre éditeur doit également pouvoir gérer la soumission des formulaires.
     *
     * **À NOTER :** Vous pouvez utiliser `studiocms/markdown` ou `studiocms/html` comme valeur de secours si vous travaillez avec du contenu HTML ou Markdown !
     *
     * @example
     * ```ts
     * import { createResolver } from 'astro-integration-kit';
     * const { resolve } = createResolver(import.meta.url)
     *
     * {
     *  pageContentComponent: resolve('./components/MonEditeurDeContenu.astro'),
     * }
     * ```
     */
    pageContentComponent: 'studiocms/markdown' | 'studiocms/html' | string;

    /**
     * Le chemin vers le composant réel affiché pour le moteur de rendu de page
     *
     * **À NOTER :** Vous pouvez utiliser `studiocms/markdown` ou `studiocms/html` comme valeur de secours si vous travaillez avec du contenu HTML ou Markdown !
     */
    rendererComponent: 'studiocms/markdown' | 'studiocms/html' | string;

    /**
     * Champs selon spécifications
     */
    fields: SettingsField[];

    /**
     * Fichier de point de terminaison de l’API pour le type de page
     *
     * Les points de terminaison de l’API sont utilisés pour créer, modifier et supprimer des pages de ce type.
     * Les points de terminaison recevront l’intégralité de l’APIContext d’Astro à partir de l’APIRoute d’Astro.
     *
     * Le fichier doit exporter au moins l’un des éléments suivants :
     * - `onCreate`
     * - `onEdit`
     * - `onDelete`
     *
     * @example
     * ```ts
     * // mon-module-extension.ts
     * import { createResolver } from 'astro-integration-kit';
     * const { resolve } = createResolver(import.meta.url)
     *
     * {
     *  apiEndpoint: resolve('./api/pageTypeApi.ts'),
     * }
     *
     * // api/pageTypeApi.ts
     * import { APIRoute } from 'astro';
     *
     * export const onCreate: APIRoute = async (ctx) => {
     *   // Logique personnalisée ici
     *   return new Response();
     * }
     * ```
     */
    apiEndpoint: string;
  }> | undefined;
};

Définir un module d’extension

'Read the “', Définir un module d’extension, '” section'

Pour définir un module d’extension pour StudioCMS, vous devez créer un objet conforme au type StudioCMSPlugin. Cet objet doit ressembler à l’exemple suivant, sachant que les propriétés suivantes sont requises :

• identifier : L’identifiant du module d’extension à partir du fichier package.json.
• name : Le libellé du module d’extension à afficher dans le tableau de bord de StudioCMS.
• studiocmsMinimumVersion : La version minimale de StudioCMS requise pour que le module d’extension fonctionne.

Voici un exemple de définition de module d’extension pour StudioCMS qui inclut toutes les propriétés requises et fournit une intégration Astro pour effectuer une logique personnalisée :

mon-module-extension.ts

import { definePlugin } from 'studiocms/plugins';
import { AstroIntegration } from 'astro';

// Définir les options du module d’extension et de l’intégration
interface Options {
    foo: string;
}

// Définir l’intégration Astro
const monIntegration = (options: Options): AstroIntegration => ({
    name: 'mon-integration-astro',
    hooks: {
        "astro:config:setup": () => {
            console.log('Bonjour depuis mon intégration Astro !');
        }
    }
});

// Définir le module d’extension pour StudioCMS
export const monModuleExtension = (options: Options) => definePlugin({
    identifier: 'mon-module-extension',
    name: "Mon module d'extension",
    studiocmsMinimumVersion: '0.1.0-beta.8',
    integration: monIntegration(options), // Facultatif, mais recommandé
});

Dans cet exemple, nous définissons un module d’extension pour StudioCMS appelé Mon module d’extension qui nécessite la version 0.1.0-beta.8 ou supérieure de StudioCMS. Le module d’extension fournit également une intégration Astro qui enregistre un message dans la console lorsque le crochet astro:config:setup est appelé.

Pour plus d’informations sur la création de modules d’extension, consultez le guide Rendre les modules d’extension utiles