Layout Page

Nel contesto del CMS, una pagina layout è una pagina che contiene elementi comuni a molte o tutte le pagine del sito. Esempi di elementi comuni sono tipicamente:

• header
• footer
• menu di navigazione
• palette di colori etc.

Immaginiamo che il nostro sito sia composto da più pagine, ad esempio:

• home page
• about page
• contact page

e tutte queste pagine abbiamo gli elementi elencati sopra in comune. Quando si definiscono le corrispondenti pagine sul backend del CMS si vuole evitare di ripetere questi elementi per ogni pagina.

Per questo scopo è sufficiente definire una layout page, che non è altro che una pagina in cui vengono messi esclusivamente gli elementi comuni a più pagine. Da notare che nel CMS non c'è un concetto esplicito di layout page: una layout page sarà uguale a tutte le altre, se non per i componenti che contiene. Si consiglia di usare una naming convention (es. "Main Layout") per distinguere tali pagine.

Per questo motivo, a seconda della complessità del sito, si può scegliere di non creare una layout page ad hoc, ma utilizzare ad esempio la home page come layout page. In questo caso:

• la home page non avrà nessuna layout page associata, e quindi prenderà ad esempio la palette da se stessa.
• le pagine secondarie useranno la home page come layout page, prendendo la palette e altre informazioni da quest'ultima.

Associare Pagine a Pagine di Layout

Ci sono due modi per creare quest'associazione:

• lato CMS: impostare una pagina di layout tra i settings della pagina (quindi nella configurazione lato CMS)
• lato frontend: indicare la layout page nel frontend quando si recupera la struttura di una pagina

Qualora venga indicata una layout page nel frontend, questa farà un override di un'eventuale pagina di layout CMS. Quale approccio utilizzare dipende dagli scenari. L'associazione lato CMS è più comune. Potrebbe aver senso l'associazione lato frontend in scenari più avanzati in cui si vuole permettere di cambiare dinamicamente, nel frontend, alcune caratteristiche del layout, quali ad esempio la palette.

Per creare l'associazione lato CMS è sufficiente entrare in una pagina, aprire il pannello Settings e scegliere la layout page tramite l'apposito attributo.

Per creare l'associazione lato frontend, quando si richiede una qualsiasi pagina, occorre indicare contestualmente anche la sua pagina di layout. Per farlo è sufficiente passare l'opzione layout nella chiamata all'hook useDiscoveryPage(), come nel seguente esempio:

const data = useDiscoveryPage('home', {
    layout: 'globalLayout'
}) ?? {};

L'opzione layout nell'esempio ha come valore lo slug della pagina che definisce il layout sul CMS. E' possibile, in alternativa, usare l'ID della pagina invece dello slug specificando l'opzione key_type=_id. In tal caso, anche la pagina stessa verrà recuperata per ID e non per slug.

Se viene richiesto il layout di una pagina, l'oggetto restituito dall'hook useDiscoveryPage() avrà una property aggiuntiva layout del tutto equivalente, come struttura, ad una normale pagina, come nell'esempio sotto:

{
  "components": [
    ...
  ],
  "details": {
    ...
  },
  "_id": "(page ID)",
  "layout": {
    "components": [
        ...
    ],
    "details": {
        ...
    },
    "_id": "(layout ID)"
  }
}

Esempio utilizzo layout in ReactJS

Per utilizzare il layout è opportuno definire un componente che renderizza le parti comuni della pagina (tipicamente header, footer, etc.), come nel seguente esempio:

<DiscoveryContext.Provider value={data}>
    <GlobalLayout layout={data.layout}>
        <DiscoveryComponents />
    </GlobalLayout>
</DiscoveryContext.Provider>

Nel componente GlobalLayout, a cui viene passata la sezione layout restituita dall'hook, è possibile recuperare i dati dei vari sottocomponenti utilizzando una find per ID, esempio:

const header = layout.components.find(component => 
    component._id === '0725f2cd-80bf-49b0-9490-feef3aba3c1f'
);

Per recuperare gli ID dei componenti dalle pagine del CMS: aprire la pagina, entrare nel componente di interesse e cliccare sull'icona "Clipboard" nell'header in alto della form del componente, ovvero l'icona nell'angolo a sinistra subito dopo l'icona ingranaggio.

Da notare che per i layout non è supportata la costruzione dinamica della pagina: la struttura del layout dev'essere codificato nell'applicazione ReactJS e non può essere modificata sul CMS. Nel CMS, tuttavia, è possibile modificare i dati che appariranno nel layout, come ad esempio:

• logo dell'applicazione
• voci del menu
• testi e immagini varie etc.