Cree un sitio mínimo en Next.js con Oracle Content Management sin cabecera

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.

Para consumir nuestro contenido de Oracle Content Management en una aplicación Next.js, podemos utilizar el ejemplo mínimo Next.js disponible como repositorio de código abierto en GitHub.

En este tutorial, crearemos un sitio mínimo sencillo en Next.js aprovechando Oracle Content Management como un CMS sin cabecera, así como su kit de desarrollo de software (SDK) para la entrega de contenido en JavaScript. Este ejemplo Next.js está disponible en GitHub.

El tutorial consta de tres tareas:

1. Preparación de Oracle Content Management
2. Crear el sitio mínimo en Next.js
3. Preparar la aplicación para su despliegue

Requisitos

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

• conceptos clave
• Repositorios de activos

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

Con Next.js mínimos, puede recuperar fácilmente imágenes y otro contenido del repositorio de Oracle Content Management.

Para ver lo que estamos creando, aquí se muestra el estado final de nuestro tutorial, un sitio mínimo básico Next.js que consume contenido de Oracle Content Management:

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

Esto es el aspecto que tendrá la página inicial al final de este tutorial:

Este es el aspecto que tendrá la página de contacto al final de este tutorial:

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

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. Hay un paquete de activos descargable disponible que rellenará su repositorio vacío con tipos de contenido y contenido asociado.

Para preparar Oracle Content Management:

1. Cree un canal y un repositorio de activos.
2. Importación del Paquete de Activos de Muestras de Oracle Content Management

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:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.

2. 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.

   

3. En la esquina superior derecha, haga clic en Crear para crear un nuevo canal. Asigne un nombre al canal 'OCEMinimalChannel' para este tutorial y mantenga el acceso público. Haga clic en Guardar para crear el canal.

   

4. 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.

   

5. En la esquina superior derecha, haga clic en Crear para crear un nuevo repositorio de activos. Asigne al repositorio de activos el nombre 'OCEMinimalRepository' para que realice este tutorial.

   

6. En el campo Canales de publicación, seleccione el canal OCEMinimalChannel para indicar a Oracle Content Management que el contenido del repositorio OCEMinimalRepository se puede publicar en el canal OCEMinimalChannel. Haga clic en Guardar cuando haya terminado.

   

Creación de un modelo de contenido

La siguiente tarea es crear un modelo de contenido. Puede utilizar uno de los siguientes métodos:

• Método 1: Importación del paquete de activos de muestras de Oracle Content Management
• Método 2: Crear su propio modelo de contenido

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. Si lo prefiere, también puede crear su propio modelo de contenido en lugar de descargar el paquete de activos de ejemplo.

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. Si desea importar el paquete de activos de muestras de Oracle Content Management, puede descargar el archivo de paquete de activos, OCESamplesAssetPack.zip, y extraerlo a un directorio de su elección:

1. 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 OCEMinimal_data.zip.

2. Conéctese a la interfaz web de Oracle Content Management como administrador.

3. 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 OCEMinimalRepository y haga clic en el botón Importar contenido de la barra de acción superior.

   

4. Cargue OCEMinimal_data.zip desde la computadora local a la carpeta Documentos.

   

5. Una vez cargado, seleccione OCEMinimal_data.zip y haga clic en Aceptar para importar el contenido al repositorio de activos.

   

6. Una vez que el contenido se haya importado correctamente, navegue a la página Activos y abra el repositorio OCEMinimalRepository. Verá que todas las imágenes y los elementos de contenido relacionados se han agregado ahora al repositorio de activos.

   

7. 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, OCEGettingStartedChannel.

   

8. Antes de la publicación, debe validar todos los activos. Primero agregue OCEMinimalChannel como canal seleccionado y, a continuación, haga clic en el botón Validar.

   

9. 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).

Después de importar el paquete de activos de muestras de Oracle Content Management, puede iniciar la creación del sitio mínimo en Next.js.

Crear su propio modelo de contenido

En lugar de importar el paquete de activos de muestras de Oracle Content Management, también puede crear su propio modelo de contenido.

Para este tutorial, estamos utilizando un tipo de contenido denominado 'MinimalMain' como tipo de contenido principal para este ejemplo. Este tipo de contenido consta de logotipos de cabecera y pie de página, así como una lista de páginas que se deben incluir en la navegación.

Para crear tipos de contenido para el modelo de contenido:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.
2. Seleccione Contenido en el menú de navegación de la izquierda y, a continuación, seleccione Tipos de activo en la lista de selección de la cabecera de página.
3. Haga clic en Crear en la esquina superior derecha.
4. Elija crear un tipo de contenido (no un tipo de activo digital). Repita esta operación para todos los tipos de contenido necesarios.

Vamos a crear tres tipos de contenido, cada uno con su propio conjunto de campos:

• MinimalMain
• MinimalPage
• MinimalSection

El primer tipo de contenido, MinimalMain, debe tener los siguientes campos:

Nombre Mostrado	Tipo de campo	necesario	Nombre de máquina
headerLogo	Campo de medios de un solo valor		headerLogo
footerLogo	Campo de medios de un solo valor		footerLogo
páginas	Campo de referencia de varios valores		páginas

Esto es lo que debería tener la definición de tipo de contenido MinimalMain:

El segundo tipo de contenido, MinimalPage, debe tener el siguiente campo:

Nombre Mostrado	Tipo de campo	necesario	Nombre de máquina
secciones	Campo de referencia de varios valores		secciones

Este es el aspecto del tipo de contenido MinimalPage:

El tercer y último tipo de contenido, MinimalSection, debe tener los siguientes campos:

Nombre Mostrado	Tipo de campo	necesario	Nombre de máquina
type	Campo de texto de valor único	X	type
encabezado	Campo de texto de valor único		encabezado
body	Campo de texto grande de valor único		body
imagen	Campo de imagen de valor único		imagen
acciones	Campo de contenido embebido de valor único		acciones

Este es el aspecto del tipo de contenido MinimalSection:

Una vez creados los tipos de contenido, puede agregar estos tipos de contenido al repositorio que creó anteriormente, OCEMinimalRepository:

1. Conéctese a la interfaz web de Oracle Content Management como administrador.
2. Navegue hasta OCEMinimalRepository.
3. Edite el repositorio y, en Tipos de activos, especifique los tres tipos de contenido recién creados. Haga clic en el botón Save (Guardar) para guardar los cambios.

Después de agregar los tipos de contenido al repositorio, puede abrir el repositorio OCEMinimalRepository en la página Activos e iniciar la creación de los elementos de contenido para todos los tipos de contenido.

Tarea 2: Creación del sitio mínimo en Next.js

Para consumir nuestro contenido de Oracle Content Management en una aplicación Next.js representada por el servidor, podemos utilizar el ejemplo de sitio mínimo 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 el sitio mínimo en Next.js:

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

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

El ejemplo de sitio mínimo 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-minimal-sample.git
    cd oce-nextjs-minimal-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

Configurar la aplicación Next.js

En este ejemplo de sitio mínimo Next.js, debe 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á lo siguiente:

# 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=ba0efff9c021422cb134c2fd5daf6015

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 OCEMinimalChannel.

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.

El SDK de contenido utiliza un objeto DeliveryClient para especificar el punto final. Puede realizar todas las solicitudes utilizando ese objeto de cliente.

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 funciones para obtener los datos de esta aplicación mínima Next.js.

El método fetchOceMinimalMain() recupera el tipo de contenido MinimalMain con un error de minimalmain.

export async function fetchOceMinimalMain() {
      const data = await getItem('minimalmain', 'fields.headerlogo,fields.footerlogo,fields.pages');
      if (!data.hasError) {
        const { fields } = data;
        const { headerlogo, footerlogo } = fields;
        // Extract the sourceset for the headerImage and footerImage and put it back in the data
        data.headerRenditionURLs = getSourceSet(headerlogo);
        data.footerRenditionURLs = getSourceSet(footerlogo);
      }
      return data;
    }

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;
    }

El método fetchPage() recupera el tipo de contenido MinimalPage mediante el valor de depuración de la página.

export async function fetchPage(pageslug) {
      // Get the page details
      const page = await getItem(pageslug, 'fields.sections');
      return page;
    }

El método getRenditionURLs() recupera las URL de representación de cualquier imagen que se pueda definir en una sección utilizando el ID de esa imagen.

export function getRenditionURLs(identifier) {
      const client = getClient();
      return client.getItem({
        id: identifier,
        expand: 'fields.renditions',
      }).then((asset) => getSourceSet(asset))
        .catch((error) => logError('Fetching Rendition URLs failed', error));
    }

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 del sitio mínima divide cada página en una serie de componentes más pequeños.

Las siguientes secciones incluyen una visión general de cómo Next.js presenta nuestra aplicación en cada uno de nuestros componentes:

• Carpeta de Páginas
• Componente principal
• Componente de Página
• Componentes de cabecera y pie de página
• Componente de sección
• Componente de error

Carpeta de Páginas

En nuestro sitio, ofrecemos una ruta - /page. Las solicitudes se dirigen al componente principal definido en el archivo pages/page/[[..slug]].jsx. La solicitud de ruta raíz se redirige a /page especificando un redireccionamiento en next.config.js.

  async redirects() {
        return [
          {
            source: '/',
            destination: '/page/',
            permanent: true,
          },
        ]
      }

Todas las páginas tienen un encabezado, contienen el logotipo y los enlaces de la compañía, así como un pie de página, con iconos de logotipo y redes sociales. Se accede a las páginas a través de URL estáticas y se obtienen todos los datos necesarios antes de transferir cualquier dato relevante a cualquier componente secundario.

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

Componente principal

Todas las páginas son representadas por el componente principal, ubicado en pages/page/[[..slug]].jsx. Capturar todas las rutas de Next.js se hacen opcionales incluyendo el parámetro entre corchetes dobles ([[...slug]]). La página raíz que toma por defecto la primera página de la lista de páginas no tiene el parámetro transferido y, por lo tanto, definimos el parámetro de desplazamiento para que sea opcional.

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

import { fetchOceMinimalMain, fetchPage, getRenditionURLs } from '../scripts/services';

Las URL de las páginas son URL dinámicas que contienen el separador de página como una ruta; por ejemplo, las rutas de acceso a las URL son

• /page/home
• /page/contact-us
• /page

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 appData = await fetchOceMinimalMain();
      const { fields } = appData;
    
      // Generate the paths we want to pre-render based on posts
      const paths = fields.pages.map((page) => ({
        params: { slug: [page.slug] },
      }));
      // Also add the path for the root /
      paths.push({
        params: { slug: [] },
      });
      return {
        paths,
        fallback: false,
      };
    }

La función getStaticProps() se utiliza para obtener los datos de una única instancia de la página. El separador de página se obtiene del parámetro transferido al método. El separador de página se utiliza para obtener todos los datos necesarios para esta página.

export async function getStaticProps(context) {
      // fetch the minimal main data
      const appData = await fetchOceMinimalMain();
      // find the slug param from the context. If its null, default to the first page slug
      const { params } = context;
      let { slug } = params;
      if (slug == null) {
        slug = appData.fields.pages[0].slug;
      }
      // fetch the page corresponding to the slug
      const pageData = await fetchPage(slug);
      const { headerRenditionURLs, footerRenditionURLs, fields } = appData;
      const { sections } = pageData.fields;
    
      // for each section in the page, if a image is present, get the corresponding rendition urls
      // and insert it back into the section
      const promises = [];
      sections.forEach((section) => {
        // add a promise to the total list of promises to get any section rendition urls
        if (section.fields.image) {
          promises.push(
            getRenditionURLs(section.fields.image.id)
              .then((renditionURLs) => {
                // eslint-disable-next-line no-param-reassign
                section.renditionURLs = renditionURLs;
              }),
          );
        }
      });
    
      // execute all the promises and return all the data
      await Promise.all(promises);
      return {
        props: {
          headerRenditionURLs,
          footerRenditionURLs,
          pages: fields.pages,
          pageData,
        },
      };
    }

Componente de Página

El componente Page es responsable de representar todas las secciones definidas para una página. Abra el componente Page, ubicado en Components/Page.jsx. Simplemente utiliza los datos transferidos desde el componente principal. No obtiene datos adicionales del servidor. Utiliza el componente Section para representar los datos de las secciones.

Page.propTypes = {
      pageData: PropTypes.shape().isRequired,
    };

Componentes de cabecera y pie de página

El componente Header, ubicado en los componentes/Header.jsx y el componente Footer, ubicado en los componentes/Footer.jsx, simplemente utiliza los datos transferidos desde el componente principal. No obtienen datos adicionales del servidor.

Componente de sección

El componente Section, ubicado en Components/Section.jsx, es utilizado por el componente Page y se utiliza para representar cualquier elemento de contenido del tipo MinimalSection.

Este componente tiene datos transferidos desde el componente Página.

Componente de error

Los componentes Página y Principal utilizan el componente Error, situado en los componentes/Error.jsx. Si se produjeron errores durante la llamada al servidor, se los representará.

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:

1. Acceder a un servidor de desarrollo local
2. 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 preemitirá las páginas. Para pre-representar las páginas, consulte la sección siguiente.

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

Cree un sitio mínimo en Next.js con Oracle Content Management sin cabecera

F49323-01

Octubre de 2021

Copyright © 2021, Oracle and/or its affiliates.

Autor Principal: Oracle Corporation