Cómo crear páginas de taxonomía con Gatsby y Sanity.io

En este tutorial, cubriremos cómo crear páginas de taxonomía con Gatsby con contenido estructurado de Sanity.io. Aprenderá a utilizar la API de creación de nodos de Gatsby para agregar campos a sus tipos de contenido en la API GraphQL de Gatsby. Específicamente, vamos a crear páginas de categorías para el blog inicial de Sanity.

Dicho esto, no hay nada específico de Sanity en lo que cubrimos aquí. Puedes hacer esto independientemente de la fuente de contenido que tengas. Sólo estamos recurriendo a Sanity.io para realizar una demostración.

Ponte en marcha con el blog.

Si desea seguir este tutorial con su propio proyecto Gatsby, continúe y pase a la sección para crear una nueva plantilla de página en Gatsby. De lo contrario, dirígete a sanity.io/create e inicia el iniciador del blog Gatsby. Pondrá el código para Sanity Studio y el front-end de Gatsby en su cuenta de GitHub y configurará la implementación para ambos en Netlify. Toda la configuración, incluido el contenido de ejemplo, estará implementada para que pueda sumergirse directamente en el aprendizaje de cómo crear páginas de taxonomía.

Una vez iniciado el proyecto, asegúrese de clonar el nuevo repositorio en GitHub local e instalar las dependencias:

git clone git@github.com:username/your-repository-name.gitcd your-repository-namenpm i

Si desea ejecutar Sanity Studio (el CMS) y el front-end de Gatsby localmente, puede hacerlo ejecutando el comando npm run deven una terminal desde la raíz del proyecto. También puedes cdingresar a la carpeta web y simplemente ejecutar Gatsby con el mismo comando.

También debe instalar Sanity CLI e iniciar sesión en su cuenta desde la terminal: npm i -g @sanity/cli sanity login. Esto le brindará herramientas y comandos útiles para interactuar con proyectos de Sanity. Puede agregar la --helpbandera para obtener más información sobre su funcionalidad y comandos.

Haremos algunas personalizaciones en el gatsby-node.jsarchivo. Para ver el resultado de los cambios, reinicie el servidor de desarrollo de Gatsby. Esto se hace en la mayoría de los sistemas presionando CTRL+ Cen la terminal y ejecutando npm run devnuevamente.

Familiarizarse con el modelo de contenido

Mire en la /studio/schemas/documentscarpeta. Hay archivos de esquema para nuestros principales tipos de contenido: autor, categoría, configuración del sitio y publicaciones. Cada uno de los archivos exporta un objeto JavaScript que define los campos y propiedades de estos tipos de contenido. Dentro de post.jsestá la definición de campo para categorías:

{  name: 'categories',  type: 'array',  title: 'Categories',  of: [    {      type: 'reference',      to: [{        type: 'category'      }]    }  ]},

Esto creará un campo de matriz con objetos de referencia para documentos de categoría. Dentro del estudio del blog se verá así:

Agregar babosas al tipo de categoría

Dirigirse a /studio/schemas/documents/category.js. Existe un modelo de contenido simple para una categoría que consta de un título y una descripción. Ahora que estamos creando páginas dedicadas a las categorías, sería útil tener también un campo slug. Podemos definir eso en el esquema de esta manera:

// studio/schemas/documents/category.jsexport default {  name: 'category',  type: 'document',  title: 'Category',  fields: [    {      name: 'title',      type: 'string',      title: 'Title'    },    {      name: 'slug',      type: 'slug',      title: 'Slug',      options: {        // add a button to generate slug from the title field        source: 'title'      }    },    {      name: 'description',      type: 'text',      title: 'Description'    }  ]}

Ahora que hemos cambiado el modelo de contenido, también debemos actualizar la definición del esquema GraphQL. Haga esto ejecutando npm run graphql-deploy(alternativamente sanity graphql deploy en la carpeta del estudio. Recibirá advertencias sobre cambios importantes, pero como solo estamos agregando un campo, puede continuar sin preocupaciones. Si desea que se pueda acceder al campo en su estudio en Netlify, verifique los cambios en git (con git add . git commit -m"add slug field") y envíalo a su repositorio de GitHub ( git push origin master).

Ahora deberíamos revisar las categorías y generar slugs para ellas. ¡Recuerde presionar el botón público para que los cambios sean accesibles para Gatsby! Y si estaba ejecutando el servidor de desarrollo de Gatsby, también deberá reiniciarlo.

Nota breve sobre cómo funciona el complemento fuente Sanity

Al iniciar Gatsby en el desarrollo o la creación de un sitio web, el complemento fuente primero buscará las definiciones de esquema GraphQL de la API GraphQL implementada por Sanity. El complemento fuente usa esto para decirle a Gatsby qué campos deben estar disponibles para evitar que se rompa si el contenido de ciertos campos desaparece. Luego llegará al punto final de exportación del proyecto, que transmite todos los documentos accesibles al almacén de datos en memoria de Gatsby.

En otras palabras, todo el sitio se construye con dos solicitudes. Al ejecutar el servidor de desarrollo, también se configurará un oyente que envíe cualquier cambio proveniente de Sanity a Gatsby en tiempo real, sin realizar consultas API adicionales. Si le damos al complemento fuente un token con permiso para leer borradores, veremos los cambios al instante. Esto también se puede experimentar con Gatsby Preview.

Agregar una plantilla de página de categoría en Gatsby

Ahora que tenemos la definición del esquema GraphQL y algo de contenido listo, podemos sumergirnos en la creación de plantillas de páginas de categorías en Gatsby. Necesitamos hacer dos cosas:

• Dígale a Gatsby que cree páginas para los nodos de categoría (ese es el término de Gatsby para “documentos”).
• Dale a Gatsby un archivo de plantilla para generar el HTML con los datos de la página.

Comience abriendo el /web/gatsby-node.jsarchivo. El código ya estará aquí y podrá usarse para crear las páginas de publicaciones del blog. Aprovecharemos en gran medida este código exacto, pero para categorías. Veámoslo paso a paso:

Entre la createBlogPostPagesfunción y la línea que comienza con exports.createPages, podemos agregar el siguiente código. He publicado comentarios aquí para explicar lo que está pasando:

// web/gatsby-node.js// ...async function createCategoryPages (graphql, actions) {  // Get Gatsby‘s method for creating new pages  const {createPage} = actions  // Query Gatsby‘s GraphAPI for all the categories that come from Sanity  // You can query this API on http://localhost:8000/___graphql  const result = await graphql(`{    allSanityCategory {      nodes {        slug {          current        }        id      }    }  }  `)  // If there are any errors in the query, cancel the build and tell us  if (result.errors) throw result.errors  // Let‘s gracefully handle if allSanityCatgogy is null  const categoryNodes = (result.data.allSanityCategory || {}).nodes || []  categoryNodes    // Loop through the category nodes, but don't return anything    .forEach((node) = {      // Desctructure the id and slug fields for each category      const {id, slug = {}} = node      // If there isn't a slug, we want to do nothing      if (!slug) return      // Make the URL with the current slug      const path = `/categories/${slug.current}`      // Create the page using the URL path and the template file, and pass down the id      // that we can use to query for the right category in the template file      createPage({        path,        component: require.resolve('./src/templates/category.js'),        context: {id}      })    })}

Por último, esta función es necesaria al final del archivo:

// /web/gatsby-node.js// ...exports.createPages = async ({graphql, actions}) = {  await createBlogPostPages(graphql, actions)  await createCategoryPages(graphql, actions) // = add the function here} 

Ahora que tenemos la maquinaria para crear el nodo de la página de categorías, necesitamos agregar una plantilla sobre cómo debería verse realmente en el navegador. Lo basaremos en la plantilla de publicación de blog existente para obtener un estilo consistente, pero lo mantendremos bastante simple en el proceso.

// /web/src/templates/category.jsimport React from 'react'import {graphql} from 'gatsby'import Container from '../components/container'import GraphQLErrorList from '../components/graphql-error-list'import SEO from '../components/seo'import Layout from '../containers/layout'export const query = graphql`  query CategoryTemplateQuery($id: String!) {    category: sanityCategory(id: {eq: $id}) {      title      description    }  }`const CategoryPostTemplate = props = {  const {data = {}, errors} = props  const {title, description} = data.category || {}  return (    Layout      Container        {errors  GraphQLErrorList errors={errors} /}        {!data.category  pNo category data/p}        SEO title={title} description={description} /        article          h1Category: {title}/h1          p{description}/p        /article      /Container    /Layout  )}export default CategoryPostTemplate

Estamos utilizando el ID que se pasó al contexto para gatsby-node.jsconsultar el contenido de la categoría. Luego lo usamos para consultar los campos titley descriptionque están en el tipo de categoría. Asegúrese de reiniciar npm run devdespués de guardar estos cambios y diríjase localhost:8000/categories/structured-contental navegador. La página debería verse así:

¡Cosas interesantes! Pero sería aún mejor si pudiéramos ver qué publicaciones pertenecen a esta categoría, porque, bueno, ese es el punto de tener categorías en primer lugar, ¿verdad? Idealmente, deberíamos poder consultar un campo de “páginas” en el objeto de categoría.

Antes de aprender cómo hacerlo, debemos dar un paso atrás para comprender cómo funcionan las referencias de Sanity.

Consultando las referencias de Sanity

Aunque solo definimos las referencias en un tipo, el almacén de datos de Sanity las indexará “bidireccionalmente”. Eso significa que crear una referencia al documento de categoría “Contenido estructurado” a partir de una publicación le permite a Sanity saber que la categoría tiene estas referencias entrantes y evitará que la eliminación mientras la referencia exista (las referencias se pueden configurar como “débiles” para anularlas). este comportamiento). Si usamos GROQ, podemos consultar categorías y unir publicaciones que las tengan así ( ver la consulta y el resultado en acción en groq.dev ):

*[_type == "category"]{  _id,  _type,  title,  "posts": *[_type == "post"  references(^._id)]{    title,    slug  }}// alternative: *[_type == "post"  ^._id in categories[]._ref]{

Esto genera una estructura de datos que nos permite crear una plantilla de publicación de categoría simple:

[  {    "_id": "39d2ca7f-4862-4ab2-b902-0bf10f1d4c34",    "_type": "category",    "title": "Structured content",    "posts": [      {        "title": "Exploration powered by structured content",        "slug": {          "_type": "slug",          "current": "exploration-powered-by-structured-content"        }      },      {        "title": "My brand new blog powered by Sanity.io",        "slug": {          "_type": "slug",          "current": "my-brand-new-blog-powered-by-sanity-io"        }      }    ]  },  // ... more entries]

Eso está bien para GROQ, ¿qué pasa con GraphQL?

Aquí está el truco: hasta el momento, este tipo de consulta no es posible con la API GraphQL de Gatsby lista para usar. ¡Pero no temas! Gatsby tiene una API poderosa para cambiar su esquema GraphQL que nos permite agregar campos.

Uso createResolverspara editar la API GraphQL de Gatsby

Gatsby mantiene todo el contenido en la memoria cuando crea su sitio y expone algunas API que nos permiten aprovechar cómo procesar esta información. Entre ellas se encuentran las API de Node. Probablemente sea bueno aclarar que cuando hablamos de “nodo” en Gatsby, no debe confundirse con Node.js. Los creadores de Gatsby tomaron prestados “bordes y nodos” de la teoría de gráficos, donde los “bordes” son las conexiones entre los “nodos”, que son los “puntos” donde se ubica el contenido real. Dado que un borde es una conexión entre nodos, puede tener una propiedad “siguiente” y “anterior”.

Las API de Node son utilizadas principalmente por complementos, pero también se pueden usar para personalizar cómo debería funcionar nuestra API GraphQL. Una de estas API se llama createResolvers. Es bastante nuevo y nos permite aprovechar cómo se crean los nodos de un tipo para que podamos realizar consultas que les agreguen datos.

Usémoslo para agregar la siguiente lógica:

• Busque los que tengan el SanityCategorytipo al crear los nodos.
• Si un nodo coincide con este tipo, cree un nuevo campo llamado postsy configúrelo en el SanityPosttipo.
• Luego ejecute una consulta que filtre todas las publicaciones que tengan una categoría que coincida con el ID de la categoría actual.
• Si hay ID coincidentes, agregue el contenido de los nodos de publicación a este campo.

Agregue el siguiente código al /web/gatsby-node.jsarchivo, ya sea debajo o encima del código que ya está allí:

// /web/gatsby-node.js// Notice the capitalized type namesexports.createResolvers = ({createResolvers}) = {  const resolvers = {    SanityCategory: {      posts: {        type: ['SanityPost'],        resolve (source, args, context, info) {          return context.nodeModel.runQuery({            type: 'SanityPost',            query: {              filter: {                categories: {                  elemMatch: {                    _id: {                      eq: source._id                    }                  }                }              }            }          })        }      }    }  }  createResolvers(resolvers)}

Ahora reiniciemos el servidor de desarrollo de Gatsby. Deberíamos poder encontrar un nuevo campo para publicaciones dentro de los tipos sanityCategoryy allSanityCategory.

Agregar la lista de publicaciones a la plantilla de categoría

Ahora que tenemos los datos que necesitamos, podemos regresar a nuestra plantilla de página de categoría ( /web/src/templates/category.js) y agregar una lista con enlaces a las publicaciones que pertenecen a la categoría.

// /web/src/templates/category.jsimport React from 'react'import {graphql, Link} from 'gatsby'import Container from '../components/container'import GraphQLErrorList from '../components/graphql-error-list'import SEO from '../components/seo'import Layout from '../containers/layout'// Import a function to build the blog URLimport {getBlogUrl} from '../lib/helpers'// Add “posts” to the GraphQL queryexport const query = graphql`  query CategoryTemplateQuery($id: String!) {    category: sanityCategory(id: {eq: $id}) {      title      description      posts {        _id        title        publishedAt        slug {          current        }      }    }  }`const CategoryPostTemplate = props = {  const {data = {}, errors} = props  // Destructure the new posts property from props  const {title, description, posts} = data.category || {}  return (    Layout      Container        {errors  GraphQLErrorList errors={errors} /}        {!data.category  pNo category data/p}        SEO title={title} description={description} /        article          h1Category: {title}/h1          p{description}/p          {/*            If there are any posts, add the heading,            with the list of links to the posts          */}          {posts  (            React.Fragment              h2Posts/h2              ul                { posts.map(post = (                  li key={post._id}                    Link to={getBlogUrl(post.publishedAt, post.slug)}{post.title}/Link                  /li))                }              /ul            /React.Fragment)          }        /article      /Container    /Layout  )}export default CategoryPostTemplate

Este código producirá esta página de categorías simple con una lista de publicaciones vinculadas, ¡tal como queríamos!

¡Vaya a crear páginas de taxonomía!

Acabamos de completar el proceso de creación de nuevos tipos de páginas con plantillas de páginas personalizadas en Gatsby. Cubrimos una de las API de nodo de Gatsby llamada createResolvery la usamos para agregar un nuevo postscampo a los nodos de categoría.

¡Esto debería brindarle lo que necesita para crear otros tipos de páginas de taxonomía! ¿Tienes varios autores en tu blog? Bueno, puedes usar la misma lógica para crear páginas de autor. Lo interesante del filtro GraphQL es que puedes usarlo para ir más allá de la relación explícita que se hace con las referencias. También se puede utilizar para hacer coincidir otros campos mediante expresiones regulares o comparaciones de cadenas. ¡Es bastante flexible!