Aller au contenu
StudioCMS Docs
Site principal
Démo

Les fondamentaux

Présentation

Section intitulée « Présentation »

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 ?

Section intitulée « Que sont les modules d’extension ? »

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

Section intitulée « Le type des modules d’extension de StudioCMS »
interface StudioCMSPlugin {
  identifier: string;
  name: string;
  studiocmsMinimumVersion: string;
  hooks: {
    'studiocms:astro:config': (params: {
      logger: AstroIntegrationLogger;
      addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void;
    }) => void | Promise<void>;
    'studiocms:config:setup': (params: {
      logger: AstroIntegrationLogger;
      setSitemap: (params: {
        triggerSitemap?: boolean | undefined;
        sitemaps?: {
          pluginName: string;
          sitemapXMLEndpointPath: string | URL;
        }[] | undefined;
      }) => void;
      setDashboard: (params: {
        dashboardGridItems?: GridItemInput[] | undefined;
        dashboardPages?: {
          user?: (...)[] | undefined;
          admin?: (...)[] | undefined;
        } | undefined;
        settingsPage?: {
          fields: (...)[];
          endpoint: string;
        } | undefined;
      }) => void;
      setFrontend: (params: {
        frontendNavigationLinks?: {
          label: string;
          href: string;
        }[] | undefined;
      }) => void;
      setRendering: (params: {
        pageTypes?: {
          label: string;
          identifier: string;
          description?: string | undefined;
          fields?: (...)[] | undefined;
          pageContentComponent?: string | undefined;
          rendererComponent?: string | undefined;
          apiEndpoint?: string | undefined;
        }[] | undefined;
      }) => void;
    }) => void | Promise<void>;
  }
}

Définir un module d’extension

Section intitulée « Définir un module d’extension »

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 { 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin } from 'studiocms/plugins';
import { 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration } from 'astro';


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


// Définir l’intégration Astro
const 
const monIntegration: (options: Options) => AstroIntegration
monIntegration = (
options: Options
options: 
interface Options
Options): 
(alias) interface AstroIntegration
import AstroIntegration
AstroIntegration => ({
    
AstroIntegration.name: string
The name of the integration.
name: 'mon-integration-astro',
    
AstroIntegration.hooks: {
    'astro:db:setup'?: (options: {
        extendDb: (options: {
            configEntrypoint?: URL | string;
            seedEntrypoint?: URL | string;
        }) => void;
    }) => void | Promise<void>;
    ... 12 more ...;
    'studiocms:plugins'?: PluginHook<...>;
} & Partial<...>
The different hooks available to extend.
hooks: {
        "astro:config:setup": () => {
            
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.


The module exports two specific components:


    

  • A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
    • 

  • A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.
    • 



Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.


Example using the global console:


console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3


const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr


Example using the Console class:


const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);


myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err


const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).


const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout


See util.format() for more information.
@since ― v0.1.100
log('Bonjour depuis mon intégration Astro !');
        }
    }
});


// Définir le module d’extension pour StudioCMS
export const 
const monModuleExtension: (options: Options) => StudioCMSPlugin
monModuleExtension = (
options: Options
options: 
interface Options
Options) => 
function definePlugin(options: StudioCMSPlugin): StudioCMSPlugin
Defines a plugin for StudioCMS.
@param ― options - The configuration options for the plugin.
@returns ― The plugin configuration.
definePlugin({
    
StudioCMSPlugin.identifier: string
identifier: 'mon-module-extension',
    
StudioCMSPlugin.name: string
name: "Mon module d’extension",
    
StudioCMSPlugin.studiocmsMinimumVersion: string
studiocmsMinimumVersion: '0.1.0-beta.18',
    
StudioCMSPlugin.hooks: {
    'studiocms:astro:config'?: PluginHook<...>;
    'studiocms:config:setup'?: PluginHook<...>;
} & Partial<...>
hooks: {
      'studiocms:astro:config': ({ 
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations }) => {
        
addIntegrations: (args_0: AstroIntegration | AstroIntegration[]) => void
addIntegrations(
const monIntegration: (options: Options) => AstroIntegration
monIntegration(
options: Options
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.18 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