--=REKLAMA=--

Parametry szablonów

Z Joomla!WikiPL

Ikona przetlumacz.png
 Uwaga o zawartości

Ta strona wymaga przetłumaczenia lub jest w trakcie tłumaczenia! Pomoc jest mile widziana. Ostatnio edytowane przez Zwiastun (dyskusja. Data edycji: Mon, 09 Dec 2013 02:35:47 +0000

The template system has always been one of Joomla's most powerful features, but prior to Joomla 1.5 it was difficult for web design companies to ship templates with much in the way of built-in flexibility. For example, a template available in a variety of different colour schemes would often be supplied as a suite of separate template files. Some web design companies created their own methods for allowing the site administrator to change colour schemes and other template features in the Administrator, but these methods were not standardised and often involved the site administrator in editing configuration files by hand, or installing a custom component to manage the template.

This all changed with the advent of Joomla 1.5 which supported the idea of template parameters. Actually it would be more accurate to call them extension parameters as the implementation is generic for all extension types: components, modules, plugins and templates. In this chapter you will learn about how to create and use parameters in your template designs. Each of the wide range of parameter types directly supported by the Joomla Framework is described in detail, but you will also learn how to create your own custom parameter types to suit your particular needs. There is also a short reference on regular expressions as they are used in some of the template parameter types.

Wprowadzenie

Aby zobaczyć praktyczne przykłady parametrów, wybierz w menu zaplecza Rozszerzenia - > Szablony [Extensions → Template Manager] i kliknij odnośnik-nazwę szablonu rhuk_milkyway. Przejdziesz na stronę edytora szablonu. W prawej części okna widać sekcję Parametry, a w niej trzy ustawienia: Wariant kolorystyczny [Colour Variation], Wariant tła [Background Variation] i Szerokość szablonu [Template Width]. Zobacz ilustrację poniżej. Te typowe parametry szablonu. W tym przypadku kontrolują one kolorystykę szablonu oraz standardową szerokość.

Template-parameters.png

Parametry szablonu pozwalają administratorom dostosować zachowanie szablonu za pomocą edytora szablonów na stronie zaplecza. To, jakie parametry są dostępne oraz jaką pełnią rolę, zależy od projektanta szablonu. Ale teraz projektanci dysponują kompletem łatwych w użyciu narzędzi tworzenia elastycznych szablonów. Aby umożliwić zmianę parametrów szablonu, projektant musi:

  • Dodać elementy <param> w sekcji <params> pliku templateDetails.xml.
  • Dodać w pliku params.ini linie określające domyślne wartości parametrów.
  • Dodać w pliku index.php szablonu kod odczytujący aktualną wartość parametrów i odpowiednie reguły zachowania.


Definiowanie parametrów w templateDetails.xml

Plik templateDetails.xml jest zawsze umieszczony w macierzystym katalogu szablonu. Przykładowo, pełna ścieżka do tego pliku w szablonie Beez wygląda tak: [sciezka_do_Joomla]/templates/beez/templateDetails.xml. Uwaga: W systemach *NIX wielkość znaków w nazwach katalogów i plików ma znaczenie - druga część nazwy pliku pisana jest wielką literą.

Plik templateDetails.xml można modyfikować w dowolnym edytorze tekstu, edytorze HTML czy XML (ale raczej nie w procesorach typu MS Word czy OpenOffice - w takich przypadkach należy je zapisywać w formacie .txt!; odradzamy też wykorzystywanie do tego celu Notatnika z systemu Windows - ten edytor umieszcza na początku pliku znacznik BOM, ktory może powodować problemy z odczytywaniem takich plików.)

Sekcja <params> umieszczona jest zwykle jako jedna z ostatnich w pliku. Jeśli nie ma takiej sekcji, można ją dodać. Musi być umieszczona przed kończącym dokument znacznikiem </install>. Nie zapomnij o znaczniku zamykającym </params>. Uwaga: W Joomla 1.6 znacznik <install> zostanie wycofany, zastąpi go znacznik <extension>.

  • Zapoznaj się z podstawowym plikiem templateDetails.xml oraz wprowadzeniem o tworzeniu pliku templateDetails.xml
  • Zapoznaj się ze specyfikacją templateDetails.xml i szczegółami specyfikacji tego pliku

Dla każdego parametru, jaki chcesz zdefiniować, dodajemy element <param>. Element może zawierać kilka wymaganych bądź nieobowiązkowych argumentów zależnie od typu parametru. Obowiązkowym jest w gruncie rzeczy tylko argument type, ale argumenty name, default, description oraz label są wspólne dla większości parametrów, a name jest obowiązkowy zawsze, jeśli występuje którykolwiek z nich.

Oto obowiązkowe/powszechne argumenty:

  • type – określa rodzaj kontrolki HTML umożliwiającej wybór opcji w edytorze własności szablonu na zapleczu w sekcji Parametry szablonu (pole tekstowe: text, przycisk opcji: radio, lista lub pole wyboru: list)
  • name – jednoznaczne, niepowtarzalne oznaczenie - nazwa parametru, dowolna, zdefiniowana w kodzie szablonu;do tej nazwy odwołuje się kod Joomla!.

Poniższe argumenty są opcjonalne, ale wspólne dla prawie wszystkich typów parametrów:

  • default – domyślne ustawienie parametru.
  • description – opis, instrukcja dla użytkownika, wyświetlana jako wskazówka w dymku na stronie edytora szablonu w sekcji Parametry szablonu. Może być napisem tłumaczonym; zapoznaj się z Lokalizacja szablonu, aby uzyskać więcej informacji o tym, jak dodać tłumaczenie tego napisu.
  • label - treść etykiety, tytuł opisujący pole parametru na stronie edytora szablonu w sekcji Parametry szablonu. Może być napisem tłumaczonym; zapoznaj się z Lokalizacja szablonu, aby uzyskać więcej informacji o tym, jak dodać tłumaczenie tego napisu. Jeśli etykieta zostanie pominięta, w jej roli zostanie wykorzystana wartość argumentu name.

Element param może zawierać opcje wyboru – elementy option, każdy z argumentem value – wartością wyrażoną liczbą albo nazwą – zależnie od deklaracji zmiennych zastosowanych w kodzie szablonu.

Argumenty nieobowiązkowe zależą od typu parametru. Każdy typ parametru jest szczegółowo opisany w artykule Standardowe typy parametrów. Jeśli jesteś projektantem, możesz stworzy swoje własne typy parametrów; zapoznaj się z Tworzenie własnych typów parametrów szablonu, aby uzyskać więcej informacji.

Na przykład w poniższym fragmencie kodu widać sekcję <params> definiującą dwa parametry - jeden to lista rozwijana z wariantami kolorystycznymi szablonu, a drugi to pola opcji, umożliwiające decyzję, czy wyświetlać notę o autorstwie i prawach własności szablonu.

Parametry szablonu umożliwiają przesyłanie zmiennych konfigurujących szablon. Element <params> zawiera podelementy dla każdego parametru, który można ustawić w szablonie. Administrator witryny może zmieniać wartości parametrów w sekcji Parametry szablonu na stronie Rozszerzenia -> Szablony -> [nazwa_szablonu] - > przycisk Zmień.

Na przykład, poniżej ustawiamy dwa parametry (Warianty kolorystyczne szablonu oraz Pokaż/Ukryj Autora i Prawa własności)

<params>
    <param name="templateColour" type="list" default="blue" 
            label="Template Colour" description="Choose the template colour.">
        <option value="blue">Blue</option>
        <option value="red">Red</option>
        <option value="green">Green</option>
        <option value="black">Black</option>
    </param>
    <param name="authorCopyright" type="radio" default="1" 
            label="Author Copyright" description="Show/Hide author copyright.">
        <option value="0">hide</option>
        <option value="1">show</option>
    </param>
</params>

Na stronie Rozszerzenia -> Szablony -> [szablon] - > [Zmień], którą teraz zobaczysz, sekcja "Parametry" będzie mieć dwa zdefiniowane przed chwilą ustawienia. Aby dowiedzieć się więcej, jak w pliku szablonu pobierać wartości parametrów, przeczytaj Pobieranie wartości parametrów w pliku szablonu

Sekcja Parametry szablonu na stronie zaplecza wygląda tak, jak na ilustracji poniżej.

Plik:Template-parameters-example.png

Uwaga: Aktualnie szablony nie obsługują grupowania parametrów!

Wskazówka: Aby w pliku XML umieszczać znaczniki HTML, niektóre znaki specjalne muszą być kodowane, jak poniżej:

Znak Opis - znaczenie Kod
& Ampersand &amp;
Podwójny apostrof &quot;
' Pojedynczy apostrof &#039;
< Mniejsze od &lt;
> Większe od &gt;

Plik params.ini

Żeby parametry działały, w katalogu szablonu musi znajdować się plik params.ini udostępniony do zapisu. Ten plik jest wykorzystywany przez Joomla! do przechowywania ustawień parametrów. Może to być pusty plik, ale z prawami do zapisu, aby możliwe było zachowanie ustawień dokonanych przez administratorów.

Przykłady z pliku powyżej wyglądać tak, jak poniżej:

templateColor=blue
authorCopyright=1


Obsługiwane typy parametrów


Ten fragment powinien objaśniać, jakie rodzaje (typy) parametrów są obsługiwane przez rozszerzenia oraz dostarczać prostych ilustracji zastosowania parametrów. Powinien opisywać, gdzie i jak umieścić definicje parametrów rozszerzenia w plikach XML oraz jak w PHP uzyskać dostęp do wartości parametru podczas wykonywania rozszerzenia. Powinno zestawiać listę dostępnych parametrów, ich opis, objaśnienie składni, ilustrację oraz pokazywać efekt zastosowania.


Standardowe typy parametrów

Standardowe typy parametrów dla Joomla! Joomla w wersji 1.5.x

Platforma Joomla! obsługuje 21 różnych typów standardowych parametrów, wykorzystywanych przez wszystkie rozszerzenia (szablony, komponenty, moduły i dodatki). Poniżej w kolejności alfabetycznej znajdują się zwięzłe opis każdego parametru. Szczegóły każdego parametru przedstawiono na odrębnych stronach.

  • calendar umieszcza pole tekstowe przeznaczone na podanie daty, a obok ikonę kalendarzyka, który może posłużyć do wyboru i umieszczania daty zamiast ręcznego wpisywania.
  • category umieszcza rozwijaną listę kategorii z danej sekcji.
  • editors umieszcza rozwijaną listę dostępnych edytorów wizualnych (WYSIWYG).
  • filelist umieszcza rozwijaną listę plików w danym katalogu.
  • folderlist umieszcza rozwijaną listę folderów w zaznaczonym katalogu.
  • helpsites umieszcza rozwijaną listę witryn - oficjalnych serwisów pomocy.
  • hidden umieszcza pole ukryte do wpisania wartości parametru, która nie może być modyfikowana bezpośrednio przez użytkownika (może być zmieniona w kodzie albo edycję pliku params.ini).
  • imagelist umieszcza rozwijaną listę plików graficznych w oznaczonym katalogu.
  • languages umieszcza rozwijaną listę zainstalowanych pakietów językowych witryny i zaplecza.
  • list umieszcza rozwijaną listę własnych zdefiniowanych opcji.
  • menu umieszcza rozwijaną listę menu dostępnych w witrynie.
  • menuitem umieszcza rozwijaną listę dostępnych pozycji menu (odnośników w menu).
  • password umieszcza pole tekstowe przeznaczone na podanie hasła. Znaki hasła nie będą widoczne podczas wpisywania (zostaną zastąpione markerami).
  • radio umieszcza przyciski radiowe umożliwiające zaznaczenie jednej z różnych opcji.
  • section umieszcza rozwijaną listę sekcji artykułów w witrynie.
  • spacer umieszcza poziomą linię rozdzielającą wizualnie pola parametrów. Jest to jedynie przerywnik graficzny - nie pobiera i nie przechowuje żadnych wartości.
  • sql umieszcza listę rozwijaną umożliwiającą odczytanie informacji z bazy danych. Wartości do rozwijanej listy dostarcza pierwsza kolumna wyników. [ The first results column returned by the query provides the values for the drop down box]
  • text umieszcza pole tekstowe przeznaczone na dane do 255 znaków.
  • textarea umieszcza obszar tekstowy przeznaczony na tekst wielowierszowy.
  • timezones umieszcza rozwijaną listę stref czasowych.
  • usergroup umieszcza rozwijaną listę grup użytkowników.


Standardowe typy parametrów - szczegóły

calendar

Parametr typu calendar - Joomla w wersji 1.5.x

Params calendar.png

Parametr typu calendar udostępnia pole tekstowe przeznaczone na wpisanie daty. Ikona obok ramki udostępnia kalendarzyk, w którym można zaznaczyć potrzebną datę – zostanie umieszczona w polu tekstowym po wybraniu (bez czasu). Jeśli jakaś wartość parametru jest zapisana, wówczas zostanie wyświetlona w polu tekstowym. Jeśli nie, wyświetlana jest wartość domyślna.

  • type (obowiązkowy) musi to być calendar.
  • name (obowiązkowy) jednoznaczne, niepowtarzalne oznaczenie - nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) treść etykiety, tytuł opisujący pole parametru.
  • default (opcjonalny) domyślna data; musi być zapisana w takim samym formacie, jak podany w polu Format.
  • description (opcjonalny, można tłumaczyć) opis, instrukcja dla użytkownika, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • format (opcjonalny) sposób zapisu daty, określony jak dla funkcji PHP strftime() (zobacz poniżej). Jeśli żaden format nie zostanie podany, zastosowany zostanie format, '%Y-%m-%d' (dający daty jak '2008-04-16').
  • class (opcjonalny) nazwa stylizującej pole klasy CSS. Jeśli ominięte, zostanie zastosowana standardowa 'inputbox'.

Przykład definicji parametrów w pliku XML:

<param name="mycalendar" type="calendar" default="5-10-2008" label="Select a date" description="" format="%d-%m-%Y" />

Pole format określa, w jaki sposób data powinna być podana w przypadku, gdy wpisywana jest ręcznie oraz decyduje, jak będzie wyświetlana. Znaki interpunkcyjne zastosowane w schemacie są – podczas zapisywania daty w bazie danych ignorowane. W schemacie kodu używamy oznaczeń służących do formatowania daty za pomocą funkcji PHP date (). Szczegóły można znaleźć na stronie http://www.php.net/manual/en/function.date.php albo - przynajmniej z częściowym tłumaczeniem http://www.php.net/manual/pl/function.date.php Poniżej przedstawiamy najczęściej stosowane oznaczenia:

Znak Opis Przykład
a pora dnia, skrót małymi literami – am (Ante meridem): przed południem lub pm (Post meridem): po południu am lub pm
A oznaczenie wielkimi literami czasu - AM (Ante meridem): przed południem lub PM (Post meridem): po południu AM lub PM
d dzień miesiąca: 2-cyfrowa liczba z zerem na początku 01 do 31
D dzień tygodnia: 3-literowy skrót Nie do Sob
j dzień miesiąca: liczba, bez zera na początku 1 do 31
l dzień tygodnia – pełna nazwa (małe 'L') Niedziela do Sobota
N dzień tygodnia – liczba, numer dnia wg ISO-8601 (w PHP od 5.1.0 wzwyż) 1 (Poniedziałek) do 7 (Niedziela)
S angielska końcówka liczebnika porządkowego – tekst, dwa znaki st, nd, rd lub th. Działa tylko z j
w dzień tygodnia: pojedyncza cyfra 0 (niedziela) do 6 (sobota)
z dzień w roku – liczba, kolejny numer dnia 0 do 365 (0 = 1 stycznia)
W tydzień w roku – liczba, kolejny numer tygodnia według ISO-8601, tydzień zaczyna się w poniedziałek (dodane w PHP 4.1.0) 42 (42. tydzień w roku)
F miesiąc – tekst, pełna nazwa Styczeń do Grudzień
m miesiąc: 2-cyfrowa liczba z zerem na początku 01 do 12
M miesiąc: 3-literowy skrót Sty do Gru
n miesiąc: liczba bez zera na początku 1 do 12
t dni w danym miesiącu – liczba 28 do 31
o rok według ISO-8601. Zwraca to taką samą wartość jak Y, z takim wyjątkiem, że numer tygodnia ISO (W) należy do poprzedniego lub następnego roku, niż rok użyty w tym miejscu. (dodane w PHP 5.1.0).
Same value as Y except that if the ISO week number (W) belongs to the previous or next year, that year is used instead (only supported on servers running PHP 5.1.0 or later)
1999 lub 2003
Y rok – cztery cyfry 1999 lub 2003
y rok – dwie cyfry 99 lub 03
B Czas internetowy Swatch - uniwersalny schemat czasu. Zob. http://www.swatch.com/zz_en/internettime.html od 000 do 999
g godzina w formacie 12-godzinnym, bez zer na początku od 1 do 12
G godzina w formacie 24-godzinnym, bez zer na początku 1 do 23
h godzina w formacie 12-godzinnym, z zerem na początku 01 do 12
H godzina w formacie 24-godzinnym, z zerem na początku 01 do 23
I czas letni - 1, jeśli jest aktualnie; w przeciwnym przypadku - 0 1 lub 0
L rok przestępny - 1, nieprzestępny - 0 1 lub 0
s sekundy po pełnej minucie z zerami na początku 00 do 59
T Strefa czasowa serwera w formacie trójznakowym np. GMT
U liczba sekund od 1 stycznia 1970 do aktualnego czasu (tzw. znacznik czasu Uniksa)
Z przesunięcie aktualnej strefy czasowej (offset) w sekundach) -43200 do 43200
u mikrosekundy (dodane w PHP 5.2.2) 54321
c pełna data sformatowana zgodnie z ISO 8601 (dodane w PHP5) 2004-02-12T15:19:21+00:00
r pełna data sformatowana zgodnie RFC 2822 Thu, 21 Dec 2000 16:01:07 +0200

Zwróć uwagę, że format, w jakim przechowywana jest data w pliku param.ini, jest taki sam, jak określony argumentem format. Pamiętaj o tym szczególnie w sytuacji, różnie ustawionych języków zaplecza i strony frontowej oraz sytuacji, gdy w dacie pojawią się nazwy np. miesięcy, dni tygodnia (np. w przypadku ustawienia %F).

Uwaga: Typ parametru ‘calendar’ nie obsługuje innych kalendarzy, niż gregoriański. Jeśli potrzebujesz obsługi niegregoriańskiego kalendarza, zaprojektuj własny typ parametru.



category

Parametr typu category - Joomla w wersji 1.5.x

Params category.png

Parametr typu category udostępnia listę rozwijaną kategorii umieszczonych w danej sekcji. Jeśli zapisany jest identyfikator sekcji (ID), wczytywane są kategorie z sekcji określonej tym identyfikatorem. Jeśli ID sekcji nie jest zapisane w ustawieniach, wczytywana jest domyślnie lista wszystkich kategorii ze wszystkich sekcji. Pierwszym elementem listy rozwijanej jest napis '- Select Category -' (tłumaczony), a jego wartość wynosi 0.

Zwróć uwagę, że lista kategorii wyświetlana jest niezależnie od stanu publikacji sekcji - zarówno z sekcji opublikowanych, jak i nieopublikowanych. Takie rozwiązanie umożliwia decydowanie o strukturze witryny bez konieczności wcześniejszego publikowania sekcji.

  • type (obowiązkowy) musi to być category.
  • name (obowiązkowy) jednoznaczne, niepowtarzalne oznaczenie - nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) treść etykiety, tytuł opisujący pole parametru.
  • section (opcjonalny) numer ID sekcji, z której kategorie będą wyświetlone na liście rozwijanej. ID sekcji można odczytać ze strony Artykuły -> Sekcje artykułów. Jeśli ID sekcji zostanie pominięte (opuszczone) będzie wyświetlana lista wszystkich kategorii ze wszystkich sekcji.
  • scope (opcjonalny) jakiś alias sekcji.
  • default (opcjonalny) domyślny numer identyfikacyjny (ID) kategorii.
  • description (opcjonalny, można tłumaczyć) opis, instrukcja dla użytkownika, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny) nazwa stylizującej pole klasy CSS. Jeśli ominięte, zostanie zastosowana standardowa 'inputbox'.

Przykład definicji parametrów w pliku XML:

<param name="mycategory" type="category" label="Select a category" description="" section="3" />


editors

Parametr typu editors - Joomla w wersji 1.5.x

Params editors.png

Parametr typu editors udostępnia rozwijaną listę zainstalowanych w systemie edytorów wizualnych (WYSIWYG). Jeśli aktualna wartość parametru jest zapisana, wybranym jest edytor określony w konfiguracji. Jeśli nie - wybranym jest edytor domyślny.

Pierwszą opcją na liście jest zawsze '- Select Editor -' (można tłumaczyć), a jej wartość wynosi 0.

  • type (obowiązkowy): musi to być editors.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • default (opcjonalny): domyślna nazwa edytora - taka, jak na stronie zaplecza Rozszerzenia -> Dodatki.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca, wyświetlana gdy użytkownik umieści wskaźnik myszki nad nazwą - etykietą parametru.

Przykład definicji parametrów w pliku XML:

<param name="myeditor" type="editors" default="none" label="Select an editor" />

calendar

Parametr typu filelist - Joomla w wersji 1.5.x

Params filelist.png

Parametr typu filelist udostępnia rozwijaną listę plików we wskazanym katalogu. Jeśli wartość parametru jest zapisana w pliku params.ini, wyświetlone zostaną pliki ze wskazanego katalogu. Jeśli wartość nie będzie zapisana, zostaną wyświetlone pliki z katalogu ustalonego przez JPATH_ROOT (macierzystego katalogu Joomla).

Domyślną pierwszą opcją na liście jest '- Do not use -' (można tłumaczyć), a jej wartość wynosi '-1', następną opcją jest '- Use default -' (można tłumaczyć), a jej wartość wynosi '0'.

  • type (obowiązkowy): musi to być filelist.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • directory (opcjonalny) ścieżka do katalogu, z którego będą listowane pliki. Jeśli opuszczona, zostaną wyświetlone pliki z katalogu ustalonego przez JPATH_ROOT.
  • default (opcjonalny) nazwa domyślnego pliku.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca, wyświetlana gdy użytkownik umieści wskaźnik myszki nad nazwą - etykietą parametru.
  • filter (opcjonalny) wyrażenie regularne filtrujące pliki, które zostaną umieszczone na liście rozwijanej. Jeśli jest opuszczone, wyświetlone zostaną wszystkie pliki z katalogu. Wyrażenie umieszczone w argumencie filter jest stosowane przed wyrażeniem umieszczonym w argumencie exclude. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • exclude (opcjonalny) wyrażenie regularne decydujące o tym, których z plików na liście nie umieszczać. Wyrażenie umieszczone w argumencie exclude jest stosowane ppo wyrażeniu umieszczonym w argumencie filter. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • stripext (opcjonalny) argument logiczny (boolean). Jeśli prawda (Tak), nazwy plików zostanie skrócone - będą wyświetlane bez rozszerzenia. Uwaga: W takim przypadku będą również zapisywane bez rozszerzenia!
  • hide_none (opcjonalny) argument logiczny (boolean). Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Do not use -'.
  • hide_default (opcjonalny) argument logiczny (boolean).. Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Use default -'.

Przykład definicji parametrów w pliku XML:

<param name="myfile" type="filelist" default="" label="Select a file" description="" directory="administrator" filter="" exclude="" stripext="" />

folderlist

Parametr typu folderlist - Joomla w wersji 1.5.x

Params folderlist.png

Parametr typu folderlist udostępnia rozwijaną listę folderów we wskazanym katalogu. Jeśli wartość parametru jest zapisana w pliku params.ini, wyświetlone zostaną foldery ze wskazanego katalogu. Jeśli wartość nie będzie zapisana, zostaną wyświetlone pliki z katalogu ustalonego przez JPATH_ROOT (macierzystego katalogu Joomla).

Domyślną pierwszą opcją na liście jest '- Do not use -' (można tłumaczyć), a jej wartość wynosi '-1', następną opcją jest '- Use default -' (można tłumaczyć), a jej wartość wynosi '0'.

  • type (obowiązkowy): musi to być folderlist.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • directory (opcjonalny) ścieżka do katalogu, z którego będą listowane foldery.
  • default (opcjonalny) nazwa domyślnego katalogu.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca, wyświetlana gdy użytkownik umieści wskaźnik myszki nad nazwą - etykietą parametru.
  • filter (opcjonalny) wyrażenie regularne filtrujące katalogi, które zostaną umieszczone na liście rozwijanej. Wyrażenie umieszczone w argumencie filter jest stosowane przed wyrażeniem umieszczonym w argumencie exclude. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • exclude (opcjonalny) wyrażenie regularne decydujące o tym, których z katalogów na liście nie umieszczać. Wyrażenie umieszczone w argumencie exclude jest stosowane ppo wyrażeniu umieszczonym w argumencie filter. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • hide_none (opcjonalny) argument logiczny (boolean). Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Do not use -'.
  • hide_default (opcjonalny) argument logiczny (boolean).. Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Use default -'.

Przykład definicji parametrów w pliku XML:

<param name="myfolder" type="folderlist" default="" label="Select a folder" directory="administrator" filter="" exclude="" stripext="" />

helpsites

Parametr typu helpsites - Joomla w wersji 1.5.x

Params helpsites.png

Parametr typu helpsites umieszcza rozwijaną listę witryn – serwerów pomocy zgodną z Twoją instalacją Joomla!. Jeśli w pliku params ini zapisana jest wartość parametru, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna. Z wyjątkiem serwera lokalnego, który jest zawsze umieszczany na liście, adresy pozostałych witryn są generowane z pliku:

[sciezka-do-Joomla]/administrator/help/helpsites-15.xml

Napis 'local' może być tłumaczony. Pozycja 'local' zwraca pusty napis.

  • type (obowiązkowy): musi to być helpsites.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • default (opcjonalny): adres domyślnego serwera pomocy (nazwa witryny nie jest widoczna).
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Przykład definicji parametrów w pliku XML:

<param name="myhelpsite" type="helpsites" default="" label="Select a help site" description="" />

hidden

Parametr typu hidden - Joomla w wersji 1.5.x

Parametr typu hidden umieszcza ukryte pole, w którym przechowywana jest wartość, jakiej użytkownik nie może zmieniać bezpośrednio za pomocą narzędzi administracyjnych (ale można tę wartość modyfikować bezpośrednio w pliku params.ini). Jeśli w pliku params.ini zapisana jest wartość parametru, zostanie wczytana.

Ponieważ jest to pole ukryte, więc nie jest widoczne na ekranie administratora.

  • type (obowiązkowy): musi to być hidden.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • default (obowiązkowy): dane, jakie chcemy zbierać.
  • class (opcjonalny): nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'text_area'.

Przykład definicji parametrów w pliku XML:

<param name="mysecretvariable" type="hidden" default="" />

imagelist

Parametr typu imagelist - Joomla w wersji 1.5.x

Params imagelist.png

Parametr typu imagelist udostępnia rozwijaną listę plików we wskazanym katalogu. Na liście znajdą się jedynie pliki z rozszerzeniem: .png, .gif, .jpg, .bmp, .ico. Jeśli wartość parametru jest zapisana w pliku params.ini, wyświetlone zostaną pliki ze wskazanego katalogu. Jeśli wartość nie będzie zapisana, zostaną wyświetlone pliki z katalogu ustalonego przez JPATH_ROOT (macierzystego katalogu Joomla).

Domyślną pierwszą opcją na liście jest '- Do not use -' (można tłumaczyć), a jej wartość wynosi '-1', następną opcją jest '- Use default -' (można tłumaczyć), a jej wartość wynosi '0'.

  • type (obowiązkowy): musi to być imagelist.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • directory (opcjonalny) ścieżka do katalogu, z którego będą listowane pliki. Jeśli opuszczona, zostaną wyświetlone pliki z katalogu ustalonego przez JPATH_ROOT.
  • default (opcjonalny) nazwa domyślnego pliku.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca, wyświetlana gdy użytkownik umieści wskaźnik myszki nad nazwą - etykietą parametru.
  • filter (opcjonalny) wyrażenie regularne filtrujące pliki, które zostaną umieszczone na liście rozwijanej. Jeśli jest opuszczone, wyświetlone zostaną wszystkie pliki z katalogu. Wyrażenie umieszczone w argumencie filter jest stosowane przed wyrażeniem umieszczonym w argumencie exclude. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • exclude (opcjonalny) wyrażenie regularne decydujące o tym, których z plików na liście nie umieszczać. Wyrażenie umieszczone w argumencie exclude jest stosowane ppo wyrażeniu umieszczonym w argumencie filter. Więcej informacji na temat wyrażeń regularnych znajdziesz w Wyrażenia regularne w argumentach parametrów.
  • stripext (opcjonalny) argument logiczny (boolean). Jeśli prawda (Tak), nazwy plików zostanie skrócone - będą wyświetlane bez rozszerzenia. Uwaga: W takim przypadku będą również zapisywane bez rozszerzenia!
  • hide_none (opcjonalny) argument logiczny (boolean). Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Do not use -'.
  • hide_default (opcjonalny) argument logiczny (boolean).. Jeśli prawda (Tak), na liście zostanie opuszczona pozycja '- Use default -'.

Przykład definicji parametrów w pliku XML:

<param name="myimage" type="imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" />

languages

Parametr typu languages - Joomla w wersji 1.5.x

Params language.png

Parametr typu languages umieszcza rozwijaną listę zainstalowanych pakietów językowych witryny albo zaplecza. Jeśli w pliku w params.ini wartość parametru jest zapisana, zostanie załadowana najpierw. Jeśli nie – zostanie wybrana wartość domyślna. Wartość zapisywana jest w znaczniku language. Przykładowo dla języka angielskiego (Wielka Brytania) będzie to 'en-GB'.

Pierwszą opcją na liście jest zawsze '- Select Language -' (można tłumaczyć), a jej wartość wynosi '0'.

  • type (obowiązkowy): musi to być languages.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • client (obowiązkowy): aplikacja obsługiwana przez wybrany język. ‘Site’, gdy chcesz wylistować języki obsługujące witrynę, ‘Administrator’, aby wylistować języki obsługujące zaplecze.
  • default (opcjonalny): kod domyślnego języka. Przykładowo, 'en-GB'.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Przykład definicji parametrów w pliku XML:

<param name="mylanguage" type="languages" client="site" default="en-GB" label="Select a language" description="" />

list

Parametr typu list - Joomla w wersji 1.5.x

Params list.png

Parametr typu list umieszcza rozwijaną listę własnych zdefiniowanych opcji. Jeśli w pliku w params.ini wartość parametru jest zapisana, zostanie załadowana najpierw. Jeśli nie – zostanie wybrana wartość domyślna.

  • type (obowiązkowy): musi to być list.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • default (opcjonalny): domyślna pozycja listy.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny): nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'inputbox'.

Element XML <param> musi zawierać jeden lub więcej elementów <option> definiujących elementy listy. Teksty między znacznikami <option> i </option> są etykietami wyświetlanymi na liście i mogą być tłumaczone. Znacznik <option> wymaga jednego argumentu – value:

  • value (obowiązkowy): wartość parametru zapisywana w params.ini, jeśli zostanie wybrana.

Wskazówka: nie zapomnij zakończyć definicji parametru zamykającym znacznikiem </param>

Przykład definicji parametrów w pliku XML:

<param name="mylistvalue" type="list" default="" label="Select an option" description="">
  <option value="0">Option 1</option>
  <option value="1">Option 2</option>
</param>

menu

Parametr typu menu - Joomla w wersji 1.5.x

Params menu.png

Parametr typu menu umieszcza rozwijaną listę menu dostępnych w witrynie. Jeśli wartość parametru jest zapisana w params.ini, zostanie załadowana najpierw. Jeśli nie – zostanie wybrana wartość domyślna.

Domyślną pierwszą opcją na liście jest zawsze '- Select Menu -' (można tłumaczyć), a jej wartość wynosi '0'.

  • type (obowiązkowy) musi to być menu.
  • name (obowiązkowy) niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • default (opcjonalny) domyślne menu. Uwaga: jest to nazwa wyświetlana na stronie Menu - >Projektant menu w kolumnie Typ, a nie numer ID menu.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Przykład definicji parametrów w pliku XML:

<param name="mymenu" type="menu" default="mainmenu" label="Select a menu" description=”Select a menu” />

menuitem

Parametr typu menuitem - Joomla w wersji 1.5.x

Params menuitem.png

Parametr typu menuitem umieszcza rozwijaną listę dostępnych w witrynie pozycji menu. Domyślną pierwszą opcją na liście jest zawsze '- Select Item -' (można tłumaczyć), a jej wartość wynosi '0'. Pierwszą pozycją na liście jest zawsze pozycja oznaczona jako ' - Top' (napis można tłumaczyć).

  • type (obowiązkowy: musi to być menuitem.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć) etykieta – tytuł opisujący parametr.
  • default (opcjonalny) domyślna pozycja menu. Uwaga: Faktycznie jest to nr ID pozycji menu (ItemID).
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca , wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • state (opcjonalny) stan pozycje, decyduje, czy będą wyświetlane wszystkie pozycje menu (jeśli 0), czy tylko opublikowane (jeśli 1).

Przykład definicji parametrów w pliku XML:

<param name="mymenuitem" type="menuitem" default="45" label="Select a menu item" description=”Select a menu item” />

password

Parametr typu password - Joomla w wersji 1.5.x

Params password.png

Parametr typu password umieszcza pole tekstowe, umożliwiające wpisanie hasła. Znaki wpisywanego hasła będą ukrywane. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona w zaciemnionej formie, jeśli nie - zostanie wyświetlana wartość domyślna.

Zwróć uwagę, że treść hasła w tym przypadku będzie przechowywana w pliku params.ini jako zwykły tekst; przechowywane hasło nie jest kodowane żadną funkcją szyfrującą. Ponieważ wiele serwerów internetowych umożliwia odczytywanie plików params.ini, nie można tej metody przechowywania hasła uznawać za bezpieczną.

  • type (obowiązkowy): musi to być password.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • size (opcjonalny): szerokość określona ilością znaków. Jeśli opuszczono - zostanie ustalona automatycznie, zależnie od przeglądarki. Wpisana tutaj wartość nie limituje ilości znaków, jakie można umieścić w polu tekstowym (standardowo do 255).
  • default (opcjonalny): domyślne hasło.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny): nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'text_area'.

Przykład definicji parametrów w pliku XML:

<param name="mypassword" type="password" default="secret" label="Enter a password" description="" size="5" />

radio

Parametr typu radio - Joomla w wersji 1.5.x

Params radio.png

Parametr typu radio umieszcza przyciski wyboru opcji (tylko jedna opcja może być wybrana). Jeśli w pliku w params.ini wartość parametru jest zapisana, zostanie załadowana najpierw. Jeśli nie – zostanie wybrana wartość domyślna.

  • type (obowiązkowy): musi to być radio.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • default (opcjonalny): pozycja wybrana domyślnie
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Element XML <param> musi zawierać jeden lub więcej elementów <option> definiujących każdy przycisk radiowy. Teksty między znacznikami <option> i </option> są etykietami przycisków i mogą być tłumaczone. Znacznik <option> wymaga jednego argumentu – value:

  • value (obowiązkowy): wartość parametru zapisywana w params.ini, jeśli zostanie wybrana.

Wskazówka: nie zapomnij zakończyć definicji parametru zamykającym znacznikiem </param>.

Przykład definicji parametrów w pliku XML:

<param name="myradiovalue" type="radio" default="0" label="Select an option" description="">
  <option value="0">1</option>
  <option value="1">2</option>
</param>

section

Parametr typu section - Joomla w wersji 1.5.x

Params section.png

Parametr typu section udostępnia listę rozwijaną dostępnych sekcji artykułów. Jeśli zapisany jest identyfikator sekcji (ID), wczytywana jest wybrana sekcja, w przeciwnym przypadku wczytywana jest wartość domyślna, jeśli została określona.

Pierwszym elementem listy rozwijanej jest napis always '- Select Section -' (tłumaczony), a jego wartość wynosi 0.

  • type (obowiązkowy) musi to być section.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • default (opcjonalny, można tłumaczyć) domyślny numer identyfikacyjny sekcji (ID).
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Przykład definicji parametrów w pliku XML:

<param name="mysection" type="section" default="" label="Select a section" description="" />

spacer

Parametr typu spacer - Joomla w wersji 1.5.x

Params spacer.png

Parametr typu spacer umieszcza poziomą linię rozdzielającą wizualnie pola parametrów. Jest to element czysto graficzny, nie przechowuje żadnych wartości.

  • type (obowiązkowy) musi to być spacer.
  • default (opcjonalny) napis używany zawsze z dodawaną domyślnie linią poziomą <hr />.

Przykład definicji parametrów w pliku XML

<param type="spacer" />

Możesz zastąpić standardową linię poziomą tytułem nazywajacym grupę parametrów. Na przykład:

<param type="spacer" default="Advanced parameters" />

Uwaga: gdy chcemy umieścić jakiś znacznik HTML, musimy go zakodować. Przykładowo, aby pogrubić tekst, użyjemy:

<param type="spacer" default="&lt;b&gt;Advanced parameters&lt;/b&gt;" />

sql

Parametr typu sql - Joomla w wersji 1.5.x

Params.sql.jpg

Parametr typu sql umieszcza, listę rozwijaną umożliwiającą odczytanie informacji z bazy danych Joomla. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna.

  • type (obowiązkowy) musi to być sql.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru. Musi być taki sam, jak nazwa kolumny w wynikach zapytania wyświetlanych użytkownikowi na liście rozwijanej, chyba że inna nazwa zostanie ustalona w atrybucie value_field.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • query (obowiązkowy): instrukcja SQL, której wykonanie dostarczy danych do listy rozwijanej. Instrukcja musi zwrócić wartości dwóch kolumn, jednej nazwanej 'value' (chyba, że jej wartość zostanie zastąpiona atrybutem ustalonym dla key_field) z wartością elementu listy, oraz drugiej nazwanej tak samo jak nazwa atrybutu (chyba, że jej wartość zostanie zastąpiona atrybutem ustalonym dla value_field) z tekstem widocznym na rozwijanej liście.
  • default (opcjonalny): wartość domyślna. Domyślna wartość pola 'value' chyba, że jej wartość zostanie zastąpiona atrybutem ustalonym dla key_field.
  • description (opcjonalny, można tłumaczyć) opis, wskazówka objaśniająca , wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • key_field (opcjonalny): nazwa kolumny zawierającej wartość parametru. Gdy opuszczono, zostanie użyta kolumna 'value', jeśli istnieje
  • value_field (opcjonalny): nazwa kolumny zawierającej wartość, która będzie widoczna dla użytkownika na rozwijanej liście. Gdy opuszczono, zostanie użyta kolumna nosząca taką samą nazwę, jak nazwa atrybutu, jeśli istnieje.

Przykład definicji parametrów w pliku XML:

<param name="title" type="sql" default="10" label="Select an article" 
query="SELECT id AS value, title FROM #__content" />

Zwróć uwagę na klauzulę AS zastosowaną w tym przykładzie, ponieważ w tabeli jos_content nie ma kolumny nazywającej się 'value'. W praktyce rzadko która tabela w bazie danych Joomla ma kolumnę 'value'.

Aby zdefiniować kolumnę, można by alternatywnie skorzystać z atrybutu key_field zamiast 'value'.

<param name="title" type="sql" default="10" label="Select an article" 
query="SELECT id, title FROM #__content" key_field=”id” />

Przyniesie identyczny efekt, jak poprzedni przykład.

Dla obu nazw kolumn mogą być potrzebne aliasy. Załóżmy na przykład, że chcesz, by pole zostało nazwane 'myfield' zamiast 'title', jak w poprzednim przykładzie. Możesz to zrobić instrukcją:

<param name="myfield" type="sql" default="10" label="Select an article" 
query="SELECT id AS value, title AS myfield FROM #__content" />

lub alternatywnie:

<param name="myfield" type="sql" default="10" label="Select an article" 
query="SELECT id, title FROM #__content" key_field=”id” value_field=”title” />

W instrukcji SQL możesz również składać (assemble) lub przeliczać pola. Przykładowo załóżmy, że chcesz dołączyć datę/czas utworzenia w każdym artykule do tytułu każdego artykułu na liście. Możesz w takim przypadku skorzystać z instrukcji SQL:

SELECT id, concat( title, ' (', created, ')') AS title FROM #__content

Uwaga: Instrukcje SQL powinny być prawidłowe także dla innych typów i wersji bazy danych niż baza obsługująca Joomla!. Będzie to najczęściej dotyczyć wersji MySQL, ale nie ma żadnego powodu, aby instrukcje nie miały działały poprawnie w innych bazach danych niż obsługiwane przez Joomla.

Uwaga: Jak widać w powyższych przykładach przedrostek nazw tabel w bazie danych można podać w postaci '#_' (znaku hasz i podkreślenia) - marker zostanie automatycznie przedrostek zastosowany w instalacji Joomla!.


text

Parametr typu text - Joomla w wersji 1.5.x

Params text.png

Parametr typu text umieszcza pole tekstowe, umożliwiające wpisywanie danych. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna.

  • type (obowiązkowy): musi to być text.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • size (opcjonalny): szerokość określona ilością znaków. Jeśli opuszczono - zostanie ustalona automatycznie, zależnie od przeglądarki. Wpisana tutaj wartość nie limituje ilości znaków, jakie można umieścić w polu tekstowym (standardowo do 255).
  • default (opcjonalny, można tłumaczyć) domyślna treść.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny): nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'text_area'.

Przykład definicji parametrów w pliku XML:

<param name="mytextvalue" type="text" default="Some text" label="Enter some text" description="" size="10" />

textarea

Parametr typu textarea - Joomla w wersji 1.5.x

Params textarea.png

Parametr typu textarea umieszcza ramkę obszaru tekstowego, umożliwiającą wpisywanie danych w wielu liniach. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna.

  • type (obowiązkowy) musi to być textarea.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • rows (obowiązkowy): wysokość obszaru, na którym będą widoczne wiersze tekstu. Jeśli opuszczono, wysokość zależy od przeglądarki. Ilość wierszy nie wyznacza żadnego limitu dla wprowadzanego tekstu.
  • cols (obowiązkowy): szerokość obszaru mierzona ilością widocznych znaków. Jeśli opuszczono, szerokość zależy od przeglądarki. Wartość ta nie wyznacza żadnego limitu ilości znaków wpisywanych w jednym wierszu.
  • default (opcjonalny, można tłumaczyć) domyślna treść.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny): nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'text_area'.

Przykład definicji parametrów w pliku XML:

<param name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" />

timezones

Parametr typu timezones - Joomla w wersji 1.5.x

Params timezones.png

Parametr typu timezones umieszcza rozwijaną listę wyboru stref czasowych. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna.

  • type (obowiązkowy): musi to być timezones.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • default (opcjonalny, można tłumaczyć) domyślna strefa czasowa. Przykładowo można zastosować '-10' dla strefy '(UTC -10:00) Hawaii'.
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.

Przykład definicji parametrów w pliku XML:

<param name="mytimezone" type="timezones" default="-10" label="Select a timezone" description="" />

usergroup

Parametr typu usergroup - Joomla w wersji 1.5.x

Params usergroups.png

Parametr typu usergroup umieszcza rozwijaną listę wyboru grupy użytkowników. Jeśli wartość parametru jest zapisana w pliku params ini, zostanie pobrana i wyświetlona, jeśli - będzie wyświetlana wartość domyślna.

  • type (obowiązkowy): musi to być usergroup.
  • name (obowiązkowy): niepowtarzalne oznaczenie – nazwa parametru.
  • label (obowiązkowy, można tłumaczyć): etykieta – tytuł opisujący parametr.
  • default (opcjonalny, można tłumaczyć): domyślna grupa użytkowników. Numer identyfikacyjny (ID) grupy.
  • size (opcjonalny): liczba określająca ilość wyświetlanych wierszy. Jeśli pozycji na liście jest więcej niż ustalona tu liczba, do listy dodawany jest pasek przewijania. Jeśli opuszczono, zostanie wyświetlona lista rozwijana.
  • multiple (opcjonalny) wartość logiczna (bolean). Jeśli prawda (1), możliwy jest zaznaczenie na liście wielu pozycji. Jeśli nie zaznaczono albo fałsz (0), tylko jedna opcja może być zaznaczona [[[ Uwaga: Ta opcja aktualnie nie działa. ]]]
  • description (opcjonalny, można tłumaczyć): opis, wskazówka objaśniająca, wyświetlany jako wskazówka w dymku na stronie edytora szablonu.
  • class (opcjonalny) nazwa stylizującej pole klasy CSS. Jeśli ominięto, zostanie zastosowana standardowa 'inputbox'.

Przykład definicji parametrów w pliku XML:

<param name="myusergroups" type="usergroup" default="" label="Select a user group" description="" />

Przechowywanie wartości parametrów

Aktualne wartości parametrów szablonu przechowywane są w pliku [sciezka-do-Joomla]/templates/[template-name]/params.ini

Jeśli Twój szablon ma parametry i chcesz stworzyć pakiet instalacyjny szablonu, w sekcji <files> pliku instalacyjnego templateDetails.xml musi znajdować się element:

<files>
        ........
 
        <filename>params.ini</filename>
 
        ........
 
</files>

Instalator zadba o prawidłowe prawa własności i uprawnienia dla w stosunku do pliku params.ini

Plik params.ini w pakiecie instalacyjnym szablonu może być pusty - jako domyślne zostaną przyjęte wartości ustalone w pliku templateDetails.xml. Umieszczenie pustego pliku params.ini w pakiecie instalacyjnym zapewni jedynie, że po instalacji szablonu będzie on zapisywalny. Jeśli jednak chcesz rozprowadzać szablon z ustawionymi domyślnymi wartościami parametrów, skorzystaj z poniższej prostej procedury:

  1. Na swoim testowym systemie utwórz pusty plik params.ini file, upewnij się, że plik może być zapisywany przez serwer internetowy.
  2. Zaloguj się na zaplecze, a następnie otwórz stronę edytora szablonu i przejdź do sekcji Parametry szablonu.
  3. Ustaw dla wszystkich parametrów wartości domyślne.
  4. Naciśnij przycisk Zapisz.
  5. Sporządź kopię pliku params.ini, by umieścić go w pakiecie instalacyjnym. Teraz plik zawierać będzie domyślne wartości parametrów.

Alternatywnie, ponieważ format pliku params.ini jest bardzo prosty, możesz go stworzyć ręcznie. Jest to standardowy plik formatu INI z jednym parametrem w każdej linii. Nazwa parametru i jego wartość rozdzielone są znakiem równości. Na przykład:

templateColour=blue
authorCopyright=1

Pobieranie wartości parametrów w pliku szablonu

Aby w pliku szablonu pobrać wartości parametru, wywołaj funkcję:

<?php 
$myParam = $this->params->get( 'parameterName' ); 
?>

Na przykład, pobranie dwóch parametrów ustawionych na stronie Definiowanie parametrów w templateDetails.xml

Dla parametru templateColour ustaliliśmy wartości czterech opcji: niebieski, czerwony, zielony i czarny. Te wartości odwołują się do pliku CSS. Ustalamy więc połączenie do pliku CSS definiującego kolorystykę:

<?php
$tplColor = $this->params->get( 'templateColour' );
$this->addStyleSheet( $this->baseurl  .'/templates/'. $this->template .'/css/'. $tplColor .'.css' );
?>

Dla parametru authorCopyright ustaliliśmy wartości opcji 0 i 1, aby ukryć lub wyświetlić notę o prawach własności na dole szablonu.

<?php if ($this->params->get( 'authorCopyright' )) : ?>   
     <div class="copyright">
         Twój kod...
     </div>
<?php endif; ?>


Tworzenie własnych typów parametrów XML

Tworzenie własnych typów parametrów XML dla Joomla! Joomla w wersji 1.5.x

Listę standardowych typów parametrów obsługiwanych przez Joomla! można poszerzać o własne typy. Aby zrozumieć, jak to zrobić, przyjrzyjmy się najpierw implementacji standardowych parametrów.

Lokalizacja kodu standardowych typów parametrów

Kod standardowych typów parametrów można znaleźć w katalogu [sciezka-do-Joomla]/libraries/joomla/html/parameter/element/

Każdy typ parametru definiowany jest w odrębnym pliku, ktory musi nosić taką samą nazwę, jak typ parametru. Na przykład kod typu category znajduje się w pliku

[sciezka-do-Joomla]/libraries/joomla/html/parameter/element/category.php

Plik ten zawiera pojedynczą klasę nazwaną JElementCategory, która jest rozszerzeniem klasy JElement. Nazwy plików i klas również muszą być zgodne z konwencją nazewniczą Joomla. Plik musi nazywać się tak samo, jak typ parametru, musi zawierać klasę nazwaną JElement[nazwa-elementu], bo w framework Joomla nie potrafi rozpoznać, przetworzyć i obsłużyć parametru.


Rozpoczynamy tworzenie własnego typu parametru

Aby stworzyć własny typ parametru, musimy najpierw wybrać jego nazwę. Przyjmijmy, że będzie się nazywać nowyparam. W ulubionym edytorze tworzymy nowy plik nazwany nowyparam.php, zawierający jedną klasę, nazwaną JElementNowyparm, która jest rozszerzeniem klasy JElement.

Kod nowego parametru można umieścić gdziekolwiek, ale zwyczajowo powinien być umieszczony w swoim własnym podkatalogu albo w tym samym, w którym umieszczono kod innych standardowych parametrów.

Nowy typ parametru będzie najprawdopodobniej związany z konkretnym rozszerzeniem, więc najpewniej właściwe będzie umieszczenie kodu parametru w pakiecie instalacyjnym tego rozszerzenia.

W lokacji pliku mamy dużą swobodę, zależy ona w pewnej mierze od projektowanego rozszerzenia. W przypadku szablonów zalecane jest umieszczenie ich w katalogu

sciezka-do-Joomla]/templates/[nazwa-szablonu]/elements/newparm.php


Zmiana w pliku XML związana z własnym typem parametru

W pliku konfiguracyjnym XML konieczne są dwie poprawki. Po pierwsze, upewnij się, że plik zawiera sekcję z listą plików - <files>:

<files>
    ........
    <filename>elements/index.html</filename>
    <filename>elements/newparm.php</filename>
    ........
</files>

Porada: To dobra praktyka, by w katalogach Joomla! umieszczać pusty plik index.html, który stanowi dodatkową ochronę przed podglądem zawartości katalogu w przypadku błędów serwera.

Alternatywnie, możesz po prostu włączyć cały katalog elements używając znacznika <folders>:

<files>
    ........
    <folder>elements</folder>
    ........
</files>

Drugą konieczną poprawką jest powiadomienie frameworka Joomla!, że został dodany nowy typ parametru oraz ścieżce do kodu tego parametru. Aby to uczynić, dodajemy argument addpath do znacznika <params>:

<params addpath=”[path]/elements”>
   ...... list of <param> elements ......
</params>

Zwróć uwagę, że dodajemy ścieżkę do katalogu zawierajacego kod parametru, a nie do pliku z kodem.

Zwróć również uwagę, że masz jeden argument addpath , tak więc, jeśli dodajesz wiele własnych parametrów, musisz umieścić je w jednym tym samym podkatalogu i ten subkatalog musi zawierać tylko kod definicji typu parametru.

Przykład zastosowania nowego elementu w znaczniku <params>, w pliku templeDetails.xml :

<params addpath=”[path-Joomla]/templates/mytemplate/elements”>
    <param type=”newparm” name=”setting1” default=”12” />
    <param type=”text” name=”setting2” value=”Some text” />
</params>

Kodowanie własnego typu parametru

Najprostszym sposobem napisania kodu nowego parametru jest skopiowanie kodu istniejącego podobnego typu parametru i dostosować go do własnych potrzeb. Podstawowa klasa JElement zawiera prawie wszystko, co potrzebne, więc w przypadku większości nowych własnych typów parametrów wystarczy zastosowanie metody fetchElement, by rozszerzyć klasę JElement.

Metoda fetchElement zwraca kod HTML wymagany, by przetworzyć pole, które zostanie zastosowane do ustawienia wartości parametru. Wymaga czterech argumentów:

fetchElement( $name, $value, &$node, $control_name )

gdzie:

$name jest unikalną nazwą parametru, z argumentu name.
$value jest bieżącą wartością parametru.
$node jest obiektem JSimpleXMLElement reprezentujacym element <param>.
$control_name jest typem parametru z argumentu type (np. 'category' albo 'nowyparm')

Aby otrzymać wartość argumentu w elemencie <param>, używamy metody attribute z obiektu JSimpleXMLElement passed in $node. Na przykład, aby otrzymać wartość argumentu class, możesz użyć kodu jak poniżej:

$class = $node->attributes( 'class' );

Przykładowo, poniżej zastosowano metodę fetchElement w prostej wersji parametru typu text (faktyczna wersja jest bardziej wyszukana - skomplikowana):

function fetchElement( $name, $value, &$node, $control_name )
{ 
    $class = $node->attributes( 'class' ) ? $node->attributes( 'class' ) : "text_area";
 
    $return = '<input type="text"' .
                     'name="' . $control_name . '[' . $name . ']"' .
                     'id="'   . $control_name . '[' . $name . ']"' .
                     'value="' . $value . '"' .
                     'class="' . $class . '" />'; 
    return $return;
}
Ikona informacja.png
 Informacja

 Zauważ, że pole parametru musi mieć cechę id, z wartością pokazaną w tym przykładzie, więc, że < etykieta > element HTML dał plony przez domyślną metodę fetchTooltip będą pasowali z tym poprawnie.


Jedyną inną metodą klasy JElement, którą można chcieć nadpisać, jest metoda fetchTooltip. Metoda ta zwraca kod HTML potrzebny, by dodać do pola dymek (poradę, objaśnienie). W większości przypadków odpowiedni będzie standardowy kod i nie będziesz potrzebował nadpisywać (zmieniać?, modyfikować) tej metody. Wymaga ona pięciu argumentów.

fetchTooltip( $label, $description, &$node, $control_name=,$name= )

gdzie:

$label jest napisem otrzymywanym z argumentu label w definicji <param>. Napis należy przed użyciem poddać tłumaczeniu
$description jest napisem otrzymywanym z argumentu description w definicji <param>. Napis należy przed użyciem poddać tłumaczeniu ( It should be passed through the language translation system before being used).
$node jest obiektem JSimpleXMLElement reprezentujacym element <param>.
$control_name jest typem parametru z argumentu type (np. 'category' albo 'nowyparm').
$name jest unikalną nazwą parametru, z argumentu name.

Aby przekazać napis do systemu tłumaczenia (Aby poddać napis systemowi tłumaczenia), musimy użyć statycznej klasy 'JText, jak poniżej:

$output = JText::_( 'ten napis będzie tłumaczony' );
© Tłumaczenie: zwiastun. Tłumaczenie wykonano na warunkach licencji JEDL.


Wyrażenia regularne w argumentach parametrów

Wyrażenia regularne w argumentach parametrów - Joomla! Joomla w wersji 1.5.x J 16.png J 17.png

Niektóre argumenty parametrów mogą posiadać, jako wartość, wyrażenie regularne. Na przykład, argumenty filter i exclude dla typów parametrów filelist i imagelist. Jest to niezwykle przydatne, ale wymaga większej wiedzy na temat składni wyrażeń regularnych, aby móc używać ich efektywnie.

Opisano tu przykłady prostych wyrażeń regularnych, które można używać w kontekście parametrów szablonu. Pełne odniesienie do składni wyrażeń regularnych wykracza poza zakres tej wiki, ale można znaleźć w Internecie więcej informacji na ten temat.

Prosty filtr ciągu

Załóżmy, że chcesz użyć parametru typu filelist, aby wyświetlić listę plików w danym katalogu. Istnieje wiele plików w katalogu, ale chcesz by wymienione były tylko te z rozszerzeniem '.php'. Następnie należy użyć tego argumentu w elemencie <param>

filter = “\.php”

Pierwszą rzeczą, na którą trzeba zwrócić uwagę jest wiodący znak backslash. Jest to konieczne, ponieważ znak "." ma specjalne znaczenie w wyrażeniach regularnych. Znak backslasha powoduje że pierwszy znak za nim traktowany jest dokładnie takim jakim jest, co da nam zwykłą kropkę ".".

Efektem zastosowania tego filtru, będą tylko te pliki, które w dowolnym miejscu swojej nazwy, posiadają te znaki w takiej kolejności występowania “.”, “p”, “h”, “p”

Mocowanie do końca łańcucha

Jeśli zastosujemy filtr z poprzedniego przypisu, to mając plik o nazwie configuration.php-dist - zostałby on zaakceptowany, gdyż znajduje się w nim ciąg “.php” w środku łańcucha. Jeśli naszym zamiarem było uzyskanie tylko plików kończących się na ".php" powinniśmy zastosować filtr:

filter = “\.php$”

Znak "$" (dolar) w wyrazeniu regularnym odpowiada za to, że szukany ciąg musi znajdować się na końcu łańcucha. Dzięki temu plik configuration.php zostanie zaakceptowany, a configuration.php-dist już nie.

Mocowanie do początku łańcucha

Jeśli chcesz by wybrane zostały tylko te plik, które zaczynają się od słowa "joomla", filtr powinien wyglądać tak:

filter = “^joomla”

Znak “^” w wyrażeniach regularnych odpowiada za to, by poszukiwane wyrażenie zaczynało się dokładnie na początku przeszukiwanego łańcucha.

Mocowanie na obu końcach łańcucha

Jeśli chciałbyś wyświetlić wszystkie pliki zaczynające się od słowa “joomla” i kończące się na “.php”, nie dbając o to co znajduje się pomiędzy nimi, to filtr powinien wyglądać tak:

filter = “^joomla(.*)\.php$”

Znak "^" powoduje poszukiwanie na początku łańcucha słowa "joomla", a znak "$" powoduje że poszukiwany ciąg ma kończyć się na ".php". Dodatkowo w środku znajduje się "(.*)" co oznacza że pomiędzy końcem a początkiem wyszukiwanego ciągu może znajdować się dowolny pojedynczy znak (to ta "."), i może on występować dowolną ilość razy, w tym nawet zero razy (to ta "*"). Nawiasy służą do oddzielenia tego ciągu od reszty poszukiwanych fraz.

Rozróżnianie wielkości liter

Należy pamiętać że wyrażenia regularne rozróżniają wielkości liter. Stosując poprzednie przykłady, możemy natrafić na pliki zaczynające się zarówno od "Joomla" jaki i "joomla". Niestety te z "Joomla" nie zostaną załadowane. Aby temu zaradzić należy zastosować taki filtr:

filter = “^[Jj]oomla”

Dzięki zapisowi "[Jj]" zostaną dopasowane słowa "Joomla" i "joomla". Nawiasy kwadratowe “[]” wskazują nam klasę znaków i powinny zawierać wszystkie znaki jakie chcemy dopasować. Na przykład jeśli poszukiwany ciąg miałby dopasować te litery “s”, “t”, “u” or “v” należałoby zapisać to tak:

filter = “^[stuv]oomla”
 
czyli pasowałyby : soomla, toomla, uoomla, voomla

lub tak (bo są one ułożone kolejno w alfabecie):

filter = “^[s-v]oomla”
 
czyli pasowałyby : soomla, toomla, uoomla, voomla

lub tak, jeśli miały by to być i małe i duże litery:

filter = “^[s-vS-V]oomla”
 
czyli pasowałyby : soomla, toomla, uoomla, voomla, Soomla, Toomla, Uoomla, Voomla

Filtrowanie listy rozszerzeń

Jeśli chcesz filtrować pliki w zależności od rozszerzenia danego pliku, i jeśli to ma być tylko jedno rozszerzenie, powinieneś zastosować taki filtr:

filter = “\.php$”

Ale co, gdy chcesz kilka rodzajów rozszerzeń, np. “.php”, “.html” i “.txt” ? Należy to zrobić tak:

filter = “\.php$|\.html$|\.txt$”

Znak "|" powoduje, że dopasowane może być alternatywnie to |lub to |lub to

Można zauważyć że typ parametru imagelist (oraz podobnie filelist) zawierają właśnie taki filtr

filter = “\.png$|\.gif$|\.jpg$|\.bmp$|\.ico$”


Dziękujemy za wkład

» Stefan Wajda [zwiastun],