Crea un sito minimo in Next.js con Headless Oracle Content Management

Introduzione

Next.js è una struttura Web di sviluppo frontend React open source che consente funzionalità quali il rendering lato server e la generazione di siti Web statici per le applicazioni Web basate su React.

Per utilizzare il contenuto di Oracle Content Management in un'applicazione Next.js, è possibile utilizzare l'esempio minimo Next.js disponibile come repository open-source su GitHub.

In questa esercitazione, creeremo un sito semplice e minimo in Next.js utilizzando Oracle Content Management come CMS senza problemi e il relativo kit di sviluppo software (SDK) per la distribuzione dei contenuti in JavaScript. Questo esempio di Next.js è disponibile su GitHub.

L'esercitazione include tre task:

1. Prepara Oracle Content Management
2. Creare il sito minimo in Next.js
3. Preparare l'applicazione per la distribuzione

Prerequisiti

Prima di procedere con questa esercitazione, si consiglia di leggere le seguenti informazioni:

• Concetti chiave
• Repository di asset

Per seguire questa esercitazione, sono necessari:

• una sottoscrizione a Oracle Content Management
• un account Oracle Content Management con il ruolo Amministratore contenuto
• un computer Windows o Mac con Node versione 10 o successiva

Cosa stiamo costruendo

Con Next.js minimo, puoi facilmente recuperare immagini e altri contenuti dal tuo repository di Oracle Content Management.

Per dare un'occhiata allo stato finale della nostra esercitazione, ecco il sito minimo Next.js di base che utilizza i contenuti di Oracle Content Management:

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

Questo è l'aspetto della home page alla fine di questa esercitazione:

Questo è l'aspetto della pagina Contattateci alla fine di questa esercitazione:

Per continuare, sarà necessario disporre di una sottoscrizione attiva a Oracle Content Management ed eseguire il login con il ruolo Amministratore contenuto.

Task 1: Prepara Oracle Content Management

Se non si dispone già di un'istanza di Oracle Content Management, vedere Avvio rapido per informazioni su come registrarsi per Oracle Cloud, eseguire il provisioning di un'istanza di Oracle Content Management e configurare Oracle Content Management come CMS senza problemi.

Per questa esercitazione sarà necessario creare un modello di contenuto. È disponibile un pacchetto asset scaricabile che riempirà il repository vuoto con i tipi di contenuto e il contenuto associato.

Per preparare Oracle Content Management, effettuare le operazioni riportate di seguito.

1. Creare un repository di canali e asset.
2. Importa pacchetto asset campioni di Oracle Content Management

Crea un repository di canale e asset

Prima è necessario creare un canale e un repository di asset in Oracle Content Management in modo da poter pubblicare il contenuto.

Per creare un canale e un repository di asset in Oracle Content Management, effettuare le operazioni riportate di seguito.

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.

2. Scegliere Contenuto nel menu di navigazione sinistro, quindi scegliere Pubblicazione canali dall'elenco di selezione nell'intestazione della pagina.

   

3. Nell'angolo in alto a destra fare clic su Crea per creare un nuovo canale. Assegnare un nome al canale 'OCEMinimalChannel' ai fini di questa esercitazione e mantenere pubblico l'accesso. Fare clic su Salva per creare il canale.

   

4. Scegliere Contenuto nel menu di navigazione sinistro, quindi scegliere Repositori dalla lista di selezione nell'intestazione della pagina.

   

5. Nell'angolo in alto a destra fare clic su Crea per creare un nuovo repository di asset. Assegnare un nome al repository di asset 'OCEMinimalRepository' ai fini di questa esercitazione.

   

6. Nel campo Pubblicazione canali selezionare il canale OCEMinimalChannel per indicare a Oracle Content Management che il contenuto nel repository OCEMinimalRepository può essere pubblicato nel canale OCEMinimalChannel. Al termine, fare clic su Salva.

   

Creazione di un modello di contenuto

Il task successivo consiste nel creare un modello di contenuto. È possibile utilizzare uno dei due metodi riportati di seguito.

• Metodo 1: Importazione del pacchetto asset di campioni di Oracle Content Management
• Metodo 2: creare un proprio modello di contenuto

Importa pacchetto asset campioni di Oracle Content Management

È possibile scaricare un pacchetto di asset di esempio Oracle Content Management preconfigurato contenente tutti i tipi di contenuto e gli asset necessari per questa esercitazione. Se si preferisce, è inoltre possibile creare un proprio modello di contenuto anziché scaricare il pacchetto di asset campione.

È possibile caricare una copia del contenuto utilizzato in questa esercitazione dal pacchetto di asset dei campioni di Oracle Content Management. In questo modo sarà possibile provare i tipi di contenuto e modificare il contenuto. Se si desidera importare il pacchetto di asset di esempio di Oracle Content Management, è possibile scaricare l'archivio del pacchetto di asset, OCESamplesAssetPack.zip, quindi estrarlo in una directory selezionata:

1. Scaricare il pacchetto asset di campioni di Oracle Content Management (OCESamplesAssetPack.zip) dalla pagina download di Oracle Content Management. Estrarre il file ZIP scaricato in una posizione sul computer. Dopo l'estrazione, questa posizione includerà un file denominato OCEMinimal_data.zip.

2. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.

3. Scegliere Contenuto nel menu di navigazione sinistro, quindi scegliere Repositori dalla lista di selezione nell'intestazione della pagina. Selezionare ora OCEMinimalRepository e fare clic sul pulsante Importa contenuto nella barra delle azioni superiore.

   

4. Caricare OCEMinimal_data.zip dal computer locale nella cartella Documenti.

   

5. Dopo aver caricato, selezionare OCEMinimal_data.zip e fare clic su OK per importare il contenuto nel repository degli asset.

   

6. Dopo aver importato il contenuto, passare alla pagina Asset e aprire il repository OCEMinimalRepository. Si noterà che tutte le immagini e gli elementi di contenuto correlati sono stati aggiunti al repository di asset.

   

7. Fare clic su Seleziona tutto in alto a sinistra, quindi su Pubblica per aggiungere tutti gli asset importati al canale di pubblicazione creato in precedenza, OCEGettingStartedChannel.

   

8. Prima della pubblicazione, è necessario convalidare tutti gli asset. Aggiungere prima OCEMinimalChannel come canale selezionato, quindi fare clic sul pulsante Convalida.

   

9. Dopo la convalida degli asset, è possibile pubblicare tutti gli asset nel canale selezionato facendo clic sul pulsante Pubblica nell'angolo superiore destro.

   

Al termine, è possibile visualizzare nella pagina Asset la pubblicazione di tutti gli asset. (È possibile visualizzare l'icona sopra il nome dell'asset).

Dopo aver importato il pacchetto di asset di campioni di Oracle Content Management, è possibile avviare la creazione del sito minimo in Next.js.

Crea il tuo modello di contenuto

Invece di importare il pacchetto di asset dei campioni di Oracle Content Management, è possibile creare un proprio modello di contenuto.

In questa esercitazione viene utilizzato un tipo di contenuto denominato 'MinimalMain' come tipo di contenuto principale per questo esempio. Questo tipo di contenuto è costituito da loghi di intestazione e piè di pagina e da un elenco di pagine da includere nel nav.

Per creare tipi di contenuto per il modello di contenuto, eseguire le operazioni riportate di seguito.

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.
2. Scegliere Contenuto nel menu di navigazione sinistro, quindi scegliere Tipi di asset dall'elenco di selezione nell'intestazione della pagina.
3. Fare clic su Crea nell'angolo superiore destro.
4. Scegliere di creare un tipo di contenuto (non un tipo di asset digitale). Ripetere l'operazione per tutti i tipi di contenuto richiesti.

Verranno creati tre tipi di contenuto, ciascuno con il proprio set di campi:

• MinimalMain
• MinimalPage
• MinimalSection

Il primo tipo di contenuto, MinimalMain, deve avere i seguenti campi:

Nome visualizzato	Tipo di campo	Obbligatorio.	Nome computer
headerLogo	Campo multimediale a valore singolo		headerLogo
footerLogo	Campo multimediale a valore singolo		footerLogo
pagine	Campo di riferimento a più valori		pagine

Questo è l'aspetto che dovrebbe avere la definizione del tipo di contenuto MinimalMain:

Il secondo tipo di contenuto, MinimalPage, deve avere il seguente campo:

Nome visualizzato	Tipo di campo	Obbligatorio.	Nome computer
sezioni	Campo di riferimento a più valori		sezioni

Questo è l'aspetto del tipo di contenuto MinimalPage:

Il terzo e il tipo di contenuto finale, MinimalSection, devono avere i seguenti campi:

Nome visualizzato	Tipo di campo	Obbligatorio.	Nome computer
tipo	Campo di testo a valore singolo	X	tipo
titolo	Campo di testo a valore singolo		titolo
corpo	Campo di testo di grandi dimensioni a valore singolo		corpo
immagine	Campo immagine a valore singolo		immagine
azioni	Campo di contenuto incorporato a valore singolo		azioni

Questo è l'aspetto del tipo di contenuto MinimalSection:

Dopo aver creato i tipi di contenuto, è possibile aggiungerli al repository creato in precedenza, OCEMinimalRepository:

1. Eseguire il login all'interfaccia Web di Oracle Content Management come amministratore.
2. Passare a OCEMinimalRepository.
3. Modificare il repository e, in Tipi di asset, specificare tutti e tre i tipi di contenuto appena creati. Fare clic sul pulsante Salva per salvare le modifiche.

Dopo aver aggiunto i tipi di contenuto al repository, è possibile aprire il repository OCEMinimalRepository nella pagina Asset e iniziare a creare gli elementi di contenuto per tutti i tipi di contenuto.

Task 2: Creare il sito minimo in Next.js

Per utilizzare il contenuto di Oracle Content Management in un'applicazione Next.js di rendering lato server, è possibile utilizzare l'esempio di sito minimo Next.js, disponibile come repository open source in GitHub.

Nota: tenere presente che l'uso dell'esempio Next.js è facoltativo e che viene utilizzato in questa esercitazione per iniziare rapidamente. Puoi anche creare la tua applicazione Next.js.

Per creare il sito minimo in Next.js:

1. Duplicare il repository di esempio e installare le dipendenze
2. Configurare l'applicazione Next.js
3. Utilizzare l'SDK di Oracle Content Management Content
4. Utilizzare l'SDK del contenuto per recuperare il contenuto

Duplicare il repository di esempio e installare le dipendenze

L'esempio di sito minimo di Next.js è disponibile come repository open source in GitHub.

Sarà prima necessario clonare l'esempio da GitHub al computer locale e modificare la directory nella directory root del repository:

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

Ora che si dispone del codice base, è necessario scaricare le dipendenze per l'applicazione. Eseguire il comando seguente dalla directory root:

npm install

Configurare l'applicazione Next.js

In questo esempio di sito minimo Next.js, devi configurare alcune informazioni in modo che il SDK di Oracle Content Management Content (e qualsiasi altra richiesta) possa definire la versione corretta dell'URL dell'istanza e dell'API con il token di canale corretto. Questi valori vengono utilizzati in script/server-config-utils.js per creare un'istanza di un nuovo client di distribuzione.

Questa applicazione utilizza un file .env.local letto da Next.js e reso disponibile al codice all'interno dell'applicazione con process.env.

Aprire il file .env.local in un editor di testo. Sono disponibili gli elementi riportati di seguito.

# 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

Modificare ogni coppia chiave-valore in modo che rifletta l'URL dell'istanza, la versione dell'API a cui si desidera indirizzare e il token canale associato al canale di pubblicazione. Il canale per questa esercitazione è OCEMinimalChannel.

Utilizzare l'SDK di Oracle Content Management Content

Oracle Content Management offre un SDK che consente di individuare e utilizzare i contenuti nelle applicazioni. L'SDK viene pubblicato come modulo NPM e il progetto viene gestito in hosting su GitHub.

Per ulteriori informazioni sull'SDK, fare clic qui.

L'SDK è stato registrato come dipendenza runtime di questo progetto nel file package.json.

Utilizzare l'SDK del contenuto per recuperare il contenuto

Ora possiamo utilizzare il kit SDK del contenuto per recuperare il contenuto in modo da renderlo disponibile nell'applicazione Next.js.

L'SDK del contenuto utilizza un oggetto DeliveryClient per specificare l'endpoint. È possibile creare tutte le richieste utilizzando tale oggetto client.

La cartella script contiene il codice per ottenere i dati da Oracle Content Management mediante l'SDK del contenuto.

Il file script/server-config-utils.js importa l'SDK del contenuto e quindi crea un client di consegna utilizzando la configurazione specificata in .env.local.

Il comando seguente importa l'SDK:

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

Il comando seguente crea il client di consegna:

return createDeliveryClient(serverconfig);

Il file script/services.js contiene funzioni per ottenere i dati per questa applicazione minima Next.js.

Il metodo fetchOceMinimalMain() recupera il tipo di contenuto MinimalMain con un slug di 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;
    }

Per il rendering delle immagini, service.js fornisce un metodo di supporto per recuperare il set di origini per un asset costruito dalle rendition per l'asset.

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

Il metodo fetchPage() recupera il tipo di contenuto MinimalPage utilizzando il valore slug per la pagina.

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

Il metodo getRenditionURLs() recupera gli URL di rendition per qualsiasi immagine che può essere definita in una sezione utilizzando l'ID per tale immagine.

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

Dopo aver ricevuto le nostre query sui dati, possiamo rendere le risposte nei nostri componenti Next.js.

Componenti Next.js

Next.js si basa su React e React utilizza una tecnologia conosciuta come JSX, che è un'estensione di sintassi simile ad HTML a JavaScript, per il rendering del contenuto. Sebbene sia possibile scrivere JavaScript puro per il rendering dei dati da Oracle Content Management, si consiglia di utilizzare JSX.

L'applicazione di sito minima scompone ogni pagina in un certo numero di componenti più piccoli.

Le prossime sezioni includono una panoramica su come Next.js rende la nostra applicazione in ognuno dei nostri componenti:

• Cartella delle pagine
• Componente principale
• Componente di pagina
• Componenti di intestazione e pagina
• Componente sezione
• Componente errore

Cartella delle pagine

Nel nostro sito, forniamo un percorso - /page. Le richieste vengono indirizzate al componente principale definito nel file page/page/[[..slug]].jsx. La richiesta di percorso radice viene reindirizzata a /page specificando un reindirizzamento in next.config.js.

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

Tutte le pagine hanno un'intestazione, contenente il logo e i collegamenti dell'azienda e un piè di pagina, contenente un logo e le icone dei social media. È possibile accedere alle pagine tramite URL statici e ottenere tutti i dati necessari prima di passare i dati rilevanti a qualsiasi componente figlio.

Next.js considera qualsiasi pagina della directory delle pagine come un instradamento per l'applicazione.

Componente principale

Tutte le pagine vengono visualizzate dal componente principale, che si trova in pagine/pagina/[[..slug]].jsx. La cattura di tutti gli instradamenti in Next.js è facoltativa includendo il parametro tra parentesi doppie ([[...slug]]). La pagina radice che per impostazione predefinita corrisponde alla prima pagina della lista delle pagine non dispone del parametro passato e pertanto il parametro slug viene definito come facoltativo.

Il componente importa l'API per ottenere i dati dal file services.js.

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

Gli URL per le pagine sono URL dinamici che contengono il slug della pagina come percorso, ad esempio i percorsi URL sono

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

Quando Next.js utilizza la generazione statica del sito per le pagine con URL dinamici, chiama getStaticPaths() per ottenere tutti i percorsi per quella pagina.

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 funzione getStaticProps() viene utilizzata per ottenere i dati per una singola istanza della pagina. La pagina slug viene ottenuta dal parametro passato nel metodo. La pagina slug viene quindi utilizzata per ottenere tutti i dati necessari per questa pagina.

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 di pagina

Il componente Pagina è responsabile del rendering di tutte le sezioni definite per una pagina. Aprire il componente Pagina, disponibile in component/Page.jsx. Utilizza semplicemente i dati passati dal componente principale. Non riceve dati aggiuntivi dal server. Viene utilizzato il componente Sezione per il rendering dei dati della sezione.

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

Componenti di intestazione e pagina

Il componente Intestazione, che si trova in component/Header.jsx e il componente Piè di pagina, che si trova in component/Footer.jsx, utilizza semplicemente i dati passati dal componente principale. Non ottengono dati aggiuntivi dal server.

Componente sezione

Il componente Section, che si trova in component/Section.jsx, viene utilizzato dal componente Page e viene utilizzato per eseguire il rendering di qualsiasi elemento di contenuto di tipo MinimalSection.

Questo componente contiene dati passati dal componente Pagina.

Componente errore

Il componente Error, che si trova in component/Error.jsx, viene utilizzato dalla pagina e dai componenti Main. In caso di errori durante la chiamata al server, verranno visualizzati.

Task 3: Prepara la tua applicazione per la distribuzione

Dopo aver creato il nostro sito di blog Next.js, dobbiamo vederlo in un server di sviluppo locale in modo da poter eseguire il debug di qualsiasi problema e visualizzare l'anteprima dell'applicazione prima che sia attiva.

Preparare l'applicazione per la distribuzione in due passaggi:

1. Attiva un server di sviluppo locale
2. Utilizza script per creare ed eseguire l'applicazione in sviluppo e produzione

Attiva un server di sviluppo locale

È possibile avviare localmente un server di sviluppo eseguendo il comando seguente.

npm run dev

Aprire quindi il browser in uso a http://localhost:3000 per visualizzare il sito in azione.

Nota: non verrà eseguito il pre-rimozione delle pagine. Per pre-riassegnare le pagine, vedere la sezione successiva.

Usa script per creare ed eseguire l'applicazione in sviluppo e produzione

Per la produzione, lo script di creazione verrà utilizzato per generare staticamente il sito.

npm run build

Lo script iniziale viene utilizzato per avviare un server Node.js che serve le pagine generate in modo statico.

npm run start

---

Titolo e informazioni sul copyright

Crea un sito minimo in Next.js con Headless Oracle Content Management

F49325-01

Ottobre 2021

Copyright © 2021, Oracle and/or its affiliates.

Autore principale: Oracle Corporation