Motivy

Motivy jsou jedním z možných typů pluginu. Jsou to podadresáře v plugins/templates/.

Prázdný motiv

Systém ve výchozím stavu obsahuje motiv s názvem Blank. Je to motiv s minimálními styly ze kterého se dá vycházet při tvorbě vlastního motivu.

Struktura motivu

Šablona

Soubor template.php (a případně další šablony uvedené v layouts) slouží k vykreslení struktury a obsahu těla stránky.

Úplně minimální šablona by mohla vypadat nějak takto:

<?php use Sunlight\Template; ?>

<?= Template::content() ?>

Pomocí třídy Template je možné vykreslit jednotlivé sekce stránky.

Metoda Popis
Template::content() Vykreslit obsah stránky.
Template::boxes('slot')

Vykreslit boxy pro daný slot.

Možné sloty se definují v plugin.json v layouts. Viz také další nastavení boxů.

Template::heading() Vykreslit titulek stránky (<h1>).
Template::backlink() Vykreslit zpětný odkaz (návrat zpět).
Template::links()

Vykreslit odkazy motivu.

Metodě je možné předat pole s následujícími klíči:

  • cms - vykreslit odkaz na web SunLight CMS
    • true - ano (výchozí)
    • false - ne
  • admin - vykreslit odkaz na administraci
    • true - vždy
    • false - nikdy
    • null - pokud má uživatel právo (výchozí)
<ul>
    <?= Template::links(['admin' => false]) ?>
</ul>
Template::asset() Sestavit URL k souboru motivu.
<?= _e(Template::asset('images/logo.jpg')) ?>
Template::menu()

Vykreslit menu.

<?= Template::menu() ?>

Pomocí argumentů je možné definovat rozsah pořadí a definovat class:

<?= Template::menu(0, 10, 'main-menu') ?>
Template::treeMenu()

Vykreslit stromové menu.

<?= Template::treeMenu(['css_class' => 'tree-menu']) ?>

Pomocí pole je možné předat více nastavení:

  • page_id - ID stránky, pro kterou se má menu vykreslit (-1 = aktuální)
  • children_only - vykreslit pouze potomky stránky (true/false)
  • max_depth - maximální hloubka stromu
  • ord_start - limit pořadí od
  • ord_end - limit pořadí do
  • css_class - vlastní CSS třída

(Pokročilejší možnosti jsou popsány v dokumentaci metody ve zdrojovém kódu.)
Template::breadcrumbs()

Vykreslit drobečkovou navigaci.

<?= Template::breadcrumbs() ?>

Pomocí argumentů lze předat vlastní drobečky (seznam polí s klíči "title" a "url") a vypnout drobečky, pokud je pouze jeden:

<?= Template::breadcrumbs([], true) ?>
Template::userMenu()

Vykreslit uživatelské menu.

<?= Template::userMenu() ?>

Pomocí argumentů je možné vypnout odkaz na profil a odkaz do administrace:

<?= Template::userMenu(false, false) ?>
Template::title() Vykreslit titulek aktuální stránky.
Template::siteTitle() Vykreslit titulek stránek.
Template::siteDescription() Vykreslit popis stránek.
Template::siteUrl()

Vykreslit absolutní URL ke hlavní stránce.

<?= _e(Template::siteUrl()) ?>
Template::sitePath()

Vykreslit cestu ke hlavní stránce.

<?= _e(Template::sitePath()) ?>
Template::currentID() Vrátí ID aktuální stránky nebo null.
Template::currentIsPage() Vrátí true, pokud je aktuální obsah typu "stránka", jinak false.
Template::currentIsArticle() Vrátí true, pokud je aktuální obsah typu "článek", jinak false.
Template::currentIsTopic() Vrátí true, pokud je aktuální obsah typu "topic", jinak false.
Template::currentIsModule() Vrátí true, pokud je aktuální obsah typu "modul", jinak false.
Template::currentIsIndex() Vrátí true, pokud je aktuální obsah typu "hlavní strana", jinak false.

plugin.json

Seznam klíčů, které můžou být uvedeny v plugin.json. Klíče označeny "*" jsou povinné.

Hlavní nastavení pluginu
Klíč Typ Popis
$schema string

Cesta k JSON schématu. Pomáhá editorům v napovídání klíčů a validaci plugin.json. Nepovinné. 

"$schema": "../../../system/schema/template.json"
name string Čitelný název pluginu.
description string Stručný popis pluginu.
authors object[]

Seznam autorů pluginu.
Klíče "name" a "url" je možné libovolně kombinovat. 

"authors": [
    {"name": "Author1", "url": "https://example.com/"},
    {"name": "Author2"},
    {"url": "https://example.com/"}
]
version string Verze pluginu. Např. "1.0.0".
environment object Prostředí vyžadované pluginem.
  • system - požadovaná verze systému (viz formát)
  • php - požadovaná verze PHP (viz formát)
  • php_extensions - požadované PHP rozšíření
  • debug - požadovaný debug mód
    • true - plugin aktivní pouze v debug režimu
    • false - plugin aktivní pouze mimo debug režim
    • null - plugin vždy aktivní
Příklad: 
"environment": {
    "system": "~8.0.2",
    "php": ">=7.4",
    "php_extensions": ["curl", "iconv"],
    "debug": null
}
Nastavení motivu
Klíč Typ Popis
layouts object

Mapa možných variant motivu.

  • layout "default" musí být definován
  • layouty je možné přiřazovat ke stránkám
  • sloty slouží k přiřazování boxů na místa v dané šabloně
  • layouty i sloty by měly mít definovány popisky ve slovníku, viz lang_dir
"layouts": {
    "default": {
        "template": "template.php",
        "slots": ["right"]
    }
}

Viz také popis možného obsahu šablony.

css string[] CSS soubory motivu. Ve výchozím stavu je vložen pouze soubor style.css. 
"css": [
    "style.css",
    "another-style.css"
]
js string[] JavaScript soubory motivu. 
"js": [
    "template.js",
    "another-script.js"
]
responsive bool Pokud je nastaveno na true, je do hlavičky automaticky vložen následující meta tag: 
<meta name="viewport" content="width=device-width, initial-scale=1">
dark bool

Pokud je nastaveno na true, je motiv považován za tmavý. Pro tmavé motivy se používá tmavé téma lightboxu. Výchozí stav je false.

bbcode.buttons bool

Zobrazit BBCode tlačítka při psání příspěvků a komentářů. Výchozí stav je true.

box.parent string

Název tagu, který obalí boxy. Výchozí je "" (vypnuto).

box.item string

Název tagu, který obalí jednotlivé boxy. Výchozí je "div".

box.title string

Název tagu, který obalí titulek boxu. Výchozí je "h3".

box.title.inside bool

Příznak, zda má být titulek uvnitř boxu nebo před ním. Výchozí je false (titulek je před boxem).

lang_dir string

Název adresáře, kde jsou umístěny popisky layoutů a slotů. Výchozí je "labels".

Příklad pro české popisky layoutů (v souboru labels/cs.php): 
<?php

return array(
    'default.label' => 'výchozí',
    'default.slot.right' => 'pravý sloupec',
);

Pokud je váš motiv určen pro širší distribuci, je doporučeno mít popisky alespoň v češtině (cs.php) a angličtině (en.php).

events object[]

Seznam událostí, které motiv zpracovává.

Viz dokumentace callbacků pro více informací o specifikaci callbacků. 

"events": [
    {"event": "tpl.title", "script": "event/title.php"}
]

Klíč "event" specifikuje název události, na který se má callback napojit. Tyto listenery se registrují až těsně před vykreslením motivu, jsou tedy vhodné primárně pro zpracování událostí motivu.

Pokročilé nastavení pluginu
Klíč Typ Popis
dependencies object

Mapa pluginů, na kterých tento plugin závisí a jejich požadovaných verzí (viz formát).

Názvy pluginů jsou ve formátu typ/název, případně pouze název - v takovém případě se předpokládá template. 

"dependencies": {
    "extend/some-plugin": "^1.0",
    "another-plugin": "*"
}
installer string

Relativní cesta ke skriptu, který vrátí instalátor pluginu.

Poznámka: Instalátor se spouští během načítání pluginů a nejsou tedy dostupné ostatní pluginy ani autoloading class samotného pluginu. 

"installer": "installer.php"

Příklad instalátoru:

<?php

use Sunlight\Plugin\PluginInstaller;
use Sunlight\Database\Database as DB;

return new class extends PluginInstaller {
    protected function verify(): bool
    {
        return empty(
            $this->checkTables([
                DB::table('example'),
            ])
        );
    }

    protected function doInstall(): void
    {
        $this->loadSqlString(<<<'SQL'
            CREATE TABLE `sunlight_example` (
                `id` int NOT NULL AUTO_INCREMENT PRIMARY KEY,
                `title` varchar(255) NOT NULL
            ) ENGINE='InnoDB';
        SQL);
    }

    protected function doUninstall(): void
    {
        $this->dropTables([
            DB::table('example'),
        ]);
    }
};
autoload object

Dodatečné nastavení autoloadingu ve stejném formátu, jako má Composer. Viz dokumentace.

  • jsou podporovaný pouze klíče "psr-0", "psr-4" a "classmap"
  • každý plugin má automaticky nastaven PSR-4 autoloading do svého class podadresáře
  • composer závislosti mohou být načteny automaticky, viz klíč inject_composer
  • namespace pluginu je řízen pomocí klíče namespace
class string

Název vlastní třídy pluginu.

  • pokud není uveden jiný namespace, je před název třídy automaticky přidán plugin namespace
  • vlastní třída musí dědit Sunlight\Plugin\TemplatePlugin
namespace string

Namespace pluginu.

Pokud není uveden žádný namespace, je vytvořen z kombinace SunlightTemplate a názvu pluginu převedeného na CamelCase. Např. pro plugin template/my-plugin bude namespace SunlightTemplate\MyPlugin

inject_composer bool

Povolit automatickou integraci Composer závislostí pluginu. Výchozí stav je true.

  • pokud je integrace povolena a v adresáři pluginu existuje composer.json, budou do autoloadingu přidány i tyto závislosti
  • s pluginem je potřeba distribuovat i vendor adresář, případně před použitím pluginu spustit composer install v jeho adresáři
  • pokud stejnou závislost poskytuje více pluginů, je preferována její nejnovější možná verze
  • systémové závislosti není možné nahradit
actions object

Vlastní akce pluginu, které je možné spouštět v administraci ve správě rozšíření. 

"actions": {
    "custom-action": "CustomActionClass"
}
  • třída akce musí dědit Sunlight\Plugin\Action\PluginAction
  • pokud není uveden jiný namespace, je před název třídy automaticky přidán plugin namespace
config_defaults object

Výchozí nastavení pluginu. 

"config_defaults": {
    "example_toggle": true,
    "example_string": "hello world!"
}
  • uvedením výchozí konfigurace se aktivuje akce Konfigurovat u daného pluginu v administraci
  • výchozí implementace akce umí editovat pouze boolean a textové hodnoty
  • implementaci akce je možné přetížit definováním vlastní akce s názvem "config" v actions
  • konfigurace se ukládá do souboru config.php v adresáři pluginu
extra object

Extra nastavení pluginu pro účely jiných pluginů.

Je možné k nim přistupovat pomocí metody getExtraOption() na instanci daného pluginu.