Haciendo complementos útiles

Introducción

Crear un complemento para StudioCMS es una forma poderosa de extender la funcionalidad de StudioCMS. Los complementos proporcionan una manera simple y flexible de agregar nuevas características a tu proyecto StudioCMS. A continuación se muestra un ejemplo básico de cómo crear un complemento de StudioCMS y cómo funciona.

Primeros Pasos

Para comenzar, necesitarás crear un nuevo complemento de StudioCMS. A continuación se muestra un ejemplo básico de la estructura de archivos para un complemento de StudioCMS:

• package.json
• Directorysrc

  • index.ts
  • Directoryroutes

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

    • MyPluginGridItem.astro

Creando el complemento

En el archivo principal src/index.ts, definirás el complemento de StudioCMS. A continuación se muestra un ejemplo de cómo definir un complemento de StudioCMS que incluye una Integración Astro para crear un ejemplo simple de blog:

index.ts

import { definePlugin } from 'studiocms/plugins';
import { AstroIntegration } from 'astro';
import { addVirtualImports, createResolver } from 'astro-integration-kit';
Error ts(2307)  ― Cannot find module 'astro-integration-kit' or its corresponding type declarations.

// Define las opciones para el complemento y la integración
interface Options {
    route: string;
}

export function studioCMSPageInjector(options: Options) {
    // Resuelve la ruta al archivo actual
    const { resolve } = createResolver(import.meta.url);

    // Define la integración Astro
    function myIntegration(options: Options): AstroIntegration {
        const route = `/${options?.route || 'my-plugin'}`;

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

                    // Inyecta la ruta para el complemento
                    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;
                            `,
                        }
                    })
                }
            }
        }
    }

  // Define el complemento de StudioCMS
  return definePlugin({
    identifier: 'my-plugin',
    name: 'My Plugin',
    studiocmsMinimumVersion: '0.1.0',
    hooks: {
      'studiocms:astro-config': ({ addIntegrations }) => {
        addIntegrations(myIntegration(options));  // Opcional, pero recomendado
      },
      'studiocms:dashboard': ({ setDashboard }) => {
        setDashboard({
          translations: {
            en: {
              example: {
                title: 'Example',
                'other-text': 'Some other text',
              }
            },
            fr: {
              example: {
                title: 'Exemple',
                'other-text': 'Un autre texte',
              }
            }
          },

          // Define los elementos de la cuadrícula para el dashboard
          // Estos son los elementos que se mostrarán en el Dashboard de StudioCMS
          // Puedes definir tantos elementos como quieras
          // En este ejemplo, estamos definiendo un solo elemento, que tiene un span de 2 y requiere el permiso 'editor' y inyecta un componente Astro que reemplaza el elemento html personalizado.
          dashboardGridItems: [
            {
              name: 'example',
              span: 2,
              variant: 'default',
              requiresPermission: 'editor',
              header: { title: 'Example', icon: 'bolt' },
              body: {
                // Siempre usa html plano sin `-` o caracteres especiales en las etiquetas, se reemplazarán con el componente Astro y este HTML nunca se renderizará
                html: '<examplegriditem></examplegriditem>',
                components: {
                  // Inyecta el componente Astro para reemplazar el elemento html personalizado
                  examplegriditem: resolve('./dashboard-grid-items/MyPluginGridItem.astro')
                }
              }
            }
          ],
        });
      },

      'studiocms:frontend': ({ setFrontend }) => {
        setFrontend({
          // Define los enlaces de navegación del frontend para el complemento
          // Esto es útil si estás usando los ayudantes de navegación de StudioCMS incorporados en tu diseño,
          // como cuando usas el complemento `@studiocms/blog`.
          frontendNavigationLinks: [{ label: 'My Plugin', href: options?.route || 'my-plugin' }],
        });
      },
      'studiocms:rendering': ({ setRendering }) => {
        setRendering({
          // Cuando creas pageTypes, también puedes definir un `pageContentComponent` si tu complemento requiere un editor de contenido personalizado.
          // pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)', pageContentComponent: resolve('./components/MyContentEditor.astro') }],
          // En este ejemplo estamos usando el editor de contenido por defecto (markdown).
          pageTypes: [{ identifier: 'my-plugin', label: 'Blog Post (My Plugin)' }],
        });
      }
    }
  });
}

El ejemplo anterior define un complemento de StudioCMS que incluye una integración Astro para crear un ejemplo simple de blog. El complemento incluye una ruta que se inyecta en el proyecto StudioCMS y un elemento de cuadrícula que se muestra en el panel de control de StudioCMS.

Para más información sobre cómo crear una integración Astro, consulta el Kit de integración de Astro^ y la documentación de integraciones de Astro^.

Ejemplo de ruta

En el archivo src/routes/[...slug].astro, definirás la ruta para el complemento. A continuación se muestra un ejemplo de cómo definir una ruta para el complemento, lo dividiremos en dos partes, la primera parte es el frontmatter (entre las marcas ---), y la segunda parte es la plantilla HTML que se coloca debajo del segundo ---.

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' aquí se usa como identificador para
// el pageType de la definición del complemento
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>Mi complemento</h1>
            <ul>
                {pages.length > 0 && pages.map((page) => (
                    <li>
                        <a href={makeRoute(page.slug)}>{page.title}</a>
                    </li>
                ))}
            </ul>
        </div>
    )
}

El ejemplo anterior define una ruta dinámica^ para el complemento que muestra una lista de entradas de blog cuando no se proporciona un slug y muestra el contenido de una entrada de blog cuando se proporciona un slug.

Ejemplo de elemento de cuadrícula

En el archivo src/dashboard-grid-items/MyPluginGridItem.astro, definirás el elemento de cuadrícula para el complemento. A continuación se muestra un ejemplo de cómo definir un elemento de cuadrícula para el complemento:

MyPluginGridItem.astro

---
import { SDKCoreJs, runSDK } from 'studiocms:sdk';

// 'my-plugin' aquí se usa como identificador para
// el pageType de la definición del complemento
const pages = await runSDK(SDKCoreJs.GET.packagePages('my-plugin'));

// Consigue las 5 páginas actualizadas más recientemente de los últimos 30 días
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>Páginas actualizadas recientemente</h2>
    <ul>
        {recentlyUpdatedPages.length > 0 && recentlyUpdatedPages.map((page) => (
            <li>
                <a href={Astro.locals.routeMap.mainLinks.contentManagementEdit + `?edit=${page.id}`}>{page.title}</a>
            </li>
        ))}
    </ul>
</div>

El ejemplo anterior define un elemento de cuadrícula para el complemento que muestra las 5 páginas actualizadas más recientemente de los últimos 30 días. El elemento de cuadrícula incluye una lista de enlaces a la página de edición de gestión de contenido para cada página.

Integrando con los ayudantes (helpers) de FrontendNavigationLinks

Si deseas usar los ayudantes (helpers) de navegación incorporados de StudioCMS en tu proyecto, similar a como lo hace el complemento @studiocms/blog, puedes crear un componente personalizado Navigation.astro:

Navigation.astro

---
import { frontendNavigation } from 'studiocms:plugin-helpers';

// Define las props para el componente de navegación
interface Props {
  topLevelLinkCount?: number;
};

// Consigue el enlace de nivel superior de las props
const { topLevelLinkCount = 3 } = Astro.props;

// Consigue la configuración del sitio y la lista de páginas
const config = Astro.locals.siteConfig.data;

// Consigue el título del sitio de la configuración
const { title } = config || { title: 'StudioCMS' };

// Consigue la URL principal del sitio
const {
  mainLinks: { baseSiteURL },
} = Astro.locals.routeMap;

// Define las props de enlace para la navegación
type LinkProps = {
  text: string;
  href: string;
};

// Define los enlaces para la navegación
const links: LinkProps[] = await frontendNavigation();
---
{/* Si no hay elementos dropdown */}
{ ( 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>
) }

{/* Si hay elementos dropdown */}
{ 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>
) }

El ejemplo anterior define un componente personalizado Navigation.astro que utiliza los ayudantes de navegación incorporados de StudioCMS para crear un menú de navegación para el proyecto. El componente incluye enlaces a la URL principal del sitio, la página de índice y cualquier otra página que esté configurada para mostrarse en la navegación.

Todo lo que necesitas hacer es agregar algunos estilos, y tendrás un menú de navegación completamente funcional que funciona con los ayudantes de navegación incorporados de StudioCMS.