Τα widgets στο CMS του Total.js: χρησιμοποιήστε τα σε μια σελίδα και γράψτε δικά σας

CMS · cms@8071e48 cmswidgetsrenderclassdata-cms

Ένα widget είναι ένα μπλοκ που τοποθετείτε σε μια σελίδα: μια επικεφαλίδα, μια ειδοποίηση, μια γκαλερί. Φέρει το δικό του στυλ, μια φόρμα για να το ρυθμίσετε στον επεξεργαστή και, προαιρετικά, κώδικα που το αποδίδει στον διακομιστή. Ένα widget είναι ένα αρχείο HTML, όπως μια συνιστώσα του Flow, και το CMS το αποθηκεύει στα μεταδεδομένα του.

Ένα widget μέσα σε μια σελίδα

Στο HTML μιας σελίδας, ένα widget είναι ένα div με δύο χαρακτηριστικά:

<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>, όπου η διαμόρφωση είναι ένα αντικείμενο JSON γραμμένο με encodeURIComponent. Το γράφει ο επεξεργαστής· μπορείτε να το γράψετε κι εσείς όταν δημιουργείτε σελίδες.
Το data-cms-id είναι το αναγνωριστικό της παρουσίας στη σελίδα.

Όταν σερβίρεται η σελίδα, το CMS αφαιρεί το χαρακτηριστικό data-cms, κρατά το HTML που βρίσκεται μέσα και προσθέτει στο head το στυλ κάθε widget της σελίδας. Αν το widget δεν είναι εγκατεστημένο, το μπλοκ του απορρίπτεται.

Τα μέρη ενός αρχείου widget

Μέρος	Σε τι χρησιμεύει
`<script total>`	τα μεταδεδομένα και ο κώδικας του διακομιστή: `exports.id`, `name`, `author`, `version`, `preview` (μια εικόνα ή ένα data URI), `config` (οι προεπιλογές) και προαιρετικά `dependencies`, `install`, `uninstall` και `render`
`<style>`	το CSS του widget
`<body>`	ο σχεδιασμός του widget όπως τον δείχνει ο επεξεργαστής· τα στοιχεία με την κλάση `CMS_edit` είναι τα επεξεργάσιμα· οι άλλες κλάσεις `CMS_*` (`CMS_repeat`, `CMS_remove`, `CMS_unwrap`...) είναι δείκτες για τον επεξεργαστή και ο μεταγλωττιστής τις αφαιρεί πριν σερβιριστεί η σελίδα
`<settings>`	η φόρμα που επεξεργάζεται το `config` στον επεξεργαστή (πεδία εισόδου jComponent των οποίων η διαδρομή ξεκινά με `?.`) και ένα `<script>` με `exports.save(config, el)` που αλλάζει τον σχεδιασμό όταν αλλάζει η διαμόρφωση
`<template>`	ένα προαιρετικό πρότυπο για το widget
`<readme>`	η βοήθεια του widget

Το CLASS στο στυλ, τις ρυθμίσεις, το πρότυπο και τον σχεδιασμό αντικαθίσταται από μια κλάση που ανήκει στο widget (w- ακολουθούμενο από το id του), ώστε δύο widgets να μην μοιράζονται ποτέ κανόνα: στο widget alert, το .CLASS-color1 γίνεται .w-alert-color1.

Το exports.dependencies δέχεται μια λίστα ή μια συμβολοσειρά χωρισμένη με κόμματα: μια διεύθυνση που τελειώνει σε .js γίνεται <script src> και μία που τελειώνει σε .css γίνεται <link rel="stylesheet">, προστιθέμενα στο head της σελίδας.

Απόδοση στον διακομιστή

Ένα widget χωρίς exports.render απλώς καθαρίζεται και σερβίρεται όπως είναι. Με render μπορεί να χτίσει το HTML του από τη διαμόρφωση:

<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 είναι η διαμόρφωση της παρουσίας, το opt.html το HTML που ήταν μέσα στο μπλοκ και τα opt.id, opt.uid και opt.body το περιγράφουν. Το next(html, replace) δίνει το HTML που θα σερβιριστεί· με true ως δεύτερο όρισμα αντικαθιστά ολόκληρο το μπλοκ. Αποθηκεύσαμε αυτό το αρχείο σε ένα τοπικό CMS και μια σελίδα με data-cms="hello__..." και {"text":"mundo"} βγήκε ως <p class="w-hello">Hello MUNDO</p>, με .w-hello{color:#07c} στο head. Το επίσημο widget picture χρησιμοποιεί την ίδια συνάρτηση για να προσθέσει loading="lazy" στην εικόνα του και το code για να εκτυπώσει τον κώδικα από τις ρυθμίσεις του.

Τα exports.install και exports.uninstall εκτελούνται με τη βάση δεδομένων του CMS όταν το widget προστίθεται, αλλάζει ή αφαιρείται.

Εγκατάσταση και αφαίρεση widgets

Το πρόσθετο Widgets της διαχείρισης εισάγει ένα αρχείο· μέσω του API είναι το widgets_save με { "html": "<file content>", "singleton": true } (το singleton παραλείπει το widget αν υπάρχει ήδη), widgets_list, widgets_read, widgets_detail και widgets_remove. Χρειάζονται το δικαίωμα widgets (δείτε το API διαχείρισης). Τα 43 επίσημα widgets βρίσκονται στο αποθετήριο widgets.