Page Element

pageElement

I page element rappresentano porzioni di contenuto in una pagina: paragrafi di testo, gallerie di immagini, ecc.. Questa sezione tratta di come i page element sono rappresentati e validati dal backend di Hydra.

Intro

Dal punto di vista del client delle API REST (di solito il frontend), i page element sono porzioni di JSON incapsulate nel JSON di un altro oggetto, come i footer dei siti o i banner delle pagine: questo è il modo in cui i page element vengono letti e inseriti.

//Così è come i page element sono visti dall'API
//L'oggetto root è un site
{
    "id": ...,
    "name": "BestSiteEver",
    "headers": [
        {
            "culture": "en",
            "pageElement": {
                "template": "header",
                "content": ...,
                "config": ...
            }
        }
    ]
}

In questo caso il json dell'element si trova al percorso headers.0.pageElement.

Struttura dei Page Element

A page element contains mainly three properties:

• Template: defines the kind of element.
• Config: properties that define the behaviour of the object in the page, both functionally and graphically.
• Content: the content of the element, can be of various kinds, for instance, a gallery page element will have an array of images as content.

But what is the kind of the element? What does the template field do? Since the front-end needs to render the element based on its properties, it demands that those property are present in the element's JSON and have meaningful values, both in the content and config sections: different kinds of element will require different property configuration (as said before, for an element with template gallery, the content prop is expected to contain a list of images).

Un page element contiene principalmente tre proprietà:

• Template: definisce il tipo di element.
• Config: proprietà che definiscono il comportamento dell'oggetto nella pagina, sia dal punto di vista funzionale che grafico.
• Content: Il contenuto del page element, che può essere di vari tipi, per esempio un page element "gallery" avrà come contenuto un array di immagini.

Cos'è il tipo del page element? Cosa fa il campo template? Per poter renderizzare un page element, il front-end ha bisogno che config e content seguano uno schema, richiede dunque che in questi oggetti siano presenti determinati campi.

Il backend ha il compito di assicurarsi che i page element seguano lo schema, il campo template è usato per indicare al sistema quale schema utilizzare per la formattazione del page element. Per ogni tipo di page element esiste uno schema che ne regola il formato, chiamato appunto Template.

Template

Per assicurarsi che il JSON inviato al frontend sia nel formato corretto, il page element è validato rispetto ad un template, ovvero una descrizione di come il JSON dovrebbe essere per essere usato per un particolare tipo di page element.

Queste descrizioni sono scritte in file di testo che sono caricati dinamicamente dal livello applicazione dal progetto Resources della soluzione. Questi file sono parsati e convertiti in una rappresentazione ad oggetti dello schema, che può essere utilizzata per validare i JSON in entrata e uscita.

I template hanno un formato simile a questo:

template foo in group bar with importance 5

config: {
    appearance: {
        margin: int(min=0, max=10) with default 0,
        backgroundColor: color with default "primary"
    }
}

content: array of (pageElement(pageElementType="cta"))

Analizzandolo per parti:

template foo in group bar with importance 5

The frontend groups elements by category for website editors to choose elements easily, sorted by importance in ascending order.

config: { appearance: { margin: int(min=0, max=10) with default 0, backgroundColor: color with default "primary" } }

This part defines what the configuration parameters are for this template: in this example, the configuration is an object containing a subobject "appearance", which in turn contains two fields:

• margin: int(min=0, max=10) with default 0: the margin field is defined as an integer with two args: min and max, which will be enforced at validation time. A default value for the field is set, that will be used if the margin field is not specified by the user.

• content: array of (pageElement(pageElementType="cta")): this is the definition of the element's content. Two things are noteworthy here: the first is that it's possible to make an array of anything by enclosing a type definition into array of (..); the second is that a template can reference other page elements (pageElement(pageElementType="cta")).

For more info about how to write templates please refer to this chapter.

Packing e Unpacking

Quando un utente inserisce un nuovo page element, come il footer di un sito, il JSON passato deve essere controllato per verificarne l'aderenza al template, e rimuovere campi ridondanti prima di archiviarlo nel DB, questa operazione viene chiamata "pack" all'interno del codice. Al contrario (unpack), quando un page element viene caricato dal DB per essere fornito al client, eventuali riferimenti a pagine, form o altro saranno risolti con i dati più recenti.

note

Pack/unpack nel dettaglio.