--=REKLAMA=--
--=REKLAMA=--
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 04: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.
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ść.
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:
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>.
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:
Poniższe argumenty są opcjonalne, ale wspólne dla prawie wszystkich typów parametrów:
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 | & |
| “ | Podwójny apostrof | " |
| ' | Pojedynczy apostrof | ' |
| < | Mniejsze od | < |
| > | Większe od | > |
Ż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
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 dla Joomla! 
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.
Parametr typu calendar -
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.
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.
Parametr typu category -
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.
Przykład definicji parametrów w pliku XML:
<param name="mycategory" type="category" label="Select a category" description="" section="3" />
Parametr typu editors -
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.
Przykład definicji parametrów w pliku XML:
<param name="myeditor" type="editors" default="none" label="Select an editor" />Parametr typu filelist -
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'.
Przykład definicji parametrów w pliku XML:
<param name="myfile" type="filelist" default="" label="Select a file" description="" directory="administrator" filter="" exclude="" stripext="" />Parametr typu folderlist -
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'.
Przykład definicji parametrów w pliku XML:
<param name="myfolder" type="folderlist" default="" label="Select a folder" directory="administrator" filter="" exclude="" stripext="" />Parametr typu helpsites -
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.
Przykład definicji parametrów w pliku XML:
<param name="myhelpsite" type="helpsites" default="" label="Select a help site" description="" />Parametr typu hidden -
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.
Przykład definicji parametrów w pliku XML:
<param name="mysecretvariable" type="hidden" default="" />Parametr typu imagelist -
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'.
Przykład definicji parametrów w pliku XML:
<param name="myimage" type="imagelist" default="" label="Select an image" description="" directory="" exclude="" stripext="" />Parametr typu languages -
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'.
Przykład definicji parametrów w pliku XML:
<param name="mylanguage" type="languages" client="site" default="en-GB" label="Select a language" description="" />Parametr typu list -
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.
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:
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>
Parametr typu menu -
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'.
Przykład definicji parametrów w pliku XML:
<param name="mymenu" type="menu" default="mainmenu" label="Select a menu" description=”Select a menu” />Parametr typu menuitem -
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ć).
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” />Parametr typu password -
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ą.
Przykład definicji parametrów w pliku XML:
<param name="mypassword" type="password" default="secret" label="Enter a password" description="" size="5" />Parametr typu radio -
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.
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:
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>
Parametr typu section -
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.
Przykład definicji parametrów w pliku XML:
<param name="mysection" type="section" default="" label="Select a section" description="" />Parametr typu spacer -
Parametr typu spacer umieszcza poziomą linię rozdzielającą wizualnie pola parametrów. Jest to element czysto graficzny, nie przechowuje żadnych wartości.
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="<b>Advanced parameters</b>" />Parametr typu sql -
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.
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!.
Parametr typu text -
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.
Przykład definicji parametrów w pliku XML:
<param name="mytextvalue" type="text" default="Some text" label="Enter some text" description="" size="10" />Parametr typu textarea -
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.
Przykład definicji parametrów w pliku XML:
<param name="mytextarea" type="textarea" default="default" label="Enter some text" description="" rows="10" cols="5" />Parametr typu timezones -
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.
Przykład definicji parametrów w pliku XML:
<param name="mytimezone" type="timezones" default="-10" label="Select a timezone" description="" />Parametr typu usergroup -
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.
Przykład definicji parametrów w pliku XML:
<param name="myusergroups" type="usergroup" default="" label="Select a user group" description="" />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:
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
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 dla Joomla!
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.
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.
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
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>
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; }
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' );
Wyrażenia regularne w argumentach parametrów - Joomla! 
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.
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”
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.
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.
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.
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
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$”