Tworzenie prostego modułu

This page is a translated version of the page J4.x:Creating a Simple Module and the translation is 100% complete.

Other languages:

Deutsch • ‎English • ‎Nederlands • ‎français • ‎italiano • ‎polski • ‎português • ‎Ελληνικά • ‎русский

Joomla!

4.x

>Samouczek

Tworzenie prostego modułu dla Joomla 4.x

Samouczek o tym jak stworzyć prosty moduł dla Joomla w wersji 4x.

Wprowadzenie

Joomlaǃ 4 proponuje pięć typów rozszerzeńː

Komponenty
Komponent jest głównym elementem witryny. Zajmuje się przetwarzaniem danych, a także wprowadzaniem i przechowywaniem ich w bazie danych. Komponent w znacznej części witryn jest ich główną treścią.
Moduły
Moduł jest dodatkiem do witryny, który rozszerza jej funkcjonalność. Moduł zazwyczaj jest drugorzędnym elementem strony i nie jest uważany za główną część jej funkcjonowania. Może on być widoczny w różnych pozycjach, można również zaznaczyć, na których aktywnych stronach menu ma być wyświetlany. Moduły są lekkimi i elastycznymi rozszerzeniami. Są one używane dla małych fragmentów witryny, które na ogół są mniej złożone i mogą być widoczne na różnych elementach.
Wtyczki
Wtyczka operuje danymi wyjściowymi, które są już generowane przez system. Zazwyczaj nie jest ona uruchamiana jako oddzielna część witryny. Pobiera ona dane z innych źródeł (np. treści) i manipuluje tymi danymi przed ich wyświetleniem. Wtyczka zazwyczaj działa za kulisami.
Języki
Język jest najprawdopodobniej najprostszym rozszerzeniem Joomla!. W zasadzie pliki pakietów językowych składają się z pary klucz/wartość, które zapewniają tłumaczenie statycznych ciągów tekstowych, przypisanych w kodzie źródłowym Joomla!
Szablony
Szablon w zasadzie określa wygląd strony internetowej Joomla!

Joomla! 4 jest skonstruowana przy użyciu pięciu różnych aplikacji:

Instalacja (służy do instalacji Joomla, musi być usunięta po zakończeniu instalacji);
Administrator (backend - służy do zarządzania treścią);
Witryna (frontend - używany do wyświetlania treści);
CLI (używany do uzyskania dostępu do Joomli w wierszu poleceń i do zadań crona);
API (usługi internetowe - wykorzystywane do tworzenia interfejsów API dla treści dostępnych maszynowo);

Aplikacja instalacyjna jest używana raz. Administrator oraz witryna używane są poprzez zastosowanie komponentów wraz z modułami. Każdy moduł posiada pojedynczy punkt dostępu umieszczony w katalogu modules i analogicznie administrator/modules. Punkt ten nosi nazwę mod_nazwamodułu/mod_nazwamodułu.php (prefiks mod_ jest zapisem umownym). Punktem wejściowym dla modułu logowania jest dla przykładu /mod_login/mod_login.php.

Wymagania

Potrzebujesz pakietu instalacyjnego Joomla! 4.x dostępnego dla tego samouczka? (W tym miejscu pobierzesz najnowszą wersję).

Możesz również pobrać Joomla! 4 pod adresem GitHub, na Stronie deweloperskiej lub możesz stworzyć darmową stronę internetową pod adresem https://launch.joomla.org.

Tworzenie prostego modułu, rozwijanie modułu podstawowego - Część 1

W standardowej instalacji Joomla! można zobaczyć wiele przykładów modułów. Na przykład:

Menu
Najnowsze wiadomości
Formularz logowania
i wiele innych...

Ten samouczek wyjaśni jak stworzyć prosty moduł. Poznasz podstawową strukturę plików modułu Joomlaǃ 4. Ta podstawowa struktura może być następnie rozszerzona w celu stworzenia bardziej rozbudowanych modułów.

Struktura plików

Istnieje kilka podstawowych plików, które są wykorzystywane w standardowym schemacie tworzenia modułów:

mod_foo.php - plik ten jest głównym punktem wejściowym dla modułu. Będzie on wykonywał wszelkie niezbędne procedury inicjalizacyjne, procedury wywoływania helpera w celu zebrania wszelkich niezbędnych danych oraz będzie zawierał szablon, który wyświetli wyjście modułu.
mod_foo.xml - plik ten zawiera informacje o module. Określa on pliki, które muszą być zainstalowane przez instalator Joomla!, określa także parametry konfiguracyjne modułu.
tmpl/default.php - to jest szablon modułu. Plik ten pobierze dane zebrane przez mod_foo.php i wygeneruje HTML, który zostanie wyświetlony na stronie.
language/pl-PL/mod_foo.ini oraz language/pl-PL/mod_foo.sys.ini- są to pliki językowe, które zawierają tekst w języku angielskim.

Tworzenie mod_foo.php

Plik mod_foo.php będzie wykonywał następujące zadania:

Zaimportuje klasę ModuleHelper do bieżącego obszaru. Będziemy potrzebować jej później do wyświetlenia wyjścia.
Dołączy szablon do wyświetlania wyjścia.

Klasa ModuleHelper jest importowana do naszego bieżącego obszaru na początku pliku.

use Joomla\CMS\Helper\ModuleHelper;

Na końcu dołączamy szablon do wyświetlenia wyjścia poprzez

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

Kompletny plik mod_foo.php

Kompletny plik mod_foo.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

Uwagaː w Joomla 3x zazwyczaj używa się linii $moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));. Nie potrzebujesz już tego. Zobacz ten Pull-Requestː https://github.com/joomla/joomla-cms/pull/17447.

Linią, której do tej pory nie wyjaśniliśmy, jest pierwsza linia defined('_JEXEC') or die;. Linia sprawdza, czy plik ten jest dołączany z aplikacji Joomla. Jest to konieczne, aby zapobiec wstrzyknięciu zmiennej i innym potencjalnym problemom związanym z bezpieczeństwem.

Tworzenie tmpl/default.php

Plik default.php jest szablonem, który wyświetla wyjście modułu.

Kompletny plik tmpl/default.php

Kod w pliku tmpl/default.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

Ważną kwestią jest to, że plik szablonu ma taki sam zakres jak plik mod_foo.php. Oznacza to, że zmienna zdefiniowana w pliku mod_foo.php może być następnie użyta w pliku szablonu bez żadnych dodatkowych deklaracji czy wywołań funkcji.

Tworzenie mod_foo.xml

Plik mod_foo.xml jest plikiem instalacyjnym. Większość wpisów jest oczywista.

Kompletny plik mod_foo.xml

Kod w pliku mod_foo.xml wygląda następująco:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
    <name>MOD_FOO</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <version>1.0</version>
    <description>MOD_FOO_XML_DESCRIPTION</description>
    <files>
        <filename module="mod_foo">mod_foo.php</filename>
        <folder>tmpl</folder>
        <folder>language</folder>
        <filename>mod_foo.xml</filename>
    </files>
</extension>

Tworzenie plików językowych

Pliki language/pl-PL/mod_foo.ini oraz language/pl-PL/mod_foo.sys.ini są używane do tłumaczenia tekstu w witrynie i na zapleczu. Należy pamiętać, że struktura plików językowych została zaktualizowana w Joomla 4, a prefiksy językowe na poszczególnych plikach w folderze językowym nie są już wymagane.

Kod dla language/pl-PL/mod_foo.sys.ini jest następujący:

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

Kod dla language/pl-PL/mod_foo.ini jest następujący:

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

Plik .sys.ini jest używany do tłumaczenia opisu rozszerzenia podczas instalacji, podczas gdy plik .ini jest używany do tłumaczenia pozostałych łańcuchów i opisu podczas korzystania z Twojego rozszerzenia.

Więcej informacji na temat plików językowych można znaleźć w tym miejscu.

Przetestuj swój moduł

Teraz możesz spakować wszystkie pliki i zainstalować je za pomocą Joomla Extension Manager.
Następnie wybierz swój moduł w menedżerze modułów, oraz wyświetl na jakich stronach ma się wyświetlać.

Na następnym obrazku możesz zobaczyć jak powinien wyglądać utworzony przez Ciebie moduł na wybranej stronie.

Wniosek

Opracowanie prostego modułu dla Joomli jest dość łatwym procesem. Przy użyciu technik opisanych w tym samouczku można bez trudu opracować nieskończoną ilość modułów.

Schematy kodu możesz znaleźć w tym miejscu:

https://github.com/joomla-extensions/boilerplate/tree/master/module

Przykładowe pliki tego samouczka można znaleźć na stronie w tym miejscuː.

https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

Dodanie klasy pomocniczej przy użyciu przestrzeni nazw - Część 2

Wymagania

Potrzebujesz aktualnej Joomli! 4.x dla tego samouczka (na dzień dzisiejszy Joomla! 4.0.0-alpha6-dev)

Przestrzenie nazw

Przestrzenie nazw pojawiły się wraz z PHP 5.3 niejako naturalnie. W innych językach programowania, przez długi czas były już używane. Te małe struktury pomagają w utrzymywaniu przejrzystości naszego kodu.

Przestrzenie nazw to odrębne obszary, w których mogą funkcjonować pewne rzeczy logiczne (w naszym przypadku klasy, interfejsy, funkcje i stałe). Obszary te zapewniają hermetyzację kodu i zapobiegają konfliktom nazw.

Przyjrzyjmy się, jak ich używać w Joomla 4. Używamy do tego pliku pomocniczego.

Struktura plików

Stworzymy lub zmienimy następujące pliki:

Helper/FooHelper.php - To jest plik, którego używamy tutaj jako przykład. Musimy go stworzyć.
mod_foo.php - W tym pliku będziemy głównie ładować przestrzeń nazw.
tmpl/default.php - W tym pliku pokażemy, jak można wyświetlić dane helpera.
mod_foo.xml - Tworzymy nowy katalog z nowym plikiem. Musi on zostać zainstalowany podczas instalacji. W tym celu musimy je określić w tym pliku.

Tworzenie Helper/FooHelper.php

Nasza nowa klasa pomocnicza powinna należeć do przestrzeni nazw. Osiągamy to za pomocą poniższego kodu. Ważne jest, aby ta linia znajdowała się na początku pliku.

namespace Joomla\Module\Foo\Site\Helper;

Następnie tworzymy prostą klasę za pomocą prostej metody. Oczywiście można tu zrobić o wiele więcej. Spójrz na metody rdzenne Joomla. Oto wiele przykładów. Pokazują one z pierwszej ręki, jakie masz opcje.

Kompletny plik Helper/FooHelper.php

Kompletny plik FooHelper.php wygląda następująco:

<?php
/**
 * @package     Joomla.Site
 * @subpackage  mod_foo
 *
 * @copyright   Copyright (C) 2005 - 2019 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later; see LICENSE.txt
 */

namespace Joomla\Module\Foo\Site\Helper;

// No direct access to this file
defined('_JEXEC') or die;

/**
 * Helper for mod_foo
 *
 * @since  4.0
 */
class FooHelper
{
	/**
	 * Retrieve foo test
	 *
	 * @param   Registry        $params  The module parameters
	 * @param   CMSApplication  $app     The application
	 *
	 * @return  array
	 */
	public static function getText()
	{
		return 'FooHelpertest';
	}
}

Edycja mod_foo.php

Nasza nowa klasa pomocnicza jest importowana do bieżącego obszaru na początku pliku.

use Joomla\Module\Foo\Site\Helper\FooHelper;

Na koniec użyj pliku pomocniczego do testowania, jeśli jest poprawnie załadowany:

$test  = FooHelper::getText($params, $app);

Kompletny plik mod_foo.php

Kompletny plik mod_foo.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test  = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

Edycja tmpl/default.php

W tym pliku dokonujesz tylko małej zmiany, aby zademonstrować na stronie, że twój plik pomocniczy działa poprawnie. Wartość zmiennej dodaje się tylko na końcu bieżącego kodu.

echo '[PROJECT_NAME]' . $test;

Kompletny tmpl/default.php

Kompletny plik tmpl/default.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

echo '[PROJECT_NAME]' . $test;

Edycja mod_foo.xml

Najpierw musisz dodać linię, aby przestrzeń nazw była ustawiona automatycznie w Joomla. Po tej zmianie, musisz ponownie zainstalować swój moduł. Prosta zmiana w zainstalowanym już module nie wystarczy. Jeśli tworzysz lokalnie, możesz również usunąć pliki libraries/autoload_psr4.php zostaną one automatycznie odtworzone. Po wstawieniu i zainstalowaniu, przestrzeń nazw jest rozpoznawana przez program ładujący JPATH_LIBRARIES . '/autoload_psr4.php'.

<namespace>Joomla\Module\Foo</namespace>

Joomla! powinna skopiować twój plik pomocniczy podczas instalacji modułu. Więc musi najpierw znaleźć ten plik. W tym celu należy dodać następujący wiersz do pliku XML.

<folder>Helper</folder>

Kompletny mod_foo.xml

Kompletny plik mod_foo.xml wygląda następująco:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
    <name>MOD_FOO</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <version>1.0</version>
    <description>MOD_FOO_XML_DESCRIPTION</description>
    <namespace>Joomla\Module\Foo</namespace>
    <files>
        <filename module="mod_foo">mod_foo.php</filename>
        <folder>tmpl</folder>
        <folder>Helper</folder>
        <folder>language</folder>
        <filename>mod_foo.xml</filename>
    </files>
</extension>

Przetestuj swój moduł

Teraz możesz spakować wszystkie pliki i zainstalować je za pomocą Joomla Extension Manager. Następnie wybierz swój moduł w menedżerze modułów, oraz wyświetl na jakich stronach ma się wyświetlać.

Na stronie widać twój moduł jak na poniższym obrazku. Zostanie wyświetlony tekst z pliku pomocniczego.

Wniosek

Jak widać, jak już się trochę zagłębimy w przestrzenie nazw, nie są one już tak skomplikowane. W dużych projektach mogą one przynieść wiele korzyści. Należy jednak odpowiednio planować przestrzenie nazw, gdyż w przeciwnym razie szybko stanie się to bardziej pracochłonne.

Schematy kodu możesz znaleźć w tym miejscu:

https://github.com/joomla-extensions/boilerplate/tree/master/module

Przykładowe pliki tego samouczka można znaleźć na stronie w tym miejscuː.

https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

Konfiguracjaː dodawanie parametrów poprzez pola formularza - Część 3

Wymagania

Potrzebujesz aktualnej Joomli! 4.x dla tego samouczka (na dzień dzisiejszy Joomla! 4.0.0-alpha6-dev)

Konfigurowanie za pomocą pól i parametrów formularza

Pola formularzy dają wiele możliwości dostosowywania w Joomla, a dla modułów są jedynym sposobem na to, aby użytkownik mógł dostosować moduł do potrzeb swojej witryny.

W tym przypadku zamierzamy rozszerzyć nasz poprzedni przykład o pole adresu URL do wstawienia domeny, której możemy użyć jako linku w interfejsie. Aby to się stało, użyjemy typu URL Form Field.

Następnie wstawiamy parametry pozwalające na korzystanie ze standardowych funkcjonalności Joomla.

Przyjrzyjmy się, jak ich używać w Joomla 4.

Struktura plików

Zmienimy następujące pliki:

mod_foo.xml - to jest plik, w którym dodajemy pola.
tmpl/default.php - w tym pliku możemy zademonstrować, w jaki sposób można wykorzystać dane pola.
language/pl-PL/mod_foo.ini - tutaj używamy ciągu językowego, aby pole mogło być poprawnie oznaczone w różnych językach.

Edycja mod_foo.xml

Najpierw ustawiamy parametr niestandardowy.

<field
    name="domain"
    type="url"
    label="MOD_FOO_FIELD_URL_LABEL"
    filter="url"
/>

Następnie wstawiamy domyślne pola Joomla, tak abyśmy mogli korzystać z pamięci podręcznej, moduleclass-suffix oraz układów.

<field
    name="layout"
    type="modulelayout"
    label="JFIELD_ALT_LAYOUT_LABEL"
    class="custom-select"
/>

<field
    name="moduleclass_sfx"
    type="textarea"
    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
    rows="3"
/>

<field
    name="cache"
    type="list"
    label="COM_MODULES_FIELD_CACHING_LABEL"
    default="0"
>
    <option value="1">JGLOBAL_USE_GLOBAL</option>
    <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
    name="cache_time"
    type="number"
    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
    default="0"
/>

<field
    name="cachemode"
    type="hidden"
    default="itemid"
>
    <option value="itemid"></option>
</field>

Kompletny mod_foo.xml

Kompletny plik mod_foo.xml wygląda następująco:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
    <name>MOD_FOO</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <version>1.0</version>
    <description>MOD_FOO_XML_DESCRIPTION</description>
    <namespace>Joomla\Module\Foo</namespace>
    <files>
        <filename module="mod_foo">mod_foo.php</filename>
        <folder>tmpl</folder>
        <folder>Helper</folder>
        <folder>language</folder>
        <filename>mod_foo.xml</filename>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="domain"
                    type="url"
                    label="MOD_FOO_FIELD_URL_LABEL"
                    filter="url"
                />
            </fieldset>
            <fieldset name="advanced">
                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    class="custom-select"
                />
                <field
                    name="moduleclass_sfx"
                    type="textarea"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    rows="3"
                />
                <field
                    name="cache"
                    type="list"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    default="0"
                >
                    <option value="1">JGLOBAL_USE_GLOBAL</option>
                    <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>
                <field
                    name="cache_time"
                    type="number"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    default="0"
                />
                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid"
                >
                    <option value="itemid"></option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Edycja tmpl/default.php

Wartość parametru możemy wykorzystać do utworzenia hiperłącza na stronie. Dostęp do wartości możemy uzyskać poprzez zmienną $params.

$domain = $params->get('domain', 'https://www.joomla.org');

Wartość tę wykorzystamy później do utworzenia hiperłącza.

<a href="<?php echo $domain; ?>">
	<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

Kompletny plik tmpl/default.php

Kompletny plik tmpl/default.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
	<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

Edycja language/pl-PL/mod_foo.ini

Tutaj możemy określić tekst dla polskiej wersji etykiety pola.

MOD_FOO_FIELD_URL_LABEL="Url"

Kompletny language/pl-PL/mod_foo.ini

Kompletny plik language/en-GB/mod_foo.ini wygląda następująco:

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

Przetestuj swój moduł

Teraz możesz spakować wszystkie pliki i zainstalować je za pomocą Joomla Extension Manager. Następnie wybierz swój moduł w menedżerze modułów, oraz wyświetl na jakich stronach ma się wyświetlać.

Na zapleczu zobaczysz swój moduł, tak jak pokazano na poniższym obrazku.

W karcie podstawowej zobaczysz niestandardowe pole, w którym możesz wstawić domenę. Tekst etykiety jest pobierany z pliku językowego.

W zakładce zaawansowane, zobaczysz wszystkie domyślne opcje z wyjątkiem trybu pamięci podręcznej, ponieważ jest to pole ukryte.

W interfejsie zobaczysz swój moduł, tak jak pokazano na poniższym obrazku. Zostanie wyświetlony tekst z pliku pomocniczego i powinieneś zobaczyć hiperłącze.

Wniosek

Pola formularza dają użytkownikowi łatwy sposób dostosowania modułu do ustawień witryn. Pozwala to na zwiększenie możliwości modułów.

Schematy kodu możesz znaleźć w tym miejscu:

https://github.com/joomla-extensions/boilerplate/tree/master/module

Przykładowe pliki tego samouczka można znaleźć na stronie w tym miejscuː.

https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

Zobacz ten problem, aby zapoznać się z możliwymi przyszłymi zmianami:

https://github.com/joomla/joomla-cms/pull/23553

Użycie skryptu instalacji, aktualizacji i deinstalacji - część 4

Wymagania

Potrzebujesz aktualnej Joomli! 4.x dla tego samouczka (na dzień dzisiejszy Joomla! 4.0.0-alpha6-dev)

Skrypty

Instalowanie, aktualizowanie i odinstalowywanie modułu może wymagać dodatkowych operacji, których nie da się zrealizować za pomocą podstawowych operacji opisanych w głównym pliku XML. Joomla oferuje nowe podejście do rozwiązania tego problemu. Polega ono na wykorzystaniu pliku skryptu PHP zawierającego klasę wykorzystującą pięć metod:

inspekcja wstępna, która jest wykonywana przed instalacją i aktualizacją
instalacja
aktualizacja
dezinstalacja
inspekcja końcowa, która jest wykonywana po instalacji i aktualizacji

Przyjrzyjmy się, jak ich używać w Joomla 4. Używamy do tego pliku pomocniczego.

Struktura plików

Stworzymy lub zmienimy następujące pliki:

script.php - to jest plik, którego używamy tutaj jako przykładu. Musimy go utworzyć.
language/pl-PL/mod_foo.sys.ini - w tym pliku dodamy tekst.
mod_foo.xml - tworzymy nowy plik. Należy go dodać podczas instalacji. W tym celu musimy określić to w tym pliku.

Tworzenie script.php

Napisanie skryptu rozszerzającego polega na zadeklarowaniu klasy o nazwie mod_ModuleNameInstallerScript z użyciem tych 5 metod. Więcej informacji można znaleźć w komentarzach w pliku. W tych komentarzach wyjaśniam, kiedy wywoływana jest metoda.

W tym przykładzie używam tylko tekstu, aby pokazać, która metoda zostanie wykonana. Dodatkowo pokażę Ci, jak sprawdzić minimalne wymagania. Oczywiście możesz zrobić znacznie więcej. Na przykład możesz usunąć pliki, które nie są już potrzebne w nowej wersji modułu. Można to zobaczyć w pliku. Innym pomysłem na ten plik jest utworzenie przykładowej treści, pokazanie komunikatu o powodzeniu z aktualnym numerem zainstalowanej wersji lub przekierowanie po udanej instalacji na stronę z ustawieniami modułu.

Kompletny script.php

Kompletny plik script.php wygląda następująco:

<?php
/**
 * @package    [PACKAGE_NAME]
 *
 * @author     [AUTHOR] <[AUTHOR_EMAIL]>
 * @copyright  [COPYRIGHT]
 * @license    GNU General Public License version 2 or later; see LICENSE.txt
 * @link       [AUTHOR_URL]
 */

// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
 * Script file of Foo module
 */
class mod_fooInstallerScript {

    /**
     * Extension script constructor.
     *
     * @return  void
     */
    public function __construct() {
        $this->minimumJoomla = '4.0';
        $this->minimumPhp = JOOMLA_MINIMUM_PHP;
    }

    /**
     * Method to install the extension
     *
     * @param   InstallerAdapter  $parent  The class calling this method
     *
     * @return  boolean  True on success
     */
    function install($parent) {
        echo Text::_('MOD_FOO_INSTALLERSCRIPT_INSTALL');

        return true;
    }

    /**
     * Method to uninstall the extension
     *
     * @param   InstallerAdapter  $parent  The class calling this method
     *
     * @return  boolean  True on success
     */
    function uninstall($parent) {
        echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

        return true;
    }

    /**
     * Method to update the extension
     *
     * @param   InstallerAdapter  $parent  The class calling this method
     *
     * @return  boolean  True on success
     */
    function update($parent) {
        echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

        return true;
    }

    /**
     * Function called before extension installation/update/removal procedure commences
     *
     * @param   string            $type    The type of change (install, update or discover_install, not uninstall)
     * @param   InstallerAdapter  $parent  The class calling this method
     *
     * @return  boolean  True on success
     */
    function preflight($type, $parent) {
        // Check for the minimum PHP version before continuing
        if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
            Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

            return false;
        }

        // Check for the minimum Joomla version before continuing
        if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
            Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

            return false;
        }
        
        echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
        echo $this->minimumJoomla . ' ' . $this->minimumPhp;

        return true;
    }

    /**
     * Function called after extension installation/update/removal procedure commences
     *
     * @param   string            $type    The type of change (install, update or discover_install, not uninstall)
     * @param   InstallerAdapter  $parent  The class calling this method
     *
     * @return  boolean  True on success
     */
    function postflight($type, $parent) {
        echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

        return true;
    }
}

Edycja language/pl-PL/mod_foo.sys.ini

Nie ma tu wiele do wyjaśnienia. Wpisz tekst tłumaczenia do tego pliku.

Kompletny language/pl-PL/mod_foo.sys.ini

Kompletny plik language/pl-PL/mod_foo.sys.ini wygląda następująco:

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

Edycja mod_foo.xml

Musisz dodać linię, aby skrypt był wywoływany automatycznie w Joomla.

<scriptfile>script.php</scriptfile>

Kompletny mod_foo.xml

Kompletny plik mod_foo.xml wygląda następująco:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
    <name>MOD_FOO</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <version>1.0</version>
    <description>MOD_FOO_XML_DESCRIPTION</description>
    <namespace>Joomla\Module\Foo</namespace>
    <scriptfile>script.php</scriptfile>
    <files>
        <filename module="mod_foo">mod_foo.php</filename>
        <folder>tmpl</folder>
        <folder>Helper</folder>
        <folder>language</folder>
        <filename>mod_foo.xml</filename>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="domain"
                    type="url"
                    label="MOD_FOO_FIELD_URL_LABEL"
                    filter="url"
                />
            </fieldset>
            <fieldset name="advanced">
                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    class="custom-select"
                />
                <field
                    name="moduleclass_sfx"
                    type="textarea"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    rows="3"
                />
                <field
                    name="cache"
                    type="list"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    default="0"
                >
                    <option value="1">JGLOBAL_USE_GLOBAL</option>
                    <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>
                <field
                    name="cache_time"
                    type="number"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    default="0"
                />
                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid"
                >
                    <option value="itemid"></option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Przetestuj swój moduł

Teraz możesz spakować wszystkie pliki i zainstalować je za pomocą Joomla Extension Manager. Bezpośrednio po instalacji zobaczysz następującą informację. Tak jak zapisałeś w skrypcie.

Wniosek

Jak widzisz, Joomla oferuje wiele, aby Twoje rozszerzenie było łatwe w użyciu - od samego początku.

Schematy kodu możesz znaleźć w tym miejscu:

https://github.com/joomla-extensions/boilerplate/tree/master/module

Przykładowe pliki tego samouczka można znaleźć na stronie w tym miejscuː.

https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

Użyj aktualizatora Joomla: dodawanie automatycznej aktualizacji - część 5

Wymagania

Potrzebujesz aktualnej Joomli! 4.x dla tego samouczka (na dzień dzisiejszy Joomla! 4.0.0-alpha6-dev)

Aktualizator Joomla

Pierwszą rzeczą do zrobienia jest przeczytanie samouczka zarządzanie aktualizacjami komponentów przy użyciu Joomla 2.5 - część 1, samouczek, dający wyobrażenie o tym, jak działa proces aktualizacji w Joomlaǃ. Chociaż został napisany dla wersji 2.5, proces nie uległ zmianie. Przeczytaj także wdrażanie aktualizacji serwera - to właśnie będziemy wdrażać w tym samouczku.

Struktura plików

Stworzymy lub zmienimy następujące pliki:

mod_foo.xml - Jedynym sposobem zaktualizowania naszego istniejącego modułu jest dodanie serwera aktualizacji - na przykład http://www.example.com/foo_update.xml -do pliku xml.
foo_update.xml - następnie musimy utworzyć plik XML dla serwera aktualizacji pod adresem http://www.example.com/foo_update.xml aby powiadomić Joomla o dostępności aktualizacji.

Edycja mod_foo.xml

Aby dodać nasz serwer aktualizacji, musimy wstawić następujące wiersze do twojego pliku XMLː

<updateservers>
    <server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

Kompletny mod_foo.xml

Kompletny plik mod_foo.xml wygląda następująco:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
    <name>MOD_FOO</name>
    <creationDate>[DATE]</creationDate>
    <author>[AUTHOR]</author>
    <authorEmail>[AUTHOR_EMAIL]</authorEmail>
    <authorUrl>[AUTHOR_URL]</authorUrl>
    <copyright>[COPYRIGHT]</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <version>1.0</version>
    <description>MOD_FOO_XML_DESCRIPTION</description>
    <namespace>Joomla\Module\Foo</namespace>
    <files>
        <filename module="mod_foo">mod_foo.php</filename>
        <folder>tmpl</folder>
        <folder>Helper</folder>
        <folder>language</folder>
        <filename>mod_foo.xml</filename>
    </files>
    <updateservers>
        <server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
    </updateservers>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="domain"
                    type="url"
                    label="MOD_FOO_FIELD_URL_LABEL"
                    filter="url"
                />
            </fieldset>
            <fieldset name="advanced">
                <field
                    name="layout"
                    type="modulelayout"
                    label="JFIELD_ALT_LAYOUT_LABEL"
                    class="custom-select"
                />
                <field
                    name="moduleclass_sfx"
                    type="textarea"
                    label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
                    rows="3"
                />
                <field
                    name="cache"
                    type="list"
                    label="COM_MODULES_FIELD_CACHING_LABEL"
                    default="0"
                >
                    <option value="1">JGLOBAL_USE_GLOBAL</option>
                    <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
                </field>
                <field
                    name="cache_time"
                    type="number"
                    label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
                    default="0"
                />
                <field
                    name="cachemode"
                    type="hidden"
                    default="itemid"
                >
                    <option value="itemid"></option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Więc teraz, gdy już Joomlaǃ szuka aktualizacji naszego rozszerzenia - stwórzmy je, aby przetestować nasz proces. Najpierw musimy jednak utworzyć plik foo_update.xml . Do tej pory opisaliśmy tylko serwer aktualizacji. Nie wiemy jeszcze, czy jest aktualizacja. W pliku foo_update.xml wskazujemy, kiedy jest publikowana nowa wersja i gdzie można ją pobrać.

Tworzenie foo_update.xml

Teraz musimy utworzyć plik XML pod adresem http://www.example.com/foo_update.xml , aby powiadomić Joomla o dostępności aktualizacji.

Kompletny foo_update.xml

Kompletny plik foo_update.xml wygląda następująco:

<?xml version="1.0" ?>
<updates>
    <update>
        <name>Foo</name>
        <description>This is mod_foo 1.0.1</description>
        <element>mod_foo</element>
        <type>module</type>
        <version>1.0.1</version>
        <downloads>
            <downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
        </downloads>
        <maintainer>Joomla</maintainer>
        <maintainerurl>http://www.example.com</maintainerurl>
        <targetplatform name="joomla" version="4.0"/>
        <client>site</client>
    </update>
</updates>

Po przesłaniu tego pliku na adres https://www.example.com/mod_foo.xml aktualizacja zostanie wyświetlona w zapleczu Joomla.

Przetestuj aktualizację swojego modułu

Utwórz kopię modułu w obecnej postaci. Następnie zaktualizuj numer wersji do 1.0.1. Teraz możesz spakować wszystkie pliki. Następnie wczytaj swój plik ZIP pod adres URL http://www.example.com/mod_foo_101.zip . Teraz możesz zaktualizować swój moduł za pomocą aktualizatora Joomla.

Moduły komercyjne

Zauważ, że w naszych plikach połączyliśmy się z plikiem XML aktualizacji rozszerzeń. W tym pliku XML widzimy lokalizację pliku ZIP modułu. Oznacza to, że jeśli ktoś miałby to prześledzić wstecz, mógłby znaleźć fizyczne źródło twojego pliku zip z modułami. Jeśli nie chcesz tego udostępniać, możesz znaleźć rozwiązanie w tym PRː https://github.com/joomla/joomla-cms/pull/15185 .

Wniosek

Dzięki aktualizatorowi Joomlaǃ możesz łatwo dotrzeć do wszystkich użytkowników i poinformować ich, że dostępna jest nowa wersja. Sama aktualizacja również jest łatwa.

Każde rozszerzenie powinno korzystać z serwera aktualizacji. Zwłaszcza ze względów bezpieczeństwa.

Schematy kodu możesz znaleźć w tym miejscu:

https://github.com/joomla-extensions/boilerplate/tree/master/module

Przykładowe pliki tego samouczka można znaleźć na stronie w tym miejscuː.

https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

J4.x

Tworzenie prostego modułu

From Joomla! Documentation

Wprowadzenie

Wymagania

Tworzenie prostego modułu, rozwijanie modułu podstawowego - Część 1

Struktura plików

Tworzenie mod_foo.php

Kompletny plik mod_foo.php

Tworzenie tmpl/default.php

Kompletny plik tmpl/default.php

Tworzenie mod_foo.xml

Kompletny plik mod_foo.xml

Tworzenie plików językowych

Przetestuj swój moduł

Wniosek

Dodanie klasy pomocniczej przy użyciu przestrzeni nazw - Część 2

Wymagania

Przestrzenie nazw

Struktura plików

Tworzenie Helper/FooHelper.php

Kompletny plik Helper/FooHelper.php

Edycja mod_foo.php

Kompletny plik mod_foo.php

Edycja tmpl/default.php

Kompletny tmpl/default.php

Edycja mod_foo.xml

Kompletny mod_foo.xml

Przetestuj swój moduł

Wniosek

Konfiguracjaː dodawanie parametrów poprzez pola formularza - Część 3

Wymagania

Konfigurowanie za pomocą pól i parametrów formularza

Struktura plików

Edycja mod_foo.xml

Kompletny mod_foo.xml

Edycja tmpl/default.php

Kompletny plik tmpl/default.php

Edycja language/pl-PL/mod_foo.ini

Kompletny language/pl-PL/mod_foo.ini

Przetestuj swój moduł

Wniosek

Użycie skryptu instalacji, aktualizacji i deinstalacji - część 4

Wymagania

Skrypty

Struktura plików

Tworzenie script.php

Kompletny script.php

Edycja language/pl-PL/mod_foo.sys.ini

Kompletny language/pl-PL/mod_foo.sys.ini

Edycja mod_foo.xml

Kompletny mod_foo.xml

Przetestuj swój moduł

Wniosek

Użyj aktualizatora Joomla: dodawanie automatycznej aktualizacji - część 5

Wymagania

Aktualizator Joomla

Struktura plików

Edycja mod_foo.xml

Kompletny mod_foo.xml

Tworzenie foo_update.xml

Kompletny foo_update.xml

Przetestuj aktualizację swojego modułu

Moduły komercyjne

Wniosek