Plugins nützlich machen

Einführung

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

Die Erstellung eines StudioCMS-Plugins ist eine leistungsstarke Möglichkeit, die Funktionalität von StudioCMS zu erweitern. Sie bieten eine einfache und flexible Möglichkeit, neue Funktionen zu deinem StudioCMS-Projekt hinzuzufügen. Das folgende Beispiel zeigt dir, wie du ein StudioCMS-Plugin erstellst und wie es funktioniert.

Erste Schritte

'Read the “', Erste Schritte, '” section'

Um loszulegen, musst du ein neues StudioCMS-Plugin erstellen. Im Folgenden findest du ein grundlegendes Beispiel für die Dateistruktur eines StudioCMS-Plugins:

• package.json
• Directorysrc

  • index.ts
  • Directoryroutes

    • […slug].astro
  • Directorydashboard-grid-items

    • MyPluginGridItem.astro

Erstellen des Plugins

'Read the “', Erstellen des Plugins, '” section'

In der Hauptdatei src/index.ts definierst du das StudioCMS Plugin. Das folgende Beispiel zeigt, wie du ein StudioCMS-Plugin definierst, das eine Astro-Integration enthält, um ein einfaches Blog-Beispiel zu erstellen:

index.ts

import { definePlugin } from 'studiocms/plugins';
import { AstroIntegration } from 'astro';
import { addVirtualImports, createResolver } from 'astro-integration-kit';

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

export function studioCMSPageInjector(options: Options) {

    // Löse den Pfad zur aktuellen Datei auf
    const { resolve } = createResolver(import.meta.url);

    // Definiere die Astro-Integration
    function myIntegration(options: Options): AstroIntegration {
        const route = `/${options?.route || 'my-plugin'}`;

        return {
            name: 'my-astro-integration',
            hooks: {
                "astro:config:setup": (params) => {
                    const { injectRoute } = params;

                    // Injiziere die Route für das Plugin
                    injectRoute({
                        entrypoint: resolve('./routes/[...slug].astro'),
                        pattern: `/${route}/[...slug]`,
                        prerender: false,
                    })

                    addVirtualImports(params, {
                        name: 'my-astro-integration',
                        imports: {
                            'myplugin:config': `
                                export const options = ${JSON.stringify({ route })};
                                export default options;
                            `,
                        }
                    })
                }
            }
        }
    }

    // Definiere das StudioCMS Plugin
    return definePlugin({
        identifier: 'my-plugin',
        name: 'My Plugin',
        studiocmsMinimumVersion: '0.1.0-beta.8',
        integration: myIntegration(options), // Optional, aber empfohlen
        // Definiere die Frontend-Navigationslinks für das Plugin (optional)
        // Dies ist nützlich, wenn du die eingebauten StudioCMS-Navigationshilfen in deinem Layout verwendest,
        // wie z.B. bei der Verwendung des Plugins `@studiocms/blog`.
        frontendNavigationLinks: [{ label: 'Title here', href: options?.route || 'my-plugin' }],
        // Wenn du pageTypes erstellst, kannst du auch eine `pageContentComponent` definieren, wenn dein Plugin einen eigenen Inhaltseditor benötigt.
        // pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)', pageContentComponent: resolve('./components/MyContentEditor.astro') }],
        // In diesem Beispiel ist es in Ordnung, den Standard-Editor (Markdown) zu verwenden.
        pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)' }],
        // Definiere die Gitterelemente für das Dashboard
        // Dies sind die Elemente, die auf dem StudioCMS Dashboard angezeigt werden
        // Du kannst so viele Elemente definieren, wie du willst
        // In diesem Beispiel definieren wir ein einzelnes Element, das eine Spannweite von 2 hat und die Berechtigung „Editor“ benötigt. Außerdem injizieren wir eine Astro-Komponente, die das einfache benutzerdefinierte HTML-Element ersetzt.
        dashboardGridItems: [
            {
                name: 'example',
                span: 2,
                variant: 'default',
                requiresPermission: 'editor',
                header: { title: 'Example', icon: 'bolt' },
                body: {
                    // Verwende immer einfaches HTML ohne `-` oder Sonderzeichen in den Tags. Sie werden durch die Astro-Komponente ersetzt und dieses HTML wird nie gerendert.
                    html: '<examplegriditem></examplegriditem>',
                    components: {
                        // Injiziere die Astro-Komponente, um das einfache benutzerdefinierte HTML-Element zu ersetzen
                        examplegriditem: resolve('./dashboard-grid-items/MyPluginGridItem.astro')
                    }
                }
            }
        ],
    });
}

Das obige Beispiel definiert ein StudioCMS-Plugin, das eine Astro-Integration enthält, um ein einfaches Blog-Beispiel zu erstellen. Das Plugin enthält eine Route, die in das StudioCMS-Projekt injiziert wird, und ein Grid-Element, das auf dem StudioCMS-Dashboard angezeigt wird.

Weitere Informationen darüber, wie du eine Astro-Integration erstellst, findest du im Astro Integration Kit^ und in der Astro Integrations Dokumentation^.

Beispiel-Route

'Read the “', Beispiel-Route, '” section'

In der Datei src/routes/[...slug].astro definierst du die Route für das Plugin. Das folgende Beispiel zeigt, wie du eine Route für das Plugin definierst. Der erste Teil ist das Frontmatter (zwischen den ----Zeichen) und der zweite Teil ist die HTML-Vorlage, die unter dem zweiten --- eingefügt wird.

Frontmatter

import { StudioCMSRenderer } from 'studiocms:renderer';
import sdk from 'studiocms:sdk';
import config from 'myplugin:config';

const makeRoute = (slug: string) => {
    return `/${config.route}/${slug}`;
}

// 'my-plugin' wird hier als Bezeichner für
// den pageType aus der Plugin-Definition verwendet
const pages = await sdk.GET.packagePages('my-plugin');

const { slug } = Astro.params;

const page = pages.find((page) => page.slug === slug || '');

Template

{
    slug && page ? (
        <div>
            <h1>{page.title}</h1>
            <StudioCMSRenderer content={page.defaultContent?.content || ''} />
        </div>
    ) : (
        <div>
            <h1>My Plugin</h1>
            <ul>
                {pages.length > 0 && pages.map((page) => (
                    <li>
                        <a href={makeRoute(page.slug)}>{page.title}</a>
                    </li>
                ))}
            </ul>
        </div>
    )
}

Das obige Beispiel definiert eine dynamische Route^ für das Plugin, die eine Liste von Blogposts anzeigt, wenn kein Slug angegeben wird, und die den Inhalt eines Blogposts anzeigt, wenn ein Slug angegeben wird.

Beispiel Gitterelement

'Read the “', Beispiel Gitterelement, '” section'

In der Datei src/dashboard-grid-items/MyPluginGridItem.astro definierst du das Grid Item für das Plugin. Das folgende Beispiel zeigt, wie du ein Grid Item für das Plugin definierst:

MyPluginGridItem.astro

---
import { StudioCMSRoutes } from 'studiocms:lib';
import sdk from 'studiocms:sdk';

// 'my-plugin' wird hier als Bezeichner für
// den pageType aus der Plugin-Definition verwendet
const pages = await sdk.GET.packagePages('my-plugin');

// Erhalte die 5 zuletzt aktualisierten Seiten der letzten 30 Tage
const recentlyUpdatedPages = pages
    .filter((page) => {
        const now = new Date();
        const thirtyDaysAgo = new Date(now.setDate(now.getDate() - 30));
        return new Date(page.updatedAt) > thirtyDaysAgo;
    })
    .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
    .slice(0, 5);
---

<div>
    <h2>Recently Updated Pages</h2>
    <ul>
        {recentlyUpdatedPages.length > 0 && recentlyUpdatedPages.map((page) => (
            <li>
                <a href={StudioCMSRoutes.mainLinks.contentManagementEdit + `?edit=${page.id}`}>{page.title}</a>
            </li>
        ))}
    </ul>
</div>

Das obige Beispiel definiert ein Grid-Element für das Plugin, das die 5 zuletzt aktualisierten Seiten der letzten 30 Tage anzeigt. Das Grid-Element enthält eine Liste mit Links zu den Bearbeitungsseiten der einzelnen Seiten im Content Management.

Integration mit den FrontendNavigationLinks Helfern

'Read the “', Integration mit den FrontendNavigationLinks Helfern, '” section'

Wenn du die eingebauten StudioCMS-Navigationshilfen in deinem Projekt verwenden möchtest, ähnlich wie das Plugin @studiocms/blog, kannst du eine eigene Komponente Navigation.astro erstellen:

Navigation.astro

---
import { StudioCMSRoutes } from 'studiocms:lib';
import studioCMS_SDK from 'studiocms:sdk/cache';
import { frontendNavigation } from 'studiocms:plugin-helpers';

// Definiere die Requisiten für die Komponente Navigation
interface Props {
  topLevelLinkCount?: number;
};

// Erhalte die Anzahl der Links auf oberster Ebene aus den Requisiten
const { topLevelLinkCount = 3 } = Astro.props;

// Abrufen der Website-Konfiguration und der Seitenliste
const config = (await studioCMS_SDK.GET.siteConfig()).data;

// Hol dir den Titel der Seite aus der Konfiguration
const { title } = config || { title: 'StudioCMS' };

// Erhalte die URL der Hauptseite
const {
  mainLinks: { baseSiteURL },
} = StudioCMSRoutes;

// Definiere die Link-Requisiten für die Navigation
type LinkProps = {
  text: string;
  href: string;
};

// Definiere die Links für die Navigation
const links: LinkProps[] = await frontendNavigation();
---
{/* Wenn keine Dropdown-Elemente */}
{ ( links.length < topLevelLinkCount || links.length === topLevelLinkCount ) && (
    <div class="navigation">
        <div class="title"><a href={baseSiteURL}>{title}</a></div>
        <div class="mini-nav">
            <button>Menu</button>
            <div class="mini-nav-content">
            {
                links.map(({ text, href }) => (
                    <a {href}>{text}</a>
                ))
            }
            </div>
        </div>
        {
            links.map(({ text, href }) => (
                <a class="links" {href}>{text}</a>
            ))
        }
    </div>
) }

{/* Wenn Dropdown-Elemente */}
{ links.length > topLevelLinkCount && (
    <div class="navigation">
        <div class="title"><a href={baseSiteURL}>{title}</a></div>

        <div class="mini-nav">
            <button>Menu</button>
            <div class="mini-nav-content">
            {
                links.map(({ text, href }) => (
                    <a {href}>{text}</a>
                ))
            }
            </div>
        </div>
        {
            links.slice(0, topLevelLinkCount).map(({ text, href }) => (
                    <a class="links" {href}>{text}</a>
            ))
        }
            <div class="dropdown">
                <button>More ▼</button>
                <div class="dropdown-content">
                    { links.slice(topLevelLinkCount).map(({ text, href }) => (
                        <a {href}>{text}</a>
                    )) }
                </div>
            </div>
    </div>
) }

Das obige Beispiel definiert eine benutzerdefinierte Komponente Navigation.astro, die die eingebauten StudioCMS-Navigationshilfen verwendet, um ein Navigationsmenü für das Projekt zu erstellen. Die Komponente enthält Links zur Haupt-URL der Website, zur Indexseite und zu allen anderen Seiten, die in der Navigation angezeigt werden sollen.

Du musst nur noch ein paar Stile hinzufügen und schon hast du ein voll funktionsfähiges Navigationsmenü, das mit den eingebauten StudioCMS-Navigationshelfern funktioniert.