Widżety w CMS Total.js: używaj ich na stronie i pisz własne

CMS · cms@8071e48 cmswidgetsrenderclassdata-cms

Widżet to blok, który umieszczasz na stronie: nagłówek, alert, galeria. Niesie własny styl, formularz do konfiguracji w edytorze i opcjonalnie kod renderujący go na serwerze. Widżet to jeden plik HTML, jak komponent Flow, a CMS przechowuje go w swoich metadanych.

Widżet na stronie

W HTML strony widżet to div z dwoma atrybutami:

<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 to <widget id>__<configuration>, gdzie konfiguracja jest obiektem JSON zapisanym przez encodeURIComponent. Zapisuje go edytor; możesz zapisać go sam, gdy generujesz strony.
data-cms-id to identyfikator instancji na stronie.

Gdy strona jest serwowana, CMS usuwa atrybut data-cms, zachowuje HTML w środku i dodaje do head styl każdego widżetu strony. Jeśli widżet nie jest zainstalowany, jego blok jest pomijany.

Części pliku widżetu

Część	Do czego służy
`<script total>`	metadane i kod serwera: `exports.id`, `name`, `author`, `version`, `preview` (obraz lub data URI), `config` (wartości domyślne) i opcjonalnie `dependencies`, `install`, `uninstall` i `render`
`<style>`	CSS widżetu
`<body>`	projekt widżetu, jak pokazuje go edytor; elementy z klasą `CMS_edit` są edytowalne; pozostałe klasy `CMS_*` (`CMS_repeat`, `CMS_remove`, `CMS_unwrap`...) to znaczniki dla edytora, a kompilator usuwa je przed serwowaniem strony
`<settings>`	formularz edytujący `config` w edytorze (wejścia jComponent, których ścieżka zaczyna się od `?.`) i `<script>` z `exports.save(config, el)`, który zmienia projekt, gdy zmienia się konfiguracja
`<template>`	opcjonalny szablon widżetu
`<readme>`	pomoc widżetu

CLASS w stylu, ustawieniach, szablonie i projekcie jest zastępowane klasą należącą do widżetu (w- i jego id), więc dwa widżety nigdy nie dzielą reguły: w widżecie alert .CLASS-color1 staje się .w-alert-color1.

exports.dependencies przyjmuje listę lub ciąg rozdzielony przecinkami: adres kończący się na .js staje się <script src>, a kończący się na .css <link rel="stylesheet">, dodanymi do head strony.

Renderowanie na serwerze

Widżet bez exports.render jest tylko oczyszczany i serwowany tak, jak jest. Z render może zbudować swój HTML z konfiguracji:

<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 to konfiguracja instancji, opt.html to HTML, który był w środku bloku, a opt.id, opt.uid i opt.body go opisują. next(html, replace) podaje HTML do serwowania; z true jako drugim argumentem zastępuje cały blok. Zapisaliśmy ten plik w lokalnym CMS, a strona z data-cms="hello__..." i {"text":"mundo"} wyszła jako <p class="w-hello">Hello MUNDO</p>, z .w-hello{color:#07c} w head. Oficjalny widżet picture używa tej samej funkcji, aby dodać loading="lazy" do swojego obrazu, a code, aby wypisać kod ze swoich ustawień.

exports.install i exports.uninstall uruchamiają się z bazą danych CMS, gdy widżet jest dodawany, zmieniany lub usuwany.

Instalowanie i usuwanie widżetów

Wtyczka Widgets administracji importuje plik; przez API jest to widgets_save z { "html": "<file content>", "singleton": true } (singleton pomija widżet, jeśli już istnieje), widgets_list, widgets_read, widgets_detail i widgets_remove. Wymagają uprawnienia widgets (zobacz API administracji). 43 oficjalne widżety są w repozytorium widżetów.