Creación de una galería de imágenes en Next.js con Oracle Content Management desacoplado

Introducción

Next.js es un marco web de desarrollo de front-end de React de código abierto que permite funciones como la representación del servidor y la generación de sitios web estáticos para aplicaciones web basadas en React.

En este tutorial se mostrarán los pasos básicos para crear un visor de imágenes con Next.js, con Oracle Content Management como sistema de gestión de contenido y su SDK de contenido. Verá cómo se pueden utilizar las taxonomías para categorizar el contenido y cómo se pueden utilizar las diferentes representaciones de activos digitales en varios casos de uso. Este ejemplo Next.js está disponible en GitHub.

El tutorial consta de tres tareas:

Preparación de Oracle Content Management
Crear la galería de imágenes en Next.js
Preparar la aplicación para su despliegue

Requisitos

Antes de continuar con este tutorial, le recomendamos que lea primero la siguiente información:

Para seguir este tutorial, necesitará:

una suscripción a Oracle Content Management
Una cuenta de Oracle Content Management con el rol de administrador de contenido
un equipo Windows o Mac con la versión 10 del nodo o superior

Lo que estamos construyendo

Nuestra galería de imágenes constará de varias páginas de imágenes de alimentos y bebidas disponibles en una cafetería.

Esta imagen muestra una galería de imágenes con diferentes tipos de bagels, algunos con crema o ingredientes, o ambos.

Para ver lo que estamos creando, aquí está el estado final de nuestro tutorial, una versión en directo de este sitio de galería de imágenes:

https://headless.mycontentdemo.com/samples/oce-nextjs-gallery-sample

Las categorías son nodos secundarios de una taxonomía y se pueden organizar en jerarquías. Para nuestra galería de imágenes, queremos mostrar todas las categorías disponibles independientemente de la organización. Para ello, primero tenemos que encontrar las taxonomías disponibles, que utilizamos el método getTaxonomies() del SDK de contenido.

Nota: La implantación de getTaxonomies utiliza el recurso de API de REST GET /published/api/v1.1/taxonomies.

A continuación, tenemos que obtener el conjunto de categorías para cada una de las taxonomías. Esto se realiza mediante el método queryTaxonomyCategories() del SDK de contenido.

Nota: La implantación de queryTaxonomyCategories utiliza la API de REST GET /published/api/v1.1/taxonomies/{id}/categories.

Para construir la vista previa de una categoría, como Bagels, necesitamos obtener un recuento del número de imágenes y las URL de las cuatro primeras imágenes.

Esta imagen muestra imágenes en la categoría Bagels.

Nuestra solicitud para buscar los activos publicados en la categoría especifica los criterios de la categoría mediante una cadena de consulta, de la siguiente forma:

"(taxonomies.categories.nodes.id eq 892CD6BC4F654249A00CB7942EE8C773)"

Para optimizar la carga de imágenes, utilizaremos una representación de la imagen denominada 'Miniatura'. Consulte retrieveThumbnailURL(), en scripts/services.js, para conocer el código que examina el juego de representaciones disponibles para cada imagen.

Nota: Además de publicar los activos digitales que queremos ver, también debe publicar las taxonomías en el canal.

Para continuar, deberá tener una suscripción activa a Oracle Content Management y conectarse con el rol de administrador de contenido.

Tarea 1: Preparación de Oracle Content Management

Este tutorial se basa en la suposición de que ha creado el repositorio de activos y que actualmente tiene un modelo de contenido vacío (es decir, no se han creado tipos de contenido).

Si aún no tiene una instancia de Oracle Content Management, consulte Inicio rápido para obtener información sobre cómo registrarse en Oracle Cloud, aprovisionar una instancia de Oracle Content Management y configurar Oracle Content Management como CMS sin cabecera.

Para este tutorial, necesitará crear un modelo de contenido de dos formas. Hay un paquete de activos descargable disponible que llenará su repositorio vacío con tipos de contenido y contenido asociado, o puede crear su propio contenido y modelo de contenido.

Para preparar Oracle Content Management:

Cree un canal y un repositorio de activos.
Importación del Paquete de Activos de Muestras de Oracle Content Management
Cargar sus propios activos de imagen
Crear taxonomías y enlazarlas a activos de imagen

Crear un canal y un repositorio de activos

Primero debe crear un canal y un repositorio de activos en Oracle Content Management para poder publicar contenido.

Para crear un canal y un repositorio de activos en Oracle Content Management:

Conéctese a la interfaz web de Oracle Content Management como administrador.
Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Publicar canales en la lista de selección de la cabecera de página.
En la esquina superior derecha, haga clic en Crear para crear un nuevo canal. Asigne un nombre al canal 'OCEImageGalleryChannel' para este tutorial y mantenga el acceso público. Haga clic en Guardar para crear el canal.
Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Repositorios en la lista de selección de la cabecera de página.
En la esquina superior derecha, haga clic en Crear para crear un nuevo repositorio de activos. Asigne al repositorio de activos el nombre 'OCEImageGalleryRepository' para que realice este tutorial.
En el campo Canales de publicación, seleccione OCEImageGalleryChannel para indicar a Oracle Content Management que el contenido del repositorio OCEImageGalleryRepository se puede publicar en el canal OCEImageGalleryChannel. Haga clic en Guardar cuando haya terminado.

Importación del Paquete de Activos de Muestras de Oracle Content Management

Puede descargar un paquete de activos de ejemplo de Oracle Content Management preconfigurado que contiene todos los tipos de contenido y activos necesarios para este tutorial.

Puede cargar una copia del contenido que estamos utilizando en este tutorial desde el paquete de activos de muestras de Oracle Content Management. Esto le permitirá experimentar con los tipos de contenido y modificar el contenido. Puede descargar el archivo de paquete de activos, OCESamplesAssetPack.zip, y extraerlo a un directorio de su elección:

Descargue el paquete de activos de muestras de Oracle Content Management (OCESamplesAssetPack.zip) desde la página descargas de Oracle Content Management. Extraiga el archivo zip descargado en una ubicación de la computadora. Después de la extracción, esta ubicación incluirá un archivo denominado OCEImageG Gallery_data.zip.
Conéctese a la interfaz web de Oracle Content Management como administrador.
Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Repositorios en la lista de selección de la cabecera de página. Ahora seleccione OCEImageGalleryRepository y haga clic en el botón Importar contenido de la barra de acción superior.
Cargue OCEImageG Gallery_data.zip desde la computadora local a la carpeta Documentos.
Una vez cargado, seleccione OCEImageG Gallery_data.zip y haga clic en Aceptar para importar el contenido al repositorio de activos.
Una vez que el contenido se haya importado correctamente, navegue a la página Activos y abra el repositorio OCEImageGalleryRepository. Verá que todas las imágenes y los elementos de contenido relacionados se han agregado ahora al repositorio de activos.
Haga clic en Seleccionar todo en la parte superior izquierda y, a continuación, en Publicar para agregar todos los activos importados al canal de publicación que ha creado anteriormente, OCEImageGalleryChannel.
Antes de la publicación, debe validar todos los activos. Primero agregue OCEImageGalleryChannel como canal seleccionado y, a continuación, haga clic en el botón Validar.
Después de validar los activos, puede publicar todos los activos en el canal seleccionado haciendo clic en el botón Publicar en la esquina superior derecha.

Cuando termine, puede ver en la página Activos que se han publicado todos los activos. (Puede indicar el icono encima del nombre del activo).

En esta imagen se muestra la página Activos, con todos los activos ubicados.

Después de importar el paquete de activos de muestras de Oracle Content Management, puede iniciar la creación de la galería de imágenes en Next.js.

Cargar sus propios activos de imagen

Para este tutorial, estamos utilizando un repositorio de activos denominado 'OCEImageGalleryRepository' para crear la página inicial para nuestro sitio de galería. Esta página inicial incluye el título 'Galería de imágenes' y álbumes de recopilación de imágenes que tienen activos de imagen dentro.

Esta imagen muestra la página de inicio de la galería de imágenes, con imágenes de varias categorías de imágenes: sándwiches, bebidas, postre, desayuno y comida.

Para agregar activos de imagen al repositorio de activos de galería:

Conéctese a la interfaz web de Oracle Content Management.
Haga clic en Activos en el menú de navegación de la izquierda.
Abra el repositorio OCEImageGalleryRepository.
Haga clic en Agregar en la esquina superior derecha de la página para agregar activos de imagen al repositorio de activos de galería.
Cargue sus propios activos nuevos desde su computadora local o elija los activos existentes que ya estén en Oracle Content Management.

Crear taxonomías y enlazarlas a activos de imagen

Debe crear una taxonomía en Oracle Content Management y, a continuación, asignar categorías a los activos del repositorio.

Para crear una taxonomía en Oracle Content Management:

Conéctese a la interfaz web de Oracle Content Management como administrador.
Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Taxonomías en la lista de selección de la cabecera de página.
En la esquina superior derecha, haga clic en Crear para crear una nueva taxonomía. Asigne un nombre al canal 'OCEImageGalleryTaxonomy' para este tutorial.
Haga clic en Crear.
Ahora, agregue categorías para crear la taxonomía. Haga clic en Agregar una categoría.
Asigne un nombre al elemento de categoría principal 'Alimento' y agregue las siguientes categorías secundarias:
- Desayuno
- Postre
- Bebidas
- Sándwiches
Haga clic en Listo en la parte superior derecha de la pantalla.
En la página Taxonomías, seleccione la taxonomía OCEImageGalleryTaxonomy y haga clic en Promocionar en la barra de acciones para que esté disponible para su uso en los repositorios de activos.

A continuación, edite el repositorio OCEImageGalleryRepository para activar la taxonomía OCEImageGalleryTaxonomy para ese repositorio:

Conéctese a la interfaz web de Oracle Content Management como administrador.
Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Repositorios en la lista de selección de la cabecera de página.
Seleccione y edite el repositorio OCEImageGalleryRepository.
En el campo Taxonomías, seleccione OCEImageGalleryTaxonomy, para que pueda asignar categorías de esa taxonomía a los activos del repositorio OCEImageGalleryRepository.
Haga clic en Guardar.

A continuación, asigne categorías de taxonomía a cada uno de los activos de imagen en el repositorio OCEImageGalleryRepository:

Conéctese a la interfaz web de Oracle Content Management.
Haga clic en Activos en el menú de navegación de la izquierda.
Abra el repositorio OCEImageGalleryRepository.
Seleccione uno o más activos de imagen, haga clic en Más en la barra de acciones y, a continuación, seleccione Categorías en el menú.
En el panel Categorías, haga clic en Agregar categoría. Busque el nombre de la categoría en la barra de búsqueda o seleccione una categoría de la estructura jerárquica de taxonomía y haga clic en Agregar para asignar la categoría seleccionada. Puede asignar varias categorías a un activo.
Cuando haya terminado de asignar taxonomías a todos los activos de imagen, seleccione todos los activos del repositorio y publíquelos en el canal OCEImageGalleryChannel.

Tarea 2: Crear la galería de imágenes en Next.js

Para consumir nuestro contenido de Oracle Content Management en una aplicación Next.js, podemos utilizar el ejemplo de la galería de imágenes Next.js, que está disponible como repositorio de código abierto en GitHub.

Nota: Recuerde que el uso de la muestra Next.js es opcional y lo utilizamos en este tutorial para comenzar rápidamente. También puede crear su propia aplicación Next.js.

Para crear la galería de imágenes en Next.js:

Clonar el repositorio de ejemplo e instalar dependencias
Configurar la aplicación Next.js
Trabajar con el SDK de Oracle Content Management Content
Utilizar el SDK de contenido para recuperar el contenido

Clonación del repositorio de ejemplo e instalación de dependencias

La muestra del blog Next.js está disponible como repositorio de código abierto en GitHub.

Primero debe clonar el ejemplo de GitHub a su equipo local y cambiar el directorio a la raíz del repositorio:

git clone https://github.com/oracle/oce-nextjs-gallery-sample.git
    cd oce-nextjs-gallery-sample

Ahora que tiene su base de código, necesita descargar dependencias para la aplicación. Ejecute el siguiente comando desde el directorio raíz:

npm install

Configuración de la Aplicación Next.js

En este ejemplo de galería de imágenes Next.js, necesita configurar algunos datos para que el SDK de Oracle Content Management Content (y cualquier otra solicitud) pueda dirigir la URL de instancia y la versión de API correctas con el token de canal correcto. Estos valores se utilizan en scripts/server-config-utils.js para instanciar un nuevo cliente de entrega.

Esta aplicación utiliza un archivo .env.local leído por Next.js y puesto a disposición del código dentro de la aplicación con process.env.

Abra el archivo .env.local en un editor de texto. Verá la siguiente información:

# The connection details for the Oracle Content Management server to be used for this application
    SERVER_URL=https://samples.mycontentdemo.com
    API_VERSION=v1.1
    CHANNEL_TOKEN=e0b6421e73454818948de7b1eaddb091

Cambie cada par clave-valor para reflejar su URL de instancia, la versión de API que desea dirigir y el token de canal asociado a su canal de publicación. El canal para este tutorial es OCEImageGalleryChannel.

Trabajar con el SDK de Oracle Content Management Content

Oracle Content Management ofrece un SDK para ayudar a detectar y utilizar contenido en las aplicaciones. El SDK se publica como módulo NPM y el proyecto se aloja en GitHub.

Obtenga más información sobre el SDK aquí.

El SDK se ha registrado como una dependencia de tiempo de ejecución de este proyecto en el archivo package.json.

Utilizar el SDK de contenido para recuperar el contenido

Ahora podemos aprovechar el SDK de contenido para recuperar contenido para poder presentarlo en nuestra aplicación Next.js.

La carpeta de scripts contiene el código para obtener datos de Oracle Content Management mediante el SDK de contenido.

El archivo scripts/server-config-utils.js importa el SDK de contenido y, a continuación, crea un cliente de entrega mediante la configuración especificada en .env.local.

El siguiente comando importa el SDK:

import { createDeliveryClient, createPreviewClient } from '@oracle/content-management-sdk';

El siguiente comando crea el cliente de entrega:

return createDeliveryClient(serverconfig);

El archivo scripts/services.js contiene todo el código para obtener datos para la aplicación. Hay una función principal para cada componente de página de la aplicación para obtener todos los datos de esa página.

Para la representación de imágenes, services.js proporciona un método auxiliar para recuperar el juego de orígenes para un activo que se crea a partir de las representaciones del activo.

function getSourceSet(asset) {
      const urls = {};
      urls.srcset = '';
      urls.jpgSrcset = '';
      if (asset.fields && asset.fields.renditions) {
        asset.fields.renditions.forEach((rendition) => {
          addRendition(urls, rendition, 'jpg');
          addRendition(urls, rendition, 'webp');
        });
      }
      // add the native rendition to the srcset as well
      urls.srcset += `${asset.fields.native.links[0].href} ${asset.fields.metadata.width}w`;
      urls.native = asset.fields.native.links[0].href;
      urls.width = asset.fields.metadata.width;
      urls.height = asset.fields.metadata.height;
      return urls;
    }

Datos de página inicial

La página inicial necesita varias llamadas de datos para obtener todos sus datos:

En primer lugar, cargamos las taxonomías para el canal especificado en .env.
Para cada una de las taxonomías, obtenemos todas las categorías de esa taxonomía.
Para cada categoría, se obtienen cuatro elementos de contenido en esa categoría.
Para cada uno de esos elementos, recibimos sus URL de representación.

Abra src/scripts/services.js y busque la función getHomePageData(), que se utiliza para obtener todos los datos de la página inicial.

export function getHomePageData() {
      const deliveryClient = getClient();
      // get the categories for all taxonomies then add all the category items to each category
      return fetchAllTaxonomiesCategories(deliveryClient).then(
        (initialCategories) => addItemsToCategories(deliveryClient, initialCategories).then(
          (categories) => {
            // pull out all of the items for all of the categories then
            // append the computed renditionUrls to each item.
            const allItems = categories.map((category) => category.items);
            const items = flattenArray(allItems);
            // for each item, retrieve the rendition urls and add it to the item
            items.forEach((item) => {
              item.renditionUrls = getSourceSet(item);
            });
            return { categories };
          },
        ),
      );
    }

getHomePageData() llama a fetchAllTaxonomiesCategories() para obtener todas las categorías en todas las taxonomías.

export function fetchAllTaxonomiesCategories(client) {
      return client
        .getTaxonomies()
        .then((topLevelItem) => {
          const taxonomyIds = topLevelItem.items.map((taxonomy) => taxonomy.id);
    
          const promises = [];
          // loop over each taxonomy id
          taxonomyIds.forEach((taxonomyId) => {
            // add a promise to the total list of promises to get the categories
            // for the specific taxonomy id
            promises.push(
              fetchCategoriesForTaxonomyId(client, taxonomyId)
                .then((categoriesTopItem) => categoriesTopItem.items),
            );
          });
    
          // execute all the promises returning a single dimension array of all
          // of the categories for all of the taxonomies (note: no taxonomy information)
          // is returned.
          return Promise.all(promises)
            .then((arrayOfCategoryArray) => flattenArray(arrayOfCategoryArray));
        })
        .catch((error) => logError('Fetching taxonomies failed', error));
    }

fetchAllTaxonomiesCategories() llama a fetchCategoriesForTaxonomyId() para obtener todas las categorías en una taxonomía específica.

function fetchCategoriesForTaxonomyId(client, taxonomyId) {
      return client
        .queryTaxonomyCategories({
          id: `${taxonomyId}`,
        })
        .then((topLevelItem) => topLevelItem)
        .catch((error) => logError('Fetching categories for taxonomy failed', error));
    }

A continuación, se llama a la función addItemsToCategories para agregar los cuatro elementos de categoría a cada categoría.

function addItemsToCategories(client, categories) {
      const promises = [];
    
      // loop over each category
      categories.forEach((category) => {
        // add a promise to the total list of promises to get the items
        // for the specific category
        promises.push(
          fetchItemsForCategory(client, category.id, true).then(
            (topLevelItem) => {
              // add the item to the category before returning it
              category.items = topLevelItem.items;
              category.totalResults = topLevelItem.totalResults;
              return {
                ...category,
              };
            },
          ),
        );
      });
    
      // execute all the promises before returning the data
      return Promise.all(promises).then((arrayOfItems) => flattenArray(arrayOfItems));
    }

Por último, se llama a getSourceSet visto anteriormente para obtener las URL de representación para cada elemento.

Datos de página de cuadrícula de imagen

La página de cuadrícula de imagen recibe un ID de categoría y requiere varias llamadas de datos para obtener todos sus datos:

Obtener todos los elementos de la categoría especificada.
Para cada elemento, obtenga sus URL de representación.

Abra src/scripts/services.js y busque la función getImageGridPageData(), que se utiliza para obtener todos los datos de la página de cuadrícula de imagen.

export function getImageGridPageData(categoryId) {
      const client = getClient();
    
      return fetchItemsForCategory(client, categoryId, false).then(
        (topLevelItem) => {
          const { totalResults } = topLevelItem;
          // for each item, retrieve the rendition urls and add it to the item
          topLevelItem.items.forEach((item) => {
            item.renditionUrls = getSourceSet(item);
          });
          return {
            totalResults,
            items: topLevelItem.items,
          };
        },
      );
    }

Llama a fetchItemsForCategory, como la página inicial, pero sin límite, para que se devuelvan todos los elementos, no solo cuatro.

Ahora que tenemos nuestras consultas de datos, podemos presentar las respuestas en nuestros componentes Next.js.

Componentes Next.js

Next.js se basa en React y React utiliza una tecnología conocida como JSX, que es una extensión de sintaxis similar a HTML a JavaScript, para representar contenido. Aunque puede escribir JavaScript puro para representar datos de Oracle Content Management, recomendamos que utilice JSX.

La aplicación de galería de imágenes divide cada página en una serie de componentes más pequeños, algunos de los cuales se utilizan tanto en las páginas iniciales como en las de cuadrícula de imágenes.

En las próximas secciones se ofrece una visión general de cómo Next.js presenta nuestra aplicación en cada uno de nuestros componentes:

Carpeta de Páginas
Componente de índice
Componente de galería
Componente ImageGridPage

Carpeta de Páginas

En nuestro sitio, queremos proporcionar dos rutas:

La página inicial, que muestra una lista de categorías de imágenes
Página de cuadrícula de imagen que muestra todos los elementos para un ID de categoría determinado

Cualquier página del directorio de páginas Next.js tratará como una ruta para la aplicación.

Componente de índice

La página inicial consta de una lista de categorías para una taxonomía, con una vista previa de cuatro elementos en esa categoría. Se representa con el componente Index, ubicado en pages/index.jsx.

El componente importa la API para obtener datos del archivo services.js.

import { getHomePageData } from '../scripts/services';

En getStaticProps(), llamado durante el tiempo de creación, el componente obtiene todos los datos necesarios para representar la página inicial.

export async function getStaticProps() {
      const data = await getHomePageData();
      return {
        props: { data },
      };
    }

Componente de galería

El componente Gallery representa la categoría individual de la lista. Muestra una vista previa de cuatro de los elementos de la categoría.

Se encuentra en src/components/G Gallery.jsx y recibe todos sus datos como propiedades. No obtiene datos adicionales del servidor.

Componente ImageGridPage

El componente Página Cuadrícula de Imagen muestra los elementos de la categoría cuyo ID se transfiere al componente de la URL. Se presenta en el componente ArticleListPage, ubicado en pages/category/[id].jsx.

El componente importa la API para obtener datos del archivo services.js.

import { fetchAllTaxonomiesCategories, getImageGridPageData } from '../../scripts/services';

Las URL de la página Cuadrícula de imagen son URL dinámicas que contienen el ID de categoría y el nombre como ruta; por ejemplo, las rutas URL son

/category/categoryId1-name1
/category/categoryId2-name2
/category/categoryId3-name3

Cuando Next.js utiliza la generación de sitios estáticos para páginas con URL dinámicas, llama a getStaticPaths() para obtener todas las rutas de esa página.

export async function getStaticPaths() {
      const categories = await fetchAllTaxonomiesCategories();
      return {
        paths: categories.map((category) => ({
          params: { id: `${category.id}-${category.name}` },
        })),
        fallback: true,
      };
    }

La función getStaticProps() se utiliza para obtener los datos de una única instancia de la página Cuadrícula de imagen. El ID de categoría y el nombre se obtienen del parámetro transferido al método. El ID de categoría se utiliza para obtener todos los datos necesarios para esta página.

export async function getStaticProps(context) {
      const { params } = context;
    
      const { id } = params;
      const arr = id.split('-');
      const categoryName = arr[1];
      const categoryId = arr[0];
      const data = await getImageGridPageData(categoryId);
      return {
        props: {
          data,
          categoryName,
        },
      };
    }

Tarea 3: Preparación de la aplicación para el despliegue

Ahora que hemos creado nuestro sitio de blog Next.js, tenemos que verlo en un servidor de desarrollo local para que podamos depurar cualquier problema y obtener una vista previa de la aplicación antes de que entre en marcha.

Prepare la aplicación para el despliegue en dos pasos:

Acceder a un servidor de desarrollo local
Utilizar scripts para crear y ejecutar la aplicación en desarrollo y producción

Aceleración de un Servidor de Desarrollo Local

Puede iniciar un servidor de desarrollo localmente ejecutando el siguiente comando.

npm run dev

A continuación, abra el explorador a http://localhost:3000 para ver el sitio en acción.

Nota: Esta acción no pre-representará las páginas, para pre-representar las páginas, consulte la siguiente sección.

Uso de scripts para crear y ejecutar la aplicación en desarrollo y producción

Para producción, el script de creación se utilizaría para generar el sitio de forma estática.

npm run build

El script de inicio se utiliza para iniciar un servidor Node.js que sirve las páginas generadas estáticamente.

npm run start

Título e Información de Copyright

Creación de una galería de imágenes en Next.js con Oracle Content Management desacoplado

F49329-01

Octubre de 2021

Autor Principal: Oracle Corporation