Moduly - 2. část

O modulech všeobecně

Položili jste si někdy otázku, kolik vlastně Sunlight používá modulů? Jestli ne, tak ta otázka má svoji platnost. Řekněme si tedy, co je to modul. Je to nějaká nabídka, menu v administračním rozhraní. V prvním dílu jsme si ukázali, jak vytvořit položku menu v hlavní administrační liště. Ale když se podíváme do menu Ostatní, v hlavní liště, vidíme tam talačítka s ikonkami. To je také modul, tedy nějaké menu. Dále, když se podíváme do Správy obsahu, zde popravé straně také vidíme nějaká tlačítka s ikonkami. Tak to jsou také menu moduly. Dnes si vyzkoušíme vytvořit takové tlačítko v záložce Ostatní.

Co všechno může obsahovat pole modulů?

Než se pustíme do práce, připomeneme si jeden soubor php, o kterém jsem psal v prvním dílu . Je to soubor modules.php \vaše doména\admin\modules.php. Vysvětlíme si nyní, co znamenají jednotlivé položky pole modulů. Tyto informace se netýkají pouze vytváření tlačítka nějakého menu v hlavní nabídce Ostatní, ale všech modulů, které v Sunlight vytvoříme. To znamená, platí i pro předchozí díl návodu.

Toto je výňatek ze souboru modules.php:

/*
    Array format:

    array(
        module-name => array(
            title                   => module title
            access                  => allow access to current user 1/0

            [script]                => custom path to module script (defaults to "module/*name*.php", false = none)
            [url]                   => custom module URL (defaults to one generated by Router::admin())
            [parent]                => parent module name
            [custom_header] (0)     => disable title and backlink rendering 1/0

            [menu] (false)          => show module in main menu 1/0
            [menu_order] (15)       => main menu order

            [other] (false)         => show module in "other functions" module 1/0
            [other_order] (0)       => order in list of "other functions"
            [other_system] (0)      => show as system module in "other functions" 1/0
            [other_icon]            => path to button icon for this module in "other functions"
        ),
        ...
    )
*/

Vysvětlení jedotlivých položek pole (Array - v php znamená pole) modulů:

module-name - toto je název danného modulu. V základu vidíme v souboru modules.php, že to může být Index (první hlavní stránka v administračním menu), nebo content (To je Správa obsahu), nebo users (Uživatelé a skupiny) a tak podobně až po other (Ostatní).

title - název modulu (menu), který se překládá do všech jazyků. Aby byla vidět např. Správa obsahu, použijeme php kód _lang('admin.menu.content').

access - Přístupová práva, zda toto menu uvidíme, nebo ne. Zde si všimněme jedné variace. U modulu Index je zápis True. Znamená to, že každý přihlášený uživatel SL s přístupem do administrace vždy uvidí Hlavní stránku tohoto rozhraní. Mohlo by tam být také false, to by pak uživatel neviděl. Ale zápis může vypadat i jinak. Pro modul Content nebo další je použit kód User::hasPrivilege('admincontent'). V tom je SL úžasný redakční systém, protože si můžeme nastavit, jaká uživatelská role bude mít přístup do danných položek, extendů a tak podobně. V tomto případě role admincontent umožní přístup so Správy obsahu.

script - Všimněme si, že v souboru modules.php pole modulů neobsahuje tuto položku. To proto, že není potřeba odkazovat na zvláštní výkonný skript php. Ale například v našich pokusech extendů už tuto položku používáme. Není to nic jiného, než nadefinovanná cesta k výkonnému skriptu php, který danný modul ovládá a pracuje s ním. Kód zápisu může vypadat například takto: __DIR__ . '../../../script/content_first_menu.php'. Soubor content_first_menu.php je vlastní výkonný skript php, který pracuje za nás.

url - Php je jazyk, který umožňuje psát odkazy zástupně. Snažím se to nyní vysvětlit laicky. Když budu v html odkazovat na nějaký soubor, např. modul.html, napíši to přesně takto. Aby internetový prohlížeš takový soubor našel a zobrazil. Ale v php se to dá napsat i jinak. A to je obsahem tohoto pole. Využívá třídu Router, aby SL zobrazil danou cestu k nějakému skriptu. Když do url zadám kód Router::admin(‘content-first-menu’), v adresním řádku prohlížeče uvidíme cestu v tomto formátu: http://localhost/admin/index.php?p=content-first-menu. A prohlížeč ví a vidí kam má směřovat a obsah content-first-menu zobrazí.

parent - Toto není nic jiného, než zpětný odkaz. Klikneme si na nějaké menu, tlačítko, někam se dostaneme. Ale chceme zpátky. K tomu slouží link < návrat zpět vlevo nahoře. A položka parent nám to umožní.

custom_header - Tato položka povolí nebo zakáže renderování názvu stránky, nebo backlinku (zpětného odkazu). Pro zápis použijeme True nebo false.

menu - Povolí nebo zakáže zobrazení modulu (menu) v hlavní administrační liště. Opět použijeme True nebo false. Všimněme si, že hlavní položka, např. Content má povoleno menu zobrazit. Ale jeho podmenu, např. content-sort už položku menu neobsahuje. Není tam potřeba. Mi nechceme aby se Řazení stránek zobrazilo, jako hlavní položka administračního menu lišty.

menu_order - Pořadí jednotlivých modulů zobrazených z leva doprava. Index má nulu, Content deset a tak dále. Nemusíme použít jen celé desítkové formáty čísel, ale i například 25, 34 a tak dále.

other - Other, tedy česky Ostatní. Zde prostě zapneme nebo vypneme zobrazení obsahu nějakého extendu nebo menu v záložce Ostatní. Opět pomocí zápisu True nebo false.

other_order - Tak jako u menu_order bylo pořadí v rámci celé administrační lišty, tak zde to je pořadí menu vrámci pouze nabídky Ostatní.

other_system - Povolí, nebo zakáže zobrazení modulu jako systémový v nabídce Ostatní. Opět pomocí zápisu True nebo false. Zde musím podotknout, že v základu SL jsou všechny moduly v nabídce Ostatní vedeny jako systémové. Osobně jsem nepotřeboval tuto funkci používat.

other_icon - Krásná položka pole modulů v nabídce Ostatní, která vám vylepší vzhled tlačítka vloženou ikonou. Zápis pro tuto položku může vypadat např. takto: Router::path('admin/public/images/icons/big-broom.png'). A nebo takto: Router::file(__DIR__ . '/../public/images/icons/big-broom.png').

Tak to je laické vysvětlení jednotlivých položek modulů. Platí pro všechny způsoby použití modulů.

Ukázkový extend pro zobrazení modulu v záložce Ostatní

Je to stejné, jako v prvním dílu o modulech. Vytvořme si tedy extend složku s názvem examplemodul-part2. Opět si v ní vytvoříme soubor plugin.json a vyplníme podobně, jako v minulém díle. Opět připomínám článek od Jirky Daňka Anatomie pluginů .

{
    "$schema": "../../../system/schema/extend.json",
    "name": "Example modul Part 2",
    "description": "Example show Modul - Other admin menu",
    "authors": [
        {"name": "Golfin", "url": "https://github.com/Helwa-Surinen/"}
    ],
    "version": "1.0.0",
    "environment": {
        "system": "^8.3.1"
    },
    "langs": {
        "modulother": "lang"
    },
    "events.admin": [
        {"event": "admin.init", "script": "event/admin/admin_init.php"}
    ]
}

Rozdílnost v plugin.json

name - Jiné pojmenování extendu, v tomto případě Example modul Part 2.

description - Jiný popis pluginu.

langs - Klíč langs má jiný název. Pokud by byl stejný, jako u prvního dílu, tyto dva extendy by se začali hádat a systém by vyhazoval chyby.

lang

Pak si opět vytvoříme novou složku lang, kam vložíme jazykové soubory pro plugin. V plugin.json jsme uvedli, že pro tyto language řetězce budeme používat klíč modulother. Ve složce lang si opět vytvoříme soubory cs.php a en.php. Do nich vložíme následující kód pro cs:

<?php

return [
    // admin
	'module.title.other' => 'Položka v menu Ostatní',
];

A pro anglickou verzi:

<?php

return [
    // admin
	'module.title.other' => 'Example Other menu',
];

event

Opět v našem pluginu vytvoříme složku event. Ve, které si vytvoříme další složku s názvem admin. A v ní vytvoříme nový php soubor admin_init.php. Pozor, tento php skript musíme zaregistrovat v plugin.json. A to následujícím způsobem (mi to tam už máme):

    "events.admin": [
        {"event": "admin.init", "script": "event/admin/admin_init.php"}
    ]

Vidíte, že nám tuto eventu odkazuje do složky admin na soubor admin_init.php.

Vlastní skript, který zobrazí menu v záložce Ostatní

Je to takřka stejné, jako u prvního dílu o modulech. Jen s malými nuancemi.

<?php

use Sunlight\Router;													// odkazujeme na třídu Router pro zobrazení ikony tlačítka menu
use Sunlight\User;														// odkazujeme na třídu user z důvodu acces práv

return function (array $args) {
    $args['admin']->modules['example-modul-other'] = [					// example-modul-other se objeví v adresním řádku prohlížeče
        'title' => _lang('modulother.module.title.other'),					// Název menu v záložce Ostatní
        'parent' => 'other',											// Parent ukazuje, že se má naše menu zobrazit v záložce Ostatní, když je povoleno
        'access' => User::hasPrivilege('adminother'),					// přístupová práva do záložky Ostatní
        'script' => __DIR__ . '../../../script/example-modul-other.php',// cesta k výkonnému skriptu
        'other' => true,												// True povolí zobrazení menu, false zakáže zobrazení menu v záložce Ostatní
        'other_icon' => Router::file(__DIR__ . '../../../public/images/icons/big-cog.png') // nastavená cesta k ikoně tlačítka menu
    ];
};

Složky script a public

Všimli jste si (i u prvního dílu), že v kořenové složce extendu je další adresář script a dnes také public? script Tento adresář obsahuje nějaký php skript, který zobrazí obsah nabídky z Other menu. Vlastně to výkonné a to co chceme aby dělalo. public V tomto případě adresář public používáme pro veřejně přístupné prvky. Mi si zde vytvoříme složku s názvem images, ve které vytvoříme další složku icons. Do té vložíme obrázek ikony pro naše menu Other. Viz zápis v souboru admin-init

'other_icon' => Router::file(__DIR__ . '../../../public/images/icons/big-cog.png') // nastavená cesta k ikoně tlačítka menu

htaccess

Pokud takto spustíme stránky a mrkneme do záložky Ostatní, tlačítko, které jsme si naskriptovali tam uvidéme. Ale pozor, neuvidíme ikonu tlačítka. A to řeší soubor .htaccess. Tento soubor umístíme do adresáře public. A v něm bude následující kód:

<IfModule mod_authz_core.c>
    Require all granted
</IfModule>
<IfModule !mod_authz_core.c>
    Order allow,deny
    Allow from all
</IfModule>

Více o této problematice se dočteme v dokumentaci SL Podpora .htaccess a Public adresář.

Když tedy máme ošetřen soubor .htaccess, ikonka v tlačítku se už ukáže.

Jak vidíte, je to v zásadě zcela stejný postup, jak vytvořit extend. jen s malou korekcí. V tom je CMS Sunlight úžasný systém. Samozřejmě ukázkový extend si můžete opět stáhnout u mě na gitu: ExampleModul.