Créez un site minimal dans Next.js avec Oracle Content Management Headless

Introduction

Next.js est une structure Web de développement frontal React open source qui active des fonctionnalités telles que le rendu côté serveur et la génération de sites Web statiques pour les applications Web basées sur React.

Pour utiliser notre contenu Oracle Content Management dans une application Next.js, nous pouvons utiliser l'exemple minimal Next.js disponible en tant que référentiel open source sur GitHub.

Dans ce tutoriel, nous allons créer un site minimal simple dans Next.js en utilisant Oracle Content Management en tant que système de gestion de contenu sans tête, ainsi que son kit de développement logiciel (SDK, Software Development Kit) pour la diffusion de contenu dans JavaScript. Cet exemple Next.js est disponible sur GitHub.

Ce tutoriel se compose de trois tâches :

1. Préparer Oracle Content Management
2. Créez le site minimal dans Next.js
3. Préparer votre application au déploiement

Prérequis

Avant de poursuivre ce tutoriel, nous vous recommandons de lire les informations suivantes en premier :

• Principaux concepts
• Référentiels de ressources

Pour suivre ce tutoriel, vous aurez besoin des éléments suivants :

• un abonnement Oracle Content Management
• un compte Oracle Content Management avec le rôle Administrateur de contenu
• un ordinateur Windows ou Mac avec une version de noeud 10 ou supérieure

Ce que nous construisons

Avec Next.js minimal, vous pouvez facilement extraire des images et d'autres contenus de votre référentiel Oracle Content Management.

Pour voir ce que nous construisons, voici l'état de fin de notre tutoriel, un site élémentaire Next.js minimal qui consomme du contenu d'Oracle Content Management :

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

Voici à quoi ressemblera la page d'accueil à la fin de ce tutoriel :

Voici à quoi ressemblera la page Nous contacter à la fin de ce tutoriel :

Pour continuer, vous devez disposer d'un abonnement actif à Oracle Content Management et être connecté avec le rôle d'administrateur de contenu.

Tâche 1 : Préparer Oracle Content Management

Si vous ne disposez pas encore d'une instance Oracle Content Management, reportez-vous à Démarrage rapide pour apprendre à vous inscrire à Oracle Cloud, à provisionner une instance Oracle Content Management et à configurer Oracle Content Management en tant que système de gestion de contenu sans tête.

Pour ce tutoriel, vous devrez créer un modèle de contenu. Un pack de ressources téléchargeable est disponible pour remplir le référentiel vide avec les types de contenu et le contenu associé.

Pour préparer Oracle Content Management :

1. Créez un canal et un référentiel de ressources.
2. Importer le pack de ressources pour les échantillons Oracle Content Management

Création d'un canal et d'un référentiel de ressources

Vous devez d'abord créer un canal et un référentiel de ressources dans Oracle Content Management afin de pouvoir publier du contenu.

Pour créer un canal et un référentiel de ressources dans Oracle Content Management, procédez comme suit :

1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.

2. Choisissez Contenu dans le menu de navigation de gauche, puis choisissez Publier des canaux dans la liste de sélection de l'en-tête de page.

   

3. Dans l'angle supérieur droit, cliquez sur Créer pour créer un canal. Nommez le canal 'OCEMinimalChannel' dans le cadre de ce tutoriel et conservez l'accès public. Cliquez sur Enregistrer pour créer le canal.

   

4. Choisissez Contenu dans le menu de navigation de gauche, puis choisissez Référentiels dans la liste de sélection de l'en-tête de page.

   

5. Dans l'angle supérieur droit, cliquez sur Créer pour créer un référentiel de ressources. Nommez le référentiel de ressources 'OCEMinimalRepository' dans le cadre de ce tutoriel.

   

6. Dans le champ Canaux de publication, sélectionnez le canal OCEMinimalChannel pour indiquer à Oracle Content Management que le contenu du référentiel OCEMinimalRepository peut être publié dans le canal OCEMinimalChannel. Cliquez sur Enregistrer lorsque vous avez terminé.

   

Créer un modèle de contenu

La tâche suivante consiste à créer un modèle de contenu. Vous pouvez utiliser l'une des deux méthodes :

• Méthode 1 : Importer le pack d'échantillons Oracle Content Management
• Méthode 2 : Créer votre propre modèle de contenu

Importer le pack de ressources pour les échantillons Oracle Content Management

Vous pouvez télécharger un pack de ressources échantillon Oracle Content Management préconfiguré contenant tous les types de contenu et ressources requis pour ce tutoriel. Si vous préférez, vous pouvez également créer votre propre modèle de contenu plutôt que de télécharger l'exemple de pack de ressources.

Vous pouvez télécharger une copie du contenu que nous utilisons dans ce tutoriel à partir d'Oracle Content Management Samples Asset Pack. Vous pourrez ainsi tester les types de contenu et les modifier. Si vous souhaitez importer le pack de ressources Oracle Content Management Samples Asset Pack, vous pouvez télécharger l'archive du pack de ressources, OCESamplesAssetPack.zip, puis l'extraire dans le répertoire de votre choix :

1. Téléchargez le pack d'échantillons Oracle Content Management (OCESamplesAssetPack.zip) à partir de la page Téléchargements d'Oracle Content Management. Extrayez le fichier ZIP téléchargé vers un emplacement sur votre ordinateur. Après l'extraction, cet emplacement inclut un fichier nommé OCEMinimal_data.zip.

2. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.

3. Choisissez Contenu dans le menu de navigation de gauche, puis choisissez Référentiels dans la liste de sélection de l'en-tête de page. A présent, sélectionnez OCEMinimalRepository et cliquez sur le bouton Importer le contenu dans la barre d'actions supérieure.

   

4. Téléchargez OCEMinimal_data.zip à partir de votre ordinateur local vers le dossier Documents.

   

5. Une fois téléchargé, sélectionnez OCEMinimal_data.zip et cliquez sur OK pour importer le contenu dans votre référentiel de ressources.

   

6. Une fois le contenu importé, accédez à la page Immobilisations et ouvrez le référentiel OCEMinimalRepository. Vous verrez que toutes les images et éléments de contenu associés ont été ajoutés au référentiel de ressources.

   

7. Cliquez sur Tout sélectionner en haut à gauche, puis sur Publier pour ajouter toutes les ressources importées au canal de publication que vous avez créé précédemment, OCEGettingStartedChannel.

   

8. Avant la publication, vous devez valider toutes les ressources. Ajoutez d'abord OCEMinimalChannel en tant que canal sélectionné, puis cliquez sur le bouton Valider.

   

9. Une fois les ressources validées, vous pouvez publier toutes les ressources sur le canal sélectionné en cliquant sur le bouton Publier dans l'angle supérieur droit.

   

Une fois cette opération effectuée, vous pouvez voir sur la page Immobilisations que toutes les immobilisations ont été publiées. (Cliquez sur l'icône située au-dessus du nom de la ressource.)

Après avoir importé le pack de ressources d'échantillons Oracle Content Management, vous pouvez commencer à créer le site minimal dans Next.js.

Créer votre propre modèle de contenu

Au lieu d'importer le pack d'échantillons Oracle Content Management, vous pouvez également créer votre propre modèle de contenu.

Pour ce tutoriel, nous utilisons un type de contenu appelé 'MinimalMain' comme type de contenu principal pour cet exemple. Ce type de contenu se compose de logos d'en-tête et de pied de page, ainsi que d'une liste de pages à inclure dans la navigation.

Pour créer des types de contenu pour le modèle de contenu :

1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.
2. Choisissez Contenu dans le menu de navigation de gauche, puis choisissez Types d'immobilisation dans la liste de sélection de l'en-tête de page.
3. Cliquez sur Créer dans l'angle supérieur droit.
4. Choisissez de créer un type de contenu (et non un type de ressource numérique). Répétez cette opération pour tous les types de contenu requis.

Nous allons créer trois types de contenu, chacun avec son propre ensemble de champs :

• MinimalMain
• MinimalPage
• MinimalSection

Le premier type de contenu, MinimalMain, doit comporter les champs suivants :

Nom d'affichage	Type de champ	Requis	Nom de machine
headerLogo	Champ de média à valeur unique		headerLogo
footerLogo	Champ de média à valeur unique		footerLogo
pages	Champ de référence à valeurs multiples		pages

Voici l'aspect de la définition de type de contenu MinimalMain :

Le second type de contenu, MinimalPage, doit comporter le champ suivant :

Nom d'affichage	Type de champ	Requis	Nom de la machine
sections	Champ de référence à valeurs multiples		sections

Voici l'apparence de votre type de contenu MinimalPage :

Le troisième et dernier type de contenu, MinimalSection, doit comporter les champs suivants :

Nom d'affichage	Type de champ	Requis	Nom de machine
type	Champ de texte à valeur unique	X	type
en-tête	Champ de texte à valeur unique		en-tête
body	Champ de texte de grande valeur		body
image	Champ d'image à valeur unique		image
actions	Champ de contenu intégré à valeur unique		actions

Voici l'apparence de votre type de contenu MinimalSection :

Une fois les types de contenu créés, vous pouvez les ajouter au référentiel que vous avez créé précédemment, OCEMinimalRepository :

1. Connectez-vous à l'interface Web d'Oracle Content Management en tant qu'administrateur.
2. Accédez à OCEMinimalRepository.
3. Modifiez le référentiel et, sous Types d'immobilisation, indiquez les trois nouveaux types de contenu. Cliquez sur le bouton Enregistrer pour enregistrer vos modifications.

Après avoir ajouté les types de contenu au référentiel, vous pouvez ouvrir le référentiel OCEMinimalRepository sur la page Ressources et commencer à créer vos éléments de contenu pour tous les types de contenu.

Tâche 2 : construction du site minimal dans Next.js

Pour utiliser notre contenu Oracle Content Management dans une application Next.js côté serveur, nous pouvons utiliser l'exemple de site minimal Next.js, disponible en tant que référentiel open source sur GitHub.

Remarque : n'oubliez pas que l'utilisation de l'exemple Next.js est facultative et que nous l'utilisons dans ce tutoriel pour vous lancer rapidement. Vous pouvez également créer votre propre application Next.js.

Pour créer le site minimal dans Next.js :

1. Cloner l'exemple de référentiel et installer les dépendances
2. Configurer l'application Next.js
3. Utiliser le kit SDK Oracle Content Management Content
4. Utiliser le kit SDK de contenu pour extraire du contenu

Cloner l'exemple de référentiel et installer les dépendances

L'exemple de site minimal Next.js est disponible en tant que référentiel open source sur GitHub.

Vous devez d'abord cloner l'exemple à partir de GitHub sur votre ordinateur local et modifier votre répertoire en racine de référentiel :

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

Maintenant que vous disposez de votre base de code, vous devez télécharger les dépendances pour l'application. Exécutez la commande suivante à partir du répertoire racine :

npm install

Configurer l'application Next.js

Dans cet exemple de site minimal Next.js, vous devez configurer quelques informations afin que votre kit SDK Oracle Content Management Content (et toute autre demande) puisse cibler l'URL d'instance et la version d'API correctes avec le jeton de canal approprié. Ces valeurs sont utilisées dans scripts/server-config-utils.js pour instancier un nouveau client de livraison.

Cette application utilise un fichier .env.local qui est lu par Next.js et mis à la disposition du code dans l'application avec process.env.

Ouvrez le fichier .env.local dans un éditeur de texte. Vous verrez ce qui suit :

# 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

Modifiez chaque paire clé-valeur pour refléter l'URL de votre instance, la version d'API à cibler et le jeton de canal associé à votre canal de publication. Le canal de ce tutoriel est OCEMinimalChannel.

Utiliser le kit SDK Oracle Content Management Content

Oracle Content Management propose un kit SDK pour vous aider à repérer et à utiliser du contenu dans vos applications. Le kit SDK est publié en tant que module NPM et le projet est hébergé sur GitHub.

En savoir plus sur le kit SDK ici.

Le kit SDK a été enregistré en tant que dépendance d'exécution de ce projet dans le fichier package.json.

Utiliser le kit SDK de contenu pour extraire du contenu

Nous pouvons désormais exploiter le kit SDK de contenu pour extraire du contenu afin de le rendre dans notre application Next.js.

Le kit SDK de contenu utilise un objet DeliveryClient pour indiquer l'adresse. Vous pouvez effectuer toutes les demandes à l'aide de cet objet client.

Le dossier de scripts contient le code permettant d'obtenir des données à partir d'Oracle Content Management à l'aide du kit SDK de contenu.

Le fichier scripts/server-config-utils.js importe le kit SDK Content, puis crée un client de distribution à l'aide de la configuration indiquée dans .env.local.

La commande suivante importe le kit SDK :

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

La commande suivante crée le client de livraison :

return createDeliveryClient(serverconfig);

Le fichier scripts/services.js contient des fonctions permettant d'obtenir les données pour cette application Next.js minimale.

La méthode fetchOceMinimalMain() extrait le type de contenu MinimalMain avec un slug de minimummain.

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

Pour le rendu des images, services.js fournit une méthode d'aide pour extraire le jeu de sources d'une ressource construite à partir des rendus de la ressource.

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

La méthode fetchPage() extrait le type de contenu MinimalPage à l'aide de la valeur de slug de la page.

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

La méthode getRenditionURLs() extrait les URL de rendu de toute image pouvant être définie dans une section à l'aide de l'ID de cette image.

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

Maintenant que nous avons nos requêtes de données, nous pouvons afficher les réponses dans nos composants Next.js.

Composants Next.js

Next.js est basé sur React et React utilise une technologie appelée JSX, qui est une extension de syntaxe de type HTML à JavaScript, pour afficher du contenu. Bien que vous puissiez écrire du JavaScript pur pour afficher des données à partir d'Oracle Content Management, nous vous recommandons vivement d'utiliser JSX.

L'application minimale du site décompose chaque page en un certain nombre de composants plus petits.

Les sections suivantes présentent la façon dont Next.js rend notre application dans chacun de nos composants :

• Dossier des pages
• Composant principal
• Composant de page
• Composants d'en-tête et de bas de page
• Composant de section
• Composant d'erreur

Dossier des pages

Dans notre site, nous fournissons une route - /page. Les demandes sont dirigées vers le composant principal défini dans le fichier pages/page/[[..slug]].jsx. La demande de chemin racine est redirigée vers /page en spécifiant un réacheminement dans next.config.js.

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

Toutes les pages comportent un en-tête contenant le logo et les liens de la société, ainsi qu'un pied de page contenant un logo et des icônes de médias sociaux. Les pages sont accessibles via des URL statiques et obtiennent toutes les données nécessaires avant de transmettre les données pertinentes à n'importe quel composant enfant.

Next.js traite n'importe quelle page du répertoire de pages comme une route pour l'application.

Composant principal

Toutes les pages sont affichées par le composant principal, situé dans pages/page/[[..slug]].jsx. Pour rendre toutes les routes dans Next.js facultatives, incluez le paramètre entre guillemets doubles ([[...slug]]). Le paramètre de la page racine qui est par défaut la première page de la liste des pages ne lui est pas transmis et nous définissons donc le paramètre slug comme facultatif.

Le composant importe l'API pour obtenir des données à partir du fichier services.js.

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

Les URL des pages sont des URL dynamiques contenant le slug de page en tant que chemin, par exemple les chemins d'URL

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

Lorsque Next.js utilise la génération de site statique pour les pages avec des URL dynamiques, il appelle getStaticPaths() pour obtenir tous les chemins de cette page.

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 fonction getStaticProps() est utilisée pour obtenir les données d'une instance unique de la page. Le slug de page est obtenu à partir du paramètre transmis dans la méthode. La diapositive de page est ensuite utilisée pour obtenir toutes les données requises pour cette page.

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

Composant de page

Le composant Page est chargé d'afficher toutes les sections définies pour une page. Ouvrez le composant Page, situé dans Components/Page.jsx. Il utilise simplement les données qui lui sont transmises à partir du composant principal. Il n'obtient aucune donnée supplémentaire du serveur. Il utilise le composant Section pour afficher les données de section.

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

Composants d'en-tête et de bas de page

Le composant Header, situé dans les composants/Header.jsx et le composant Footer, situé dans les composants/Footer.jsx, utilise simplement les données qui leur sont transmises à partir du composant principal. Ils n'obtiennent aucune donnée supplémentaire du serveur.

Composant de section

Le composant Section, situé dans les composants/Section.jsx, est utilisé par le composant Page et permet d'afficher tous les éléments de contenu du type MinimalSection.

Des données sont transmises à ce composant à partir du composant Page.

Composant d'erreur

Le composant Error, situé dans les composants/Error.jsx, est utilisé par les composants Page et Main. Si des erreurs se sont produites pendant l'appel au serveur, il les affiche.

Tâche 3 : Préparer votre application pour le déploiement

Maintenant que nous avons créé notre site de blog Next.js, nous devons le voir sur un serveur de développement local afin que nous puissions déboguer tous les problèmes et prévisualiser l'application avant son déploiement.

Préparez l'application pour le déploiement en deux étapes :

1. Lancement d'un serveur de développement local
2. Utiliser des scripts pour créer et exécuter l'application en cours de développement et de production

Faire fonctionner un serveur de développement local

Vous pouvez démarrer un serveur de développement localement en exécutant la commande suivante.

npm run dev

Ouvrez ensuite votre navigateur sur http://localhost:3000 pour voir votre site en action.

Remarque : les pages ne sont pas prérendues. Pour prédéfinir les pages, reportez-vous à la section suivante.

Utilisation de scripts pour créer et exécuter l'application en cours de développement et de production

Pour la production, le script de création est utilisé pour générer le site de manière statique.

npm run build

Le script de démarrage permet de démarrer un serveur Node.js traitant les pages générées de manière statique.

npm run start

---

Informations relatives au titre et au copyright

Créez un site minimal dans Next.js avec Oracle Content Management Headless

F49319-01

Octobre 2021

Copyright © 2021, Oracle and/or its affiliates.

Auteur principal : Oracle Corporation