Minimal Site in Next.js mit Headless Oracle Content Management erstellen

Einführung

Next.js ist ein Open-Source-Web-Front-End-Entwicklungs-Framework für React, das Funktionen wie serverseitiges Rendering ermöglicht und statische Websites für React-basierte Webanwendungen generiert.

Um unsere Oracle Content Management-Inhalte in einer Next.js-Anwendung zu verbrauchen, können wir das minimale Next.js-Beispiel als Open-Source-Repository auf GitHub verwenden.

In diesem Tutorial erstellen wir eine einfache minimale Site in Next.js, indem wir Oracle Content Management als Headless CMS sowie sein Software Development Kit (SDK) für die Inhaltsbereitstellung in JavaScript nutzen. Dieses Next.js-Beispiel ist auf GitHub verfügbar.

Das Tutorial besteht aus drei Aufgaben:

1. Oracle Content Management vorbereiten
2. Minimal-Site in Next.js erstellen
3. Vorbereitung der Anwendung auf das Deployment

Voraussetzungen

Bevor Sie mit diesem Tutorial fortfahren, sollten Sie zuerst die folgenden Informationen lesen:

• Wichtige Konzepte
• Asset-Repositorys

Um diesem Tutorial zu folgen, benötigen Sie:

• ein Oracle Content Management-Abonnement
• ein Oracle Content Management-Account mit der Rolle "Content Administrator"
• ein Windows- oder Mac-Computer mit der Knotenversion 10 oder höher

Was wir bauen

Mit dem minimalen Wert von Next.js können Sie Images und andere Inhalte ganz einfach aus dem Oracle Content Management-Repository abrufen.

Im Folgenden finden Sie den Endstatus unseres Tutorials, einer grundlegenden Minimal-Site von Next.js, die Inhalte aus Oracle Content Management verbraucht:

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

Die Homepage sieht am Ende dieses Tutorials aus:

Die Kontaktseite sieht am Ende dieses Tutorials aus:

Um fortzufahren, benötigen Sie ein aktives Abonnement für Oracle Content Management und müssen mit der Rolle "Content Administrator" angemeldet sein.

Aufgabe 1: Oracle Content Management vorbereiten

Wenn noch keine Oracle Content Management-Instanz vorhanden ist, erfahren Sie unter Schnellstart, wie Sie sich für Oracle Cloud registrieren, eine Oracle Content Management-Instanz bereitstellen und Oracle Content Management als Headless CMS konfigurieren.

Für dieses Tutorial müssen Sie ein Contentmodell erstellen. Es ist ein herunterladbares Anlagenpaket verfügbar, das Ihr leeres Repository mit Inhaltstypen und zugehörigen Inhalten ausfüllt.

So bereiten Sie Oracle Content Management vor:

1. Erstellen Sie einen Kanal und ein Asset-Repository.
2. Oracle Content Management Samples Asset Pack importieren

Kanal- und Asset-Repository erstellen

Sie müssen zuerst einen Kanal und ein Asset-Repository in Oracle Content Management erstellen, damit Sie Inhalte veröffentlichen können.

So erstellen Sie einen Kanal und ein Asset-Repository in Oracle Content Management:

1. Melden Sie sich als Administrator bei der Oracle Content Management-Webbenutzeroberfläche an.

2. Wählen Sie im linken Navigationsmenü die Option Inhalt und anschließend Kanäle veröffentlichen aus der Auswahlliste im Seitenheader.

   

3. Klicken Sie in der oberen rechten Ecke auf Erstellen, um einen neuen Kanal zu erstellen. Benennen Sie den Kanal "OCEMinimalChannel" für die Zwecke dieses Tutorials, und behalten Sie den Zugriff öffentlich. Klicken Sie auf Speichern, um den Kanal zu erstellen.

   

4. Wählen Sie Inhalt im linken Navigationsmenü, und wählen Sie Repositorys aus der Auswahlliste im Seitenheader aus.

   

5. Klicken Sie in der oberen rechten Ecke auf Erstellen, um ein neues Asset-Repository zu erstellen. Benennen Sie das Asset-Repository "OCEMinimalRepository" für die Zwecke dieses Tutorials.

   

6. Wählen Sie im Feld Veröffentlichungskanäle den Kanal OCEMinimalChannel aus, um Oracle Content Management anzugeben, dass Inhalte im Repository OCEMinimalRepository im Kanal OCEMinimalChannel veröffentlicht werden können. Klicken Sie abschließend auf Speichern.

   

Contentmodelle erstellen

Als nächste Aufgabe wird ein Contentmodell erstellt. Sie haben zwei Möglichkeiten:

• Methode 1: Oracle Content Management Samples Asset Pack importieren
• Methode 2: Eigenes Contentmodell erstellen

Oracle Content Management Samples Asset Pack importieren

Sie können ein vorkonfiguriertes Oracle Content Management-Beispielassetspaket herunterladen, das alle erforderlichen Inhaltstypen und -assets für dieses Tutorial enthält. Gegebenenfalls können Sie auch ein eigenes Contentmodell erstellen, anstatt das Beispielassetspaket herunterzuladen.

Sie können eine Kopie des Inhalts, den wir in diesem Tutorial verwenden, aus dem Oracle Content Management Samples Asset Pack hochladen. Dadurch können Sie mit den Inhaltstypen experimentieren und den Inhalt ändern. Wenn Sie das Oracle Content Management Samples Asset Pack importieren möchten, können Sie das Assetpack-Archiv, OCESamplesAssetPack.zip, herunterladen und in ein Verzeichnis Ihrer Wahl extrahieren:

1. Laden Sie das Oracle Content Management Samples Asset Pack (OCESamplesAssetPack.zip) von der Seite Downloads von Oracle Content Management herunter. Extrahieren Sie die heruntergeladene ZIP-Datei an einen Speicherort auf Ihrem Computer. Nach der Extraktion enthält dieser Speicherort eine Datei namens OCEMinimal_data.zip.

2. Melden Sie sich als Administrator bei der Oracle Content Management-Webbenutzeroberfläche an.

3. Wählen Sie Inhalt im linken Navigationsmenü, und wählen Sie Repositorys aus der Auswahlliste im Seitenheader aus. Wählen Sie jetzt OCEMinimalRepository, und klicken Sie in der oberen Aktionsleiste auf die Schaltfläche Inhalt importieren.

   

4. Laden Sie OCEMinimal_data.zip von Ihrem lokalen Computer in den Ordner Dokumente hoch.

   

5. Wählen Sie nach dem Hochladen OCEMinimal_data.zip aus, und klicken Sie auf OK, um den Inhalt in das Asset-Repository zu importieren.

   

6. Nachdem der Inhalt erfolgreich importiert wurde, navigieren Sie zur Seite Anlagen, und öffnen Sie das Repository OCEMinimalRepository. Sie sehen, dass alle zugehörigen Bilder und Inhaltselemente jetzt dem Asset-Repository hinzugefügt wurden.

   

7. Klicken Sie oben links auf Alle auswählen und dann auf Veröffentlichen, um alle importierten Assets dem Veröffentlichungskanal hinzuzufügen, den Sie zuvor erstellt haben: OCEGettingStartedChannel.

   

8. Vor der Veröffentlichung müssen Sie alle Anlagen validieren. Fügen Sie zuerst OCEMinimalChannel als ausgewählten Kanal hinzu, und klicken Sie auf die Schaltfläche Validieren.

   

9. Nachdem die Assets validiert wurden, können Sie alle Assets im ausgewählten Kanal veröffentlichen, indem Sie oben rechts auf die Schaltfläche Veröffentlichen klicken.

   

Anschließend können Sie auf der Seite Anlagen sehen, dass alle Assets veröffentlicht wurden. (Sie können das Symbol über dem Assetnamen erkennen.)

Nach dem Import des Oracle Content Management Samples Asset Pack können Sie die minimale Site in Next.js erstellen.

Eigenes Contentmodell erstellen

Anstatt das Oracle Content Management Samples Asset Pack zu importieren, können Sie auch Ihr eigenes Contentmodell erstellen.

Für dieses Tutorial wird der Inhaltstyp "MinimalMain" als Hauptinhaltstyp für dieses Beispiel verwendet. Dieser Inhaltstyp besteht aus Header- und Footer-Logos und einer Liste von Seiten, die in der NAV enthalten sein sollen.

So erstellen Sie Inhaltstypen für das Contentmodell:

1. Melden Sie sich als Administrator bei der Oracle Content Management-Webbenutzeroberfläche an.
2. Wählen Sie im linken Navigationsmenü die Option Inhalt und anschließend Anlagentypen aus der Auswahlliste im Seitenheader.
3. Klicken Sie auf Erstellen in der oberen rechten Ecke.
4. Wählen Sie diese Option, um einen Inhaltstyp zu erstellen (kein digitaler Assettyp). Wiederholen Sie diesen Vorgang für alle erforderlichen Inhaltstypen.

Es werden drei Inhaltstypen mit jeweils eigenen Feldern erstellt:

• MinimalMain
• MinimalPage
• MinimalSection

Der erste Inhaltstyp, MinimalMain, sollte folgende Felder enthalten:

Anzeigename	Feldtyp	erforderlich	Rechnername
headerLogo	Einwertiges Medienfeld		headerLogo
footerLogo	Einwertiges Medienfeld		footerLogo
Seiten	Referenzfeld mit mehreren Werten		Seiten

Die MinimalMain-Inhaltstypdefinition sollte wie folgt aussehen:

Der zweite Inhaltstyp MinimalPage muss folgendes Feld enthalten:

Anzeigename	Feldtyp	erforderlich	Rechnername
Abschnitte	Referenzfeld mit mehreren Werten		Abschnitte

Der Inhaltstyp MinimalPage sollte wie folgt aussehen:

Der dritte und letzte Inhaltstyp, MinimalSection, sollte folgende Felder enthalten:

Anzeigename	Feldtyp	erforderlich	Rechnername
type	Einzelwert-Textfeld	X	type
Überschrift	Einzelwert-Textfeld		Überschrift
Hauptteil	Großtextfeld mit einem Wert		Hauptteil
Image	Bildfeld mit einem Wert		Image
Aktionen	Einwertiges eingebettetes Inhaltsfeld		Aktionen

Der Inhaltstyp MinimalSection sollte wie folgt aussehen:

Nachdem Sie Ihre Inhaltstypen erstellt haben, können Sie diese Inhaltstypen dem zuvor erstellten Repository OCEMinimalRepository hinzufügen:

1. Melden Sie sich als Administrator bei der Oracle Content Management-Webbenutzeroberfläche an.
2. Navigieren Sie zu OCEMinimalRepository.
3. Bearbeiten Sie das Repository, und geben Sie unter Anlagentypen alle drei neu erstellten Inhaltstypen an. Klicken Sie auf Speichern, um die Änderungen zu speichern.

Nachdem Sie die Inhaltstypen zum Repository hinzugefügt haben, können Sie das Repository OCEMinimalRepository auf der Seite Anlagen öffnen und Ihre Inhaltselemente für alle Inhaltstypen erstellen.

Aufgabe 2: Minimale Site in Next.js erstellen

Um unseren Oracle Content Management-Inhalt in einer serverseitigen wiedergegebenen Next.js-Anwendung zu verbrauchen, können wir das minimale Site-Beispiel Next.js verwenden, das als Open-Source-Repository auf GitHub verfügbar ist.

Hinweis: Beachten Sie, dass die Verwendung des Beispiels "Next.js" optional ist. In diesem Tutorial erhalten Sie einen schnellen Einstieg. Sie können auch Ihre eigene Next.js-Anwendung erstellen.

So erstellen Sie die minimale Site in Next.js:

1. Beispiel-Repository klonen und Abhängigkeiten installieren
2. Next.js-Anwendung konfigurieren
3. Mit dem Oracle Content Management Content-SDK arbeiten
4. Content-SDK zum Abrufen von Inhalt verwenden

Beispiel-Repository klonen und Abhängigkeiten installieren

Das Minimal Site Sample Next.js ist als Open-Source-Repository auf GitHub verfügbar.

Zunächst müssen Sie das Beispiel von GitHub auf Ihren lokalen Computer klonen und Ihr Verzeichnis in das Repository-Root ändern:

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

Nachdem Sie jetzt über Ihre Codebasis verfügen, müssen Sie Abhängigkeiten für die Anwendung herunterladen. Führen Sie den folgenden Befehl aus dem Root-Verzeichnis aus:

npm install

Next.js-Anwendung konfigurieren

In diesem minimalen Site-Beispiel für Next.js müssen Sie einige Informationen konfigurieren, damit Ihr Oracle Content Management Content-SDK (und alle anderen Anforderungen) die richtige Instanz-URL und API-Version mit dem richtigen Kanal-Token bestimmen kann. Diese Werte werden in script/server-config-utils.js verwendet, um einen neuen Zustellungsclient zu instanziieren.

Diese Anwendung verwendet eine .env.local-Datei, die von Next.js gelesen und dem Code innerhalb der Anwendung mit process.env zur Verfügung gestellt wird.

Öffnen Sie die .env.local-Datei in einem Texteditor. Folgendes wird angezeigt:

# 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

Ändern Sie die einzelnen Schlüssel/Wert-Paare entsprechend Ihrer Instanz-URL, der gewünschten API-Version und dem mit Ihrem Veröffentlichungskanal verknüpften Kanaltoken. Der Kanal für dieses Tutorial ist OCEMinimalChannel.

Mit dem Oracle Content Management Content-SDK arbeiten

Oracle Content Management bietet ein SDK, mit dem Sie Inhalte in Ihren Anwendungen erkennen und verwenden können. Das SDK wird als NPM-Modul veröffentlicht und das Projekt wird auf GitHub gehostet.

Weitere Informationen zum SDK finden Sie hier.

Das SDK wurde als Laufzeitabhängigkeit dieses Projekts in der Datei package.json registriert.

Content-SDK zum Abrufen von Inhalt verwenden

Wir können das Content-SDK jetzt nutzen, um Inhalte abzurufen, damit wir es in unserer Next.js-Anwendung wiedergeben können.

Das Inhalts-SDK verwendet ein DeliveryClient-Objekt, um den Endpunkt anzugeben. Sie können alle Anforderungen mit diesem Clientobjekt ausführen.

Der Skriptordner enthält den Code zum Abrufen von Daten aus Oracle Content Management mit dem Content-SDK.

Die Datei script/server-config-utils.js importiert das Content SDK und erstellt dann einen Zustellungsclient mit der in .env.local angegebenen Konfiguration.

Der folgende Befehl importiert das SDK:

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

Mit dem folgenden Befehl wird der Delivery Client erstellt:

return createDeliveryClient(serverconfig);

Die Datei script/services.js enthält Funktionen zum Abrufen der Daten für diese minimale Anwendung Next.js.

Die fetchOceMinimalMain()-Methode ruft den Inhaltstyp MinimalMain mit einem Slug mit minimalmain ab.

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

Für die Wiedergabe der Images stellt services.js eine Helper-Methode bereit, mit der das Quellset für eine Anlage abgerufen wird, die aus den Wiedergaben für die Anlage erstellt wurde.

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

Die fetchPage()-Methode ruft den Inhaltstyp MinimalPage mit dem Slug-Wert für die Seite ab.

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

Die getRenditionURLs()-Methode ruft die Wiedergabe-URLs für jedes Bild ab, das in einem Abschnitt mit der ID für dieses Image definiert werden kann.

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

Nachdem unsere Datenabfragen vorliegen, können wir die Antworten in unseren Next.js-Komponenten gerendern.

Next.js-Komponenten

Next.js basiert auf React und React verwendet eine Technologie, die als JSX bezeichnet wird. Dabei handelt es sich um eine HTML-ähnliche Syntaxerweiterung für JavaScript, um den Inhalt wiederzugeben. Auch wenn Sie reinen JavaScript schreiben können, um Daten aus Oracle Content Management wiederzugeben, wird dringend empfohlen, JSX zu verwenden.

Die minimale Siteanwendung unterteilt jede Seite in eine Reihe kleinerer Komponenten.

Die nächsten Abschnitte enthalten einen Überblick darüber, wie Next.js unsere Anwendung in jeder unserer Komponenten wiedergibt:

• Seitenordner
• Hauptkomponente
• Seitenkomponente
• Header- und Footer-Komponenten
• Abschnittskomponente
• Fehlerkomponente

Seitenordner

Auf unserer Website bieten wir eine Route - /page. Anforderungen werden an die Hauptkomponente geleitet, die in der Datei Pages/([..slug]].jsx definiert ist. Die Root-Pfadanforderung wird auf /page umgeleitet, indem in next.config.js eine Umleitung angegeben wird.

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

Alle Seiten enthalten eine Kopfzeile mit dem Firmenlogo und Links sowie eine Fußzeile, die ein Logo und Symbole in sozialen Medien enthält. Der Zugriff auf Seiten erfolgt über statische URLs und ruft alle erforderlichen Daten ab, bevor relevante Daten an untergeordnete Komponenten übergeben werden.

Next.js behandelt jede Seite im Seitenverzeichnis als Route für die Anwendung.

Hauptkomponente

Alle Seiten werden von der Hauptkomponente angezeigt, die sich auf den Seiten/Seiten/[[..slug]].jsx befindet. Alle Routen in Next.js werden optional abgefangen, indem der Parameter in doppelte Klammern ([...slug]]) eingefügt wird. Auf der Hauptseite, die standardmäßig die erste Seite in der Seitenliste ist, wird der Parameter nicht übergeben. Daher wird der Slug-Parameter als optional definiert.

Die Komponente importiert die API, um Daten aus der Datei services.js abzurufen.

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

Die URLs für die Seiten sind dynamische URLs, die den Seitenumbruch als Pfad enthalten. Beispiel: URL-Pfade sind

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

Wenn Next.js die statische Sitegenerierung für Seiten mit dynamischen URLs verwendet, ruft es getStaticPaths() auf, um alle Pfade für diese Seite abzurufen.

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

Mit der Funktion getStaticProps() werden die Daten für eine einzelne Instanz der Seite abgerufen. Der Seitenschlug wird aus dem Parameter abgerufen, der an die Methode übergeben wird. Der Seiten-Slug wird dann verwendet, um alle für diese Seite erforderlichen Daten abzurufen.

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

Seitenkomponente

Die Seitenkomponente ist für die Wiedergabe aller Abschnitte verantwortlich, die für eine Seite definiert wurden. Öffnen Sie die Seitenkomponente in den Komponenten/Page.jsx. Sie verwendet lediglich die Daten, die von der Hauptkomponente an sie übergeben wurden. Es werden keine zusätzlichen Daten vom Server abgerufen. Die Abschnittsdaten werden in der Komponente "Abschnitt" wiedergegeben.

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

Header- und Footer-Komponenten

Die Headerkomponente, die sich in den Komponenten/Header.jsx und der Footer-Komponente befindet, die sich in den Komponenten/Footer.jsx befindet, verwendet einfach Daten, die an sie von der Hauptkomponente übergeben werden. Sie erhalten keine zusätzlichen Daten vom Server.

Abschnittskomponente

Die Abschnittskomponente, die sich in den Komponenten/Section.jsx befindet, wird von der Seitenkomponente verwendet und dient zur Wiedergabe von Inhaltselementen des Typs MinimalSection.

Diese Komponente enthält Daten, die von der Seitenkomponente an sie übergeben wurden.

Fehlerkomponente

Die Fehlerkomponente, die sich in den Komponenten/Error.jsx befindet, wird von den Seiten- und Hauptkomponenten verwendet. Wenn beim Aufruf des Servers Fehler aufgetreten sind, werden diese wiedergegeben.

Aufgabe 3: Anwendung auf Deployment vorbereiten

Nachdem wir unsere Next.js-Blog-Website erstellt haben, müssen wir sie auf einem lokalen Entwicklungsserver sehen, damit wir Probleme debuggen und die Anwendung vor ihrem Go-Live in der Vorschau anzeigen können.

Bereiten Sie die Anwendung in zwei Schritten vor:

1. Lokalen Entwicklungsserver hochfahren
2. Verwenden von Skripten zum Erstellen und Ausführen der Anwendung in Entwicklung und Produktion

Lokalen Entwicklungsserver hochfahren

Sie können einen Entwicklungsserver lokal starten, indem Sie den folgenden Befehl ausführen.

npm run dev

Öffnen Sie dann Ihren Browser zu http://localhost:3000, um Ihre Site in Aktion anzuzeigen.

Hinweis: Dadurch werden die Seiten nicht vorab wiedergegeben. Im nächsten Abschnitt wird beschrieben, wie Sie die Seiten im Voraus anzeigen.

Verwenden von Skripten zum Erstellen und Ausführen der Anwendung in Entwicklung und Produktion

Für die Produktion wird das Build-Skript verwendet, um die Site statisch zu generieren.

npm run build

Mit dem Startskript wird ein Node.js-Server gestartet, der die statisch generierten Seiten bedient.

npm run start

---

Titel und Copyright-Informationen

Minimal Site in Next.js mit Headless Oracle Content Management erstellen

F49324-01

Oktober 2021

Copyright © 2021, Oracle and/or its affiliates.

Hauptverfasser: Oracle Corporation