I widget nel CMS di Total.js: usarli in una pagina e scrivere i tuoi

CMS · cms@8071e48 cmswidgetsrenderclassdata-cms

Un widget è un blocco che inserisci in una pagina: un titolo, un avviso, una galleria. Porta il proprio stile, un modulo per configurarlo nell’editor e, facoltativamente, codice che lo renderizza sul server. Un widget è un file HTML, come un componente di Flow, e il CMS lo conserva nei suoi metadati.

Nell’HTML di una pagina, un widget è un div con due attributi:

<div data-cms="headline__%7B%22h%22%3A%22h1%22%2C%22align%22%3A%22left%22%7D" data-cms-id="h1">
	<h1 class="w-headline-h">Hello CMS</h1>
	<p>Some text</p>
</div>

data-cms è <widget id>__<configuration>, dove la configurazione è un oggetto JSON scritto con encodeURIComponent. Lo scrive l’editor; puoi scriverlo tu quando generi pagine.
data-cms-id è l’identificativo dell’istanza nella pagina.

Quando la pagina viene servita, il CMS rimuove l’attributo data-cms, conserva l’HTML che c’è dentro e aggiunge all’head lo stile di ogni widget della pagina. Se il widget non è installato, il suo blocco viene scartato.

Parte	A cosa serve
`<script total>`	i metadati e il codice del server: `exports.id`, `name`, `author`, `version`, `preview` (un’immagine o un data URI), `config` (i valori predefiniti) e, facoltativamente, `dependencies`, `install`, `uninstall` e `render`
`<style>`	il CSS del widget
`<body>`	il design del widget come lo mostra l’editor; gli elementi con la classe `CMS_edit` sono quelli modificabili; le altre classi `CMS_*` (`CMS_repeat`, `CMS_remove`, `CMS_unwrap`...) sono segnalini per l’editor, e il compilatore le rimuove prima di servire la pagina
`<settings>`	il modulo che modifica `config` nell’editor (input di jComponent il cui percorso inizia con `?.`) e uno `<script>` con `exports.save(config, el)` che cambia il design quando cambia la configurazione
`<template>`	un modello facoltativo per il widget
`<readme>`	l’aiuto del widget

CLASS nello stile, nelle impostazioni, nel modello e nel design viene sostituito da una classe che appartiene al widget (w- seguito dal suo id), così due widget non condividono mai una regola: nel widget alert, .CLASS-color1 diventa .w-alert-color1.

exports.dependencies accetta un elenco o una stringa separata da virgole: un indirizzo che termina con .js diventa un <script src> e uno che termina con .css un <link rel="stylesheet">, aggiunti all’head della pagina.

Renderizzare sul server

Un widget senza exports.render viene solo ripulito e servito così com’è. Con render può costruire il proprio HTML dalla configurazione:

<script total>

	exports.id = 'hello';
	exports.name = 'Hello';
	exports.author = 'Me';
	exports.version = '1';
	exports.config = { text: 'world' };

	exports.render = function(opt, next) {
		next('<p class="w-hello">Hello ' + (opt.config.text || '').toUpperCase() + '</p>', true);
	};

</script>

<style>
	.CLASS { color: #07c; }
</style>

<body>
	<p class="CLASS CMS_edit">Hello world</p>
</body>

opt.config è la configurazione dell’istanza, opt.html l’HTML che c’era dentro il blocco, e opt.id, opt.uid e opt.body lo descrivono. next(html, replace) fornisce l’HTML da servire; con true come secondo argomento sostituisce l’intero blocco. Abbiamo salvato questo file in un CMS locale e una pagina con data-cms="hello__..." e {"text":"mundo"} è uscita come <p class="w-hello">Hello MUNDO</p>, con .w-hello{color:#07c} nell’head. Il widget ufficiale picture usa la stessa funzione per aggiungere loading="lazy" alla sua immagine, e code per stampare il codice delle sue impostazioni.

exports.install e exports.uninstall vengono eseguiti con il database del CMS quando il widget viene aggiunto, modificato o rimosso.

Il plugin Widgets dell’admin importa un file; tramite l’API è widgets_save con { "html": "<file content>", "singleton": true } (singleton salta il widget se esiste già), widgets_list, widgets_read, widgets_detail e widgets_remove. Richiedono il permesso widgets (vedi l’API dell’admin). I 43 widget ufficiali sono in il repository dei widget.

I widget nel CMS di Total.js: usarli in una pagina e scrivere i tuoi

Un widget dentro una pagina

Le parti di un file di widget

Renderizzare sul server

Installare e rimuovere widget