Die Grundlagen

Einführung

'Read the “', Einführung, '” section'

StudioCMS-Plugins sind ein leistungsstarkes Werkzeug, mit dem du die Funktionalität von StudioCMS erweitern kannst. Sie bieten eine einfache und flexible Möglichkeit, neue Funktionen zu deinem StudioCMS-Projekt hinzuzufügen. Im Folgenden findest du eine Übersicht über die StudioCMS-Plugins und ihre Funktionsweise.

Was sind Plugins?

'Read the “', Was sind Plugins?, '” section'

StudioCMS-Plugins sind ähnlich wie Astro-Integrationen, aber sie haben zusätzliche Informationen, die an das Funktionsobjekt angehängt sind. Diese Informationen werden von StudioCMS verwendet, um zu bestimmen, wie das Plugin geladen und verwendet werden soll. StudioCMS-Plugins werden verwendet, um die Funktionalität von StudioCMS zu erweitern, indem neue Funktionen hinzugefügt oder bestehende geändert werden.

Der StudioCMS Plugin-Typ

'Read the “', Der StudioCMS Plugin-Typ, '” section'

type StudioCMSPlugin = {
  /**
   * Kennung des Plugins aus der package.json
   */
  identifier: string;

  /**
   * Bezeichnung des Plugins, die im StudioCMS Dashboard angezeigt werden soll
   */
  name: string;

  /**
   * Erforderliche Mindestversion von StudioCMS, damit das Plugin funktioniert
   */
  studiocmsMinimumVersion: string;

  /**
   * Astro-Integration(en), die das Plugin bietet
   */
  integration?: AstroIntegration | AstroIntegration[] | undefined;

  /**
   * Wenn dies der Fall ist, aktiviert das Plugin die Erstellung der Sitemap
   */
  triggerSitemap?: boolean;

  /**
   * Ermöglicht es dem Plugin, Sitemap-Endpunkte hinzuzufügen
   */
  sitemaps?: Array<{

    /**
     * Name des Plugins
     */
    pluginName: string;

    /**
     * Pfad zur Sitemap-Xml-Endpunktdatei
     */
    sitemapXMLEndpointPath: string | URL;
  }> | undefined;

  /**
   * Ermöglicht es dem Plugin, benutzerdefinierte Dashboard-Gitterelemente hinzuzufügen
   */
  dashboardGridItems?: Array<{

    /**
     * Name des Gitterelements
     */
    name: string;

    /**
     * Spannweite des Gitterelements
     */
    span: 1 | 2 | 3;

    /**
     * Kartenvariante des Gitterelements
     */
    variant: 'default' | 'filled';

    /**
     * Erlaubnis erforderlich, um das Gitterelement anzuzeigen
     */
    requiresPermission?: "owner" | "admin" | "editor" | "visitor";

    /**
     * Kopfzeileninformationen des Gitterelements
     */
    header?: {

      /**
       * Titel des Gitterelements
       */
      title: string;

      /**
       * Symbol für das Gitterelement
       */
      icon?: HeroIconName;
    };

    /**
     * Körperinformationen des Gitterelements
     */
    body?: {

      /**
       * HTML-Inhalt des Gitterelements
       */
      html: string;

      /**
       * Komponente, die im Gitterelement angezeigt wird
       */
      components?: Record<string, string>;

      /**
       * Sanitize-Optionen für den HTML-Inhalt
       */
      sanitizeOpts?: SanitizeOptions;
    };
  }> | undefined;

  /**
   * Wenn dies der Fall ist, hat das Plugin seine eigene Einstellungsseite
   */
  settingsPage: {

    /**
     * Felder gemäß Spezifikation
     */
    fields: SettingsField[];

    /**
     * Der Endpunkt für die Einstellungen
     *
     * Sollte eine APIRoute namens `onSave` exportieren, die ausgeführt wird, wenn die Einstellungsseite gespeichert wird
     */
    endpoint: string,
  } | undefined;

  /**
   * Navigationslinks für die Verwendung mit dem `@studiocms/blog`-Plugin und anderen Plugins zur Anzeige von Links im Frontend
   */
  frontendNavigationLinks: Array<{
    label: string;
    href: string;
  }>;

  /**
   * Seitentyp-Definition. Wenn dies der Fall ist, möchte das Plugin den Prozess der Seitenerstellung ändern können
   */
  pageTypes: Array<{

    /**
     * Beschriftung, die in der Select-Eingabe angezeigt wird
     */
    label: string;

    /**
     * Kennung, die in der Datenbank gespeichert wird
     * @example
     * // Einzelner Seitentyp pro Plugin
     * 'studiocms'
     * '@studiocms/blog'
     * // Mehrere Seitentypen pro Plugin (verwende eindeutige Bezeichner für jeden Typ, um Konflikte zu vermeiden)
     * '@mystudiocms/plugin:pageType1'
     * '@mystudiocms/plugin:pageType2'
     * '@mystudiocms/plugin:pageType3'
     * '@mystudiocms/plugin:pageType4'
     */
    identifier: string;

    /**
     * Beschreibung, die unter der Überschrift „Seiteninhalt“ angezeigt wird, wenn dieser Typ ausgewählt ist
     */
    description: string;

    /**
     * Der Pfad zu der eigentlichen Komponente, die für den Seiteninhalt angezeigt wird
     *
     * Die Komponente sollte eine Eigenschaft `content` haben, die ein String ist, um den aktuellen Inhalt anzeigen zu können.
     *
     * **HINWEIS:** Derzeit musst du die Formular-ID `page-content` für die Inhaltsausgabe verwenden. Dein Editor sollte auch in der Lage sein, die Formularübermittlung zu verarbeiten.
     *
     * **HINWEIS:** Du kannst `studiocms/markdown` oder `studiocms/html` als Fallback-Wert verwenden, wenn du mit HTML- oder Markdown-Inhalten arbeitest!
     *
     * @example
     * ```ts
     * import { createResolver } from 'astro-integration-kit';
     * const { resolve } = createResolver(import.meta.url)
     *
     * {
     *  pageContentComponent: resolve('./components/MyContentEditor.astro'),
     * }
     * ```
     */
    pageContentComponent: 'studiocms/markdown' | 'studiocms/html' | string;

    /**
     * Der Pfad zu der tatsächlichen Komponente, die für den Seitenrenderer angezeigt wird
     *
     * **HINWEIS:** Du kannst `studiocms/markdown` oder `studiocms/html` als Fallback-Wert verwenden, wenn du mit HTML- oder Markdown-Inhalten arbeitest!
     */
    rendererComponent: 'studiocms/markdown' | 'studiocms/html' | string;

    /**
     * Felder gemäß Spezifikation
     */
    fields: SettingsField[];

    /**
     * API-Endpunktdatei für den Seitentyp
     *
     * API-Endpunkte werden verwendet, um Seiten dieses Typs zu erstellen, zu bearbeiten und zu löschen,
     * Endpunkte erhalten den vollständigen Astro APIContext von der Astro APIRoute.
     *
     * Die Datei sollte mindestens einen der folgenden Punkte exportieren:
     * - `onCreate`
     * - `onEdit`
     * - `onDelete`
     *
     * @example
     * ```ts
     * // my-plugin.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) => {
     *   // Custom logic here
     *   return new Response();
     * }
     * ```
     */
    apiEndpoint: string;
  }> | undefined;
};

Ein Plugin definieren

'Read the “', Ein Plugin definieren, '” section'

Um ein StudioCMS-Plugin zu definieren, musst du ein Objekt erstellen, das dem Typ StudioCMSPlugin entspricht. Dieses Objekt sollte ähnlich wie das folgende aussehen, wobei du beachten musst, dass die folgenden Eigenschaften erforderlich sind:

• identifier: Der Bezeichner des Plugins aus der package.json-Datei.
• name: Die Bezeichnung des Plugins, die im StudioCMS Dashboard angezeigt werden soll.
• studiocmsMinimumVersion: Die Mindestversion von StudioCMS, die benötigt wird, damit das Plugin funktioniert.

Hier ist ein Beispiel für eine StudioCMS-Plugin-Definition, die alle erforderlichen Eigenschaften enthält und eine Astro-Integration für eigene Logik bereitstellt:

my-plugin.ts

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

// Definiere die Optionen für das Plugin und die Integration
interface Options {
    foo: string;
}

// Definiere die Astro-Integration
const myIntegration = (options: Options): AstroIntegration => ({
    name: 'my-astro-integration',
    hooks: {
        "astro:config:setup": () => {
            console.log('Hello from my Astro Integration!');
        }
    }
});

// Definiere das StudioCMS-Plugin
export const myPlugin = (options: Options) => definePlugin({
    identifier: 'my-plugin',
    name: 'My Plugin',
    studiocmsMinimumVersion: '0.1.0-beta.8',
    integration: myIntegration(options), // Optional, aber empfohlen
});

In diesem Beispiel definieren wir ein StudioCMS-Plugin namens My Plugin, das StudioCMS Version 0.1.0-beta.8 oder höher benötigt. Das Plugin stellt außerdem eine Astro-Integration bereit, die eine Meldung auf der Konsole protokolliert, wenn der astro:config:setup-Hook aufgerufen wird.

Weitere Informationen zur Erstellung von Plugins findest du in der „Plugins nützlich machen“-Anleitung.