Contenuti dinamici: fonti, cicli e associazioni dei campi

Contenuti dinamici collega i record forniti da un'integrazione attiva ai normali blocchi CMS. Il fornitore gestisce dati e traduzioni; tu gestisci layout, modello ripetuto e associazioni. Questa guida descrive il flusso del pannello in CMS 1.104.0 con lo standard delle fonti 1.0. L'esempio è il catalogo dei plugin pubblicato.

Puoi creare questi collegamenti senza scrivere richieste API o inserire ID dei blocchi. Accesso API e credenziali appartengono all'integrazione installata; questo spazio seleziona fonti già registrate dall'integrazione.

Trovare una fonte e i suoi utilizzi

Apri Contenuti dinamici → Fonti. I dettagli mostrano fornitore, origine dichiarata, raccolta o record singolo, lingue, chiave stabile e campi disponibili. La dichiarazione delle lingue descrive un contratto; non conferma una connessione attiva riuscita.

Le viste Cicli, Collegamenti campi e Problemi mostrano dove sono usate le fonti. Filtra per sito, stato di pubblicazione o ricerca. I numeri contano blocchi e collegamenti salvati, non schede generate. Aprire l'inventario legge la configurazione senza richiedere contenuti remoti. Gli utilizzi nei Shared Slot rimandano all'editor esistente; il flusso guidato seguente usa slot propri della pagina.

L'integrazione di esempio offre tre fonti distinte:

Published plugin catalog (webblocks-extensions-live::plugins): una raccolta per le schede ripetute.
Published plugin (webblocks-extensions-live::plugin): un plugin selezionato, ad esempio come record fisso.
Catalog interface (webblocks-extensions-live::ui): il record labels fornisce testi di interfaccia condivisi e tradotti.

Queste etichette del fornitore possono restare in inglese anche nel pannello tradotto. I contenuti dei record usano la lingua richiesta.

Collegare una fonte a una pagina

Nei dettagli scegli Usa in una pagina. Seleziona sito e pagina, poi Carica destinazione. Per la raccolta del catalogo, scegli Grid come blocco del ciclo. Carica la destinazione e scegli il figlio diretto Card come modello ripetuto.

In una pagina pubblicata puoi subito esaminare e visualizzare le connessioni. Prima di salvare, scegli Prepara bozza di aggiornamento, poi seleziona la destinazione nella bozza. I blocchi clonati hanno ID propri: usa i selettori visibili e controlla le associazioni risultanti. La pagina pubblicata resta invariata.

Se manca un modello adatto, Crea griglia e scheda iniziali aggiunge una struttura non collegata a uno slot proprio della bozza. Conserva i blocchi e non sceglie le associazioni al tuo posto. Installazione, accesso alla fonte e credenziali API si configurano nell'integrazione del fornitore, non qui. Per installarla consulta Sistema dei plugin.

Scegliere ciclo e modello ripetuto

Il ciclo appartiene a Grid; Card è il modello ripetuto una volta per ogni record corrispondente. I blocchi Image, Header, Plain Text e Button Link dentro Card ricevono il record corrente. Un Header fisso accanto a Card resta editoriale e non può usare il record corrente di quel ciclo.

L'albero indica proprietario del ciclo, modello ripetuto e campi collegati. Gli antenati chiusi segnalano contenuti dinamici al loro interno. Segui un indicatore per raggiungere ciclo o associazione. Una sola Card salvata può quindi produrre dieci schede pubbliche senza dieci copie modificabili.

Scegli un figlio diretto compatibile, non un discendente di secondo livello o un blocco di un'altra pagina. Section, Container, Stack, Cluster, Grid e Slide accettano modelli figli altrimenti validi; Slider richiede Slide, Columns richiede Column Item, Feature Grid richiede Feature Item o Column Item e Link List richiede Link List Item. Card e Split non espongono questa capacità di contenitore di raccolte.

Section
└─ Container
   └─ Grid  [loop: Published plugin catalog]
      ├─ Header  [fixed editorial block]
      └─ Card  [repeated template]
         ├─ Image
         ├─ Header
         ├─ Plain Text
         └─ Button Link

Impostare filtri, ordinamento e paginazione

Per il catalogo imposta Record massimi a 50, Campo ordinamento a title, direzione crescente e Record per pagina a 12; abilita Pagina i record. Cinquanta è il limite di risoluzione, non la garanzia di cinquanta record. Dieci corrispondenze con dodici record per pagina producono una sola pagina di anteprima. Slider non supporta questo controllo di paginazione.

Filtra solo per i campi dichiarati. Published plugin catalog seleziona già i plugin pubblicati nel fornitore; non inventare un campo status né mantenere un secondo filtro di pubblicazione nel CMS. Scegli separatamente i comportamenti Se non ci sono record e Se la fonte non risponde: nascondere il modello o conservare la versione editoriale. Controlla entrambi prima di pubblicare.

Per raccolte piccole CMS filtra e ordina i record restituiti. I fornitori con supporto alle query eseguono direttamente la ricerca. I dettagli della fonte indicano il modello utilizzato.

Associare campi al record corrente, a uno fisso o al valore editoriale

In Associazioni del modello scegli una modalità valore per ogni campo di destinazione:

Record corrente del ciclo: i valori cambiano per scheda. Scegli raccolta e campo compatibile; il record è l'elemento corrente.
Record fisso della fonte: tutte le schede possono condividere il valore di un record. Scegli fonte, record e poi campo compatibile.
Valore editoriale / riserva: usa testo o media inseriti nel blocco. Se un collegamento non restituisce un valore utilizzabile, il valore editoriale può fungere anche da riserva.

Per esempio collega il titolo Header a title, il contenuto Plain Text a summary e l'URL Button Link a url del record corrente. Per l'etichetta del pulsante usa la fonte fissa Catalog interface, record labels, campo explore. Fonte, record e campo hanno selettori separati; Cerca record e campi restringe le opzioni.

I blocchi collegati hanno anche una scheda dedicata Contenuti dinamici. I normali Campi del blocco contengono i valori editoriali di riserva. Un campo di testo non può scegliere un campo riservato agli URL; le scelte del record corrente sono limitate al ramo del modello selezionato. Prima di modificare o rimuovere il ciclo devi risolvere le associazioni interessate: la convalida rifiuta collegamenti orfani o incompatibili.

Collegare separatamente immagine, testo alternativo, didascalia e link

La fonte fornisce un URL immagine accessibile o un riferimento multimediale di questa installazione CMS. L'ID numerico di un'immagine remota non è automaticamente un ID media CMS. CMS mostra l'immagine tramite il normale blocco Image; non copi il file in ogni Card.

Per Image del catalogo usa quattro collegamenti indipendenti:

Fonte immagine → image_url del record corrente.
Testo alternativo → image_alt.
Didascalia facoltativa → image_caption.
Link → url.

Il file può essere condiviso tra lingue, mentre testo alternativo e didascalia cambiano. Il testo alternativo descrive informazioni visive rilevanti; la didascalia aggiunge contesto visibile facoltativo. Non copiare l'uno nell'altra. Nell'API, Image subtitle indica il testo alternativo e Image title la didascalia. Verifica caricamento e adeguatezza dei testi: un campo di tipo URL non dimostra che l'indirizzo contenga un'immagine.

Ricevere le traduzioni dal fornitore

Lo standard 1.0 richiede a ogni fonte tutte le sei lingue CMS: en, tr, de, es, it e fr, anche quando il sito ne abilita meno. CMS richiede la lingua abilitata del sito corrente; il fornitore restituisce testo del record, testo alternativo, didascalia ed etichette condivise corrispondenti. Non traduci ogni scheda generata nell'editor della pagina.

La stessa Card usa ad esempio summary in inglese e la traduzione turca del fornitore quando la lingua richiesta è tr. L'etichetta del pulsante proviene da Catalog interface / labels / explore nella stessa lingua. Il file immagine può restare identico.

Le parti statiche scritte intorno al ciclo continuano a usare le normali traduzioni di pagine e blocchi. La convalida verifica marcatori linguistici, chiavi stabili e tipi, non la qualità della traduzione. Visualizza ogni lingua abilitata e controlla il testo effettivo. Un fornitore non deve etichettare l'inglese invariato come un'altra lingua.

Controllare l’anteprima configurata prima di salvare

Scegli Lingua anteprima, poi Verifica fonte e anteprima. L'anteprima privata in una nuova scheda rende il modello reale con associazioni non salvate, filtro, ordinamento, limite e paginazione correnti. Non salva né pubblica la pagina. Aprire soltanto i dettagli della fonte non esegue questa verifica.

Controlla numero di record, titoli, riepiloghi, etichette e destinazioni dei pulsanti. Verifica immagini caricate, testi alternativi e didascalie tradotti. Distingui un risultato vuoto valido da accesso negato, risposta non conforme al contratto o fornitore non disponibile. L'anteprima segnala questi stati separatamente. Se necessario controlla accesso o impostazioni del fornitore; non sostituire dati mancanti con traduzioni ipotizzate.

Dopo aver cambiato impostazioni genera una nuova anteprima. Se è presente paginazione, passa tra le pagine per controllare il risultato. Un campione API aiuta nella diagnosi, ma non sostituisce l'anteprima visiva completa della Card.

Salvare la bozza e verificare separatamente la pubblicazione

Salva collegamenti della bozza aggiorna solo la bozza e registra una revisione. Se la pagina è cambiata dopo l'apertura, ricaricala e controlla prima di salvare. Una configurazione non valida conserva le impostazioni precedenti. Ricontrolla la bozza renderizzata in tutte le lingue abilitate e usa il normale flusso editoriale per pubblicare o promuovere l'aggiornamento.

Una raccolta ripete blocchi in una pagina esistente. La destinazione di dettaglio deve già esistere o essere fornita da una regola Pagine automatiche configurata separatamente. Collegare un ciclo non crea né attiva la regola. Il fornitore dei plugin pubblicati determina i record disponibili; CMS non dovrebbe gestire una seconda copia manuale del catalogo.

Riferimento tecnico: standard delle fonti e contratto per record singoli

Un plugin abilitato registra fonti in PluginDefinition::contentSources(...). Un risolutore di entità implementa ContentSourceResolver: options() offre scelte sicure e leggibili con identità stabile come chiave; resolve() restituisce un record per sito, pagina, lingua e contesto di anteprima. Un risolutore di raccolta implementa ContentCollectionSourceResolver; raccolte grandi possono implementare QueryableContentCollectionSourceResolver usando ContentCollectionQuery e ContentCollectionResult per query, totali e finestre di pagina.

La dichiarazione seguente appartiene all'integrazione, non all'editor. Ogni record risolto deve includere _locale uguale alla lingua richiesta, una chiave stringa non vuota dichiarata da recordKey e tutti i campi dichiarati. Usa null per i valori non disponibili; le chiavi di raccolta devono essere uniche. I tipi sono text, rich_text, url o media. Un valore media è un ID media CMS positivo; gli altri valori diversi da null sono stringhe. Gli URL devono rispettare il contratto URL della fonte.

ContentSourceDefinition::collection('catalog::items')
  ->label('Catalog items')
  ->resolver(CatalogItems::class)
  ->standard(
    locales: ['en', 'de', 'tr', 'es', 'it', 'fr'],
    description: 'Localized catalog records.',
    origin: 'Catalog application',
    recordKey: 'id',
  )
  ->fields([
    'id' => ['type' => 'text', 'label' => 'Record ID'],
    'title' => ['type' => 'text', 'label' => 'Title'],
    'image_url' => ['type' => 'url', 'label' => 'Image'],
    'image_alt' => ['type' => 'text', 'label' => 'Alternative text'],
    'image_caption' => ['type' => 'text', 'label' => 'Caption'],
  ]);

Le fonti senza versione sono segnate come Legacy — aggiornamento standard necessario. Le scelte esistenti possono restare invariate, ma i nuovi collegamenti richiedono lo standard multilingue. I fornitori mantengono tabelle e record; CMS gestisce layout e rendering. I contenitori dei plugin attivano la capacità con contentCollectionTemplate() e rendono i figli risolti con ContentCollectionRenderer::children($block); i manifest usano content_collection.enabled e facoltativamente content_collection.child_types. I plugin dovrebbero riutilizzare i renderer Card, Grid e Image del nucleo.

Riferimento tecnico: accesso, cache e valori di riserva

Per record riservati associa una ContentSourceAccessPolicy con accessPolicy(...); CMS controlla sito, pagina, lingua, stato di anteprima e utente autenticato prima della risoluzione. Errori di entità e valori vuoti mantengono la riserva editoriale del campo. Il risultato vuoto di una raccolta e gli errori del risolutore si configurano separatamente; fonti negate o rimosse mantengono l'albero salvato. Problemi e controlli dei blocchi mostrano collegamenti indisponibili senza eliminarli silenziosamente.

cacheFor($seconds) attiva una cache limitata; zero, il valore predefinito, la disattiva. Le chiavi includono fonte, sito, pagina, lingua, argomenti di record/query e impostazioni della fonte. L'anteprima non usa questa cache. Dopo una modifica ai dati del dominio richiama app(ContentSourceRuntime::class)->invalidate('plugin-handle::source') per invalidare le varianti della fonte. Duplicazione, revisioni ed esportazione/importazione conservano collegamenti e configurazione della raccolta; i risultati eseguiti del fornitore non vengono copiati nei pacchetti.

Riferimento tecnico: Internal Content API

GET /webadmin/api/content-sources individua le fonti abilitate accessibili. Aggiungi block_id per vedere destinazioni compatibili e capacità di raccolta. POST /webadmin/api/content-sources/{source}/preview risolve un'entità selezionata o fino a cinque record di esempio di una raccolta, esponendo solo campi dichiarati. Questo endpoint non rende l'intero modello configurato.

PATCH /webadmin/api/blocks/{block} accetta content_bindings e content_collection al primo livello o sotto settings. Ogni oggetto sostituisce la configurazione corrispondente; null la cancella. La convalida include accesso, scelte dei record, tipi, appartenenza dei figli diretti e capacità del modello. Le richieste non valide restituiscono 422 invalid_content_source_configuration. Usa una tua bozza o bozza di aggiornamento e rendi poi il risultato; segui le regole di autorizzazione e pubblicazione di Internal Content API. Image subtitle e title mantengono i significati distinti di testo alternativo e didascalia.