Passa al contenuto principale

Applicazioni NextJS

Setup​

Innanzitutto, è necessario fare il setup del connettore seguendo la sezione Setup, copiando il file discovery-cms-connector.js dentro la cartella public e aggiungendo all'interno del file _app.js il seguente script:

<script async={true} src={'discovery-cms-connector.js'} />

Utilizzo del loader Akamai​

Se si utilizza Akamai Image Manager e si vuole utilizzare next/image occorre definire un loader custom per le immagini come segue:

// file: lib/akamaiImageloader.js
export default function akamaiImageLoader({ src, width, quality }) {
    if (src.includes('?')) {
        return `${src};Resize,width=${width}`;
    } else {
        return `${src}?imwidth=${width}`;
    }
}

modificare next.config.js per puntare al loader Akamai:

module.exports = {
    ...
    images: {
            loader: 'custom',
            loaderFile: './lib/akamaiImageloader.js',
            remotePatterns: [{
                protocol: 'https',
                hostname: '<YOUR-AKAMAI-DOMAIN>',
            }],
        },
    };
    ...
}

In remotePatterns.hostname occorre indicare il dominio Akamai. La sezione remotePatterns è spiegata qui.

IMPORTANTE: senza questa modifica, se si utilizza Vercel le immagini transiteranno tutte per la CDN di Vercel. Verificare i limiti di banda del proprio account.

Client Side Generation​

In un'applicazione NextJS, oltre alla gestione client side, vista in React, bisogna considerare anche la generazione statica e server side dove la parte di rappresentazione dei dati rimane invariata rispetto ad un applicazione React, ma cambia come vengono recuperati i dati.

Server Side Generation​

Durante la generazione server-side, è possibile recuperare i dati utilizzando il connettore all'interno della funzione getServerSideProps:

export async function getServerSideProps(context) {
    const data = await getDiscoveryCms().getPage('slug');
    
    return {
        props: {
            data: data
        }
    }
}

Così facendo non è più necessario recuperare i dati con useDiscoveryPage o useDiscoveryContent.

Static Site Generation​

Durante la generazione statica delle pagine, è possibile recuperare i dati esattamente come mostrato per la SSG, ovviamente utilizzando il metodo NextJS corretto:

export async function getStaticSiteProps(context) {
    const data = await getDiscoveryCms().getContent('Slug');
    
    return {
        props: {
            data: data
        }
    }
}

Static Paths​

Quando si usa la generazione statica in combinazione con pagine dinamiche(ad esempio [slug].js), è necessario recuperare i path per i quali è necessario generare una pagina statica. L'array dei path può essere generato utilizzando il metodo getPathList che restituisce un array di oggetti 

{
    slug: 'some-slug'
}

Partendo da questo array, è possibile applicare una trasformazione per ottenere il formato richiesto da NextJS:

export async function getStaticPaths() {
    let paths = await getDiscoveryCms().getPathList({ type: 'ContentType' });
    paths = paths.map((path) => ({
        params: {
            slug: path.slug,
        },
    }));

    return {
        paths: paths,
        fallback: 'blocking',
    };
}

Preview Mode​

NextJS mette a disposizione la Preview Mode che permette la visualizzazione di modifiche a pagine statiche, senza dover buildare l'applicazione ed esporre tali modifiche al pubblico. Questo viene fatto utilizzando un cookie che l'applicazione utilizza per rigenerare la pagina per i client in possesso di tale cookie, permettendo di visualizzare in tempo reale delle modifiche fatte su un headless CMS senza doversi appoggiare ad altri environment. Il Discovery CMS supporta la preview mode attraverso qualche semplice accorgimento. Innanzitutto è necessario attivare due endpoint:

  • api/preview: permette di entrare nella preview mode
  • api/exit-preview: permette di uscire dalla preview mode.

Per fare questo, è necessario copiare i due file relativi da node_modules/@discoverycms/connector/nextjs dentro la cartella pages/api del progetto. Mentre l'endpoint di uscita può assumere path diversi, l'endpoint di attivazione della preview mode dev'essere necessariamente api/preview.

Successivamente, si deve aggiungere la variabile d'ambiente DISCOVERY_PREVIEW_TOKEN nel proprio file .env, settandola al valore del preview token fornito dal CMS.

Fatto questo, nel file _app.js, è necessario acquisire l'informazione relativa all'attivazione o meno della preview mode usando l'hook useRouter() e aggiungendo il data attribute data-preview-enabled allo script che integra il nostro file discovery-cms-connector.js così:

<script id="connectorScript" async={true} src={'/discovery-cms-connector.js'} data-preview-enabled={router.isPreview} />

A questo punto, accedendo alla pagina attraverso il nostro cms, la modalità di preview sarà attivata automaticamente ed il token con cui accedere alla versione di preview dei dati sarà presente dentro il context passato ai metodi getStaticProps e getServerSideProps. Sarà quindi necessario modificare questi metodi, nella parte relativa alla chiamata al connettore Discovery, passando tale token se presente:

    const data = await getDiscoveryCms().getPage(
        'home',
        {
            ...context.query,
            token: context.previewData?.token// Passiamo il token presente in previewData se presente
        }
    );

Questo permetterà, in fase di build, di usare il token pubblico e generare la pagina corretta, mentre, in fase di preview mode, di rigenerare la pagina usando i dati di preview e permettendo all'utente di visualizzare correttamente le modifiche che apporta alla pagina senza doverle rendere pubbliche.

È bene ricordare che l'utilizzo della Preview Mode è richiesto in caso di SSG. Nel caso di CSR, tale approccio non è previsto, in quanto esporrebbe il token di preview al pubblico. In tal caso, la visualizzazione di modifiche in fase di edit è fatta utilizzando il token che viene passato dal nostro CMS alla pagina, tramite query param token, e che deve essere passato alle opzioni dei vari metodi del connettore. Senza questo passaggio, non sarebbe possibile visualizzare le modifiche in tempo reale. Infine, in caso di SSR, è possibile utilizzare entrambi i metodi proposti sopra. Infatti la modalità SSR supporta la Preview Mode ma permette anche di accedere ai query param a ogni richiesta. Rimane quindi discrezione dello sviluppatore decidere quale approccio utilizzare.

Come ultimo appunto, è bene ricordare che l'utilizzo della Preview Mode potrebbe spaventare l'utente. Infatti, una volta attivata, la modalità rimane attiva per 2 ore e, sopratutto, è attiva anche accedendo direttamente al sito senza passare dal CMS. È quindi importante comunicare all'utente l'utilizzo o meno di questa modalità, mostrando un elemento ben visibile che comunichi ciò e permetta di tornare alla versione pubblica. Per fare questo è sufficiente inserire un link all'endpoint api/exit-preview.