Tekst źródłowy strony Tworzenie własnych typów pól formularza XML

'''Tworzenie własnych typów pól formularza''' dla Joomla! {{j_16}} {{j_17}}

JForm , funkcja wprowadzona w Joomla 1.6, umożliwia łatwe tworzenie formularzy HTML ( <form> ). Formularze utworzone za pomocą JForm składają się z pól formularza , i realizowane są za pomocą klasy JFormFields . 
Każdy typ pola, który można znaleźć w formularzu, dziedziczy po JFormFields. JForm obsługuje szeroki wybór standardowych typów. Aby uzyskać pełną listę można zobaczyć [[Standardowe typy pól formularzy]] .

Joomla 1.6 umożliwia używanie standardowych typów pól, lub zdefiniowanych własnych. Na przykład, jeśli Twój komponent zarządza wpisami do książki telefonicznej, można określić typ pola formularza, który zawiera wybieralną listę miast. Istnieje wiele korzyści do zdefiniowania niestandardowego typu pola formularza:

*Będziesz mógł mieszać standardowe typy pól z niestandardowymi typami pól w formularzu bazującym na JForm.
*Będziesz mógł mieć paczkę kodu wielokrotnego użytku, który można wykorzystać łatwo w całym kodzie.
*Rozszerzenia, które współpracują z Twoim rozszerzeniem będą miały możliwość tworzenia pól formularza bez ingerencji w  tabele bazy danych i inne zewnętrzne aplikacje. 


== Wymagania dla nowego typu pola formularza ==

Typ pola formularza jest zdefiniowany w klasie, która musi być (niekoniecznie bezpośrednio) podklasą JFormField. Aby działać prawidłowo, klasa ta musi określić co najmniej dwie metody:

* <code>public function getLabel()</code>
*: Funkcja ta zostanie użyta do tworzenia etykiet, które należą do Twojego typu pola i musi zwracać ciąg HTML, który te etykiety zawiera. Klasa JFormField definiuje gotową do użycia  metodę <code>getLabel()</code> więc zazwyczaj w  niestandardowych typach pól formularzy, nie trzeba definiować nowego <code> getLabel()</code> . Jeśli pominiesz definiowanie własnego <code>getLabel()</code>, metody tworzenia etykiet zostaną odziedziczone z klasy JFormField. Zaleca się, aby pominąć metodę<code> getLabel()</code> dla spójności i prędkości, chyba że faktycznie chcesz zmodyfikować etykiety HTML.

* <code>public function getInput()</code>
*: Funkcja ta zostanie użyta do tworzenia samego pola i musi zwrócić ciąg HTML, który te pole zawieraja. To właśnie tutaj najczęściej dochodzi do przetwarzania danych. W naszej książce telefonicznej, przykładowo pole formularza ''Miasta'', będzie zawierać kilka miast do wyboru. Funkcja ta będzie musiała pobrać listę dostępnych miast i zwrócić kod HTML z pola <code><select></code> z miastami zawartymi w polu <code><option></code>.


Aby użyć atrybutów - zdefiniowanych przez użytkownika - wewnątrz kodu, należy je odpowiednio pobrać z pliku XML. Niektóre z atrybutów, są dostępne za pośrednictwem chronionych zmiennych z JFormField. Na przykład, atrybut <code>name</code> jest dostępny w kodzie jako <code>$this->name </code>. Podobnie jest z <code>label</code> , <code>description</code> , <code>default</code> , <code>multiple</code> i <code>class</code> - są one również dostępne jako właściwości <code>$this</code> . Inne parametry które sam zdefiniujesz, są dostępne poprzez <code>$this->element</code> tablicy: atrybut <code>size</code> będzie dostępny jako  <code>$this->element['size']</code> .

== Do jakiej klasy przypisać podklasę? ==

Typ pola formularza, aby nadawał się do wykorzystania w JForm, nie potrzebuje być podklasą JFormField. Nie musi być bezpośrednim dzieckiem tej klasy: można również wykorzystać podklasy istniejących (standardowych i niestandardowych) typów pola formularza, a tym samym odziedziczyć po nich przydatny kod.

'''Jeśli typ pola formularza jest dość podobny do istniejącego typu''', powinieneś użyć podklasy tego typu. Zwłaszcza, jeśli Twój typ pola formularza to '''list''', powinieneś użyć podklasy JFormFieldList . Trzeba tylko zmienić <code>getOptions()</code> aby metoda zwróciła opcje do pokazania; Metoda <code>getInput()</code> przekonwertuje te opcje do HTML.

Aby dodać podklasę istniejącego już typu, np. JFormFieldList, należy załadować, dodając po <code>jimport('joomla.form.formfield');</code> następujący wpis:

<source lang="php">
jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');
</source>

'''Jeśli Twój typ pola formularza, nie jest podobny do żadnego istniejącego już typu''', należy odwołać się bezpośrednio do podklasy JFormField.

== Lokalizacja plików ==

* Standardowe typy pól formularza znajdują się w '''joomla/libraries/joomla/form/fields/''' . Nie należy przechowywać tam własnych typów pól, ani nie powinno się korzystać z tej ścieżki w swoim własnym kodzie. Standardowe typy, są również przydatne jako przykłady, jak powinien wyglądać własny typ.

* Niestandardowe typy pól, które należą do Twojego komponentu, powinny znajdować się zwykle w <code>administrator/components/<nazwa_Twojego_komponentu>/models/fields</code> . Ścieżkę do nich można określić np. w ten sposób:
<source lang="php">JForm::addFieldPath(JPATH_COMPONENT . DS . 'models' . DS . 'fields');</source>

* Pliki XML, które definiują formularze, zwykle znajdują się w <code>administrator/components/<nazwa_Twojego_komponentu>/models/forms . Aby dodać ścieżkę do nich, możesz użyć np. takiego kodu:

<source lang="php">JForm::addFormPath(JPATH_COMPONENT . DS . 'models' . DS . 'forms');</source>

== Konwencja nazewnictwa oraz szkielet konstrukcji ==

Pliki definiujące Twoje typy pól formularzy, powinny znajdować się w <code>administrator/components/<NazwaTwojegoKomponentu>/models/fields/</code> i nazywać się tak samo jak typ pola formularza.
Na przykład, tworząc typ o nazwie '''color''', plik z jego kodem powinien nazywać się '''color.php''', a ścieżka dostępu do niego powinna wyglądać tak: <code>administrator/components/<NazwaTwojegoKomponentu>/models/fields/color.php</code>. Konstrukcja pliku powinna wyglądać tak:


<source lang="php"><?php
// Sprawdzanie czy ten plik wywołany został z Joomla!
defined('_JEXEC') or die('Dostęp zabroniony');

jimport('joomla.form.formfield');

// Nazwa klasy musi być taka sama jak nazwa pliku 
//(czyli taka sama jak nazwa typu pola formularza) np. plik=color.php to <NazwaPola>=color
class JFormField<NazwaPola> extends JFormField {

	//Musimy przypisać zmiennej $type wartość, którą jest nazwa naszego typu pola formularza .
	protected $type = '<NazwaPola>';

	public function getLabel() {
	// kod zwracany do HTML który będzie odpowiedzialny za wyświetlanie etykiety
	}

	public function getInput() {
	// kod zwracany do HTML który będzie odpowiedzialny za wyświetlanie pola formularza
	}
} 
</source>

=== Grupowanie niestandardowych typów pól ===

{{Uwaga|W Joomla! 1.6 i nowsze, istnieje możliwość grupowania niestandardowych typów pól formularzy, lecz nie jest to jeszcze dokładnie i poprawnie opisane.
Informacja o tym znajduje się tutaj [http://docs.joomla.org/Creating_a_custom_form_field_type#Grouping_custom_field_types docs.joomla.org] }}

== Przykład niestandardowego typu pola formularza ==

Suppose you're working on your component named ''com_phonebook'' and you want to define a field that contains cities. Create the file <code>administrator/components/com_phonebook/models/fields/city.php</code> and write something similar to the following:

Załóżmy, że pracujesz nad komponentem o nazwie ''com_ksiazkatelefoniczna'' i chcesz zdefiniować pole, które zawiera nazwy miast. Utwórz plik <code>administrator/components/com_ksiazkatelefoniczna/models/fields/miasta.php</code> i napisz coś podobnego do następującego:

<source lang="php"><?php
// Sprawdzenie czy plik został wywołany z Joomla!
defined('_JEXEC') or die('Dostęp zabroniony');

jimport('joomla.form.formfield');

class JFormFieldMiasta extends JFormField {
	
	protected $type = 'Miasta';

	// getLabel() pomijamy

	public function getInput() {
		return '<select id="'.$this->id.'" name="'.$this->name.'">'.
		       '<option value="1" >Warszawa</option>'.
		       '<option value="2" >Lębork</option>'.
		       '<option value="3" >Kraków</option>'.
		       '</select>';
	}
} 
</source>

=== Korzystanie z niestandardowego typu pola ===

Aby korzystać z pola typu '''Miasta''', musimy zaktualizować plik XML zawierający pola formularza. Otwórz plik XML, znajduje się on w <code>administrator/components/com_ksiazkatelefoniczna/models/forms i dodaj pole w tradycyjny sposób:

<source lang="xml"><field name="tytuł" type="Miasta" label="JGLOBAL_TYTUL"
	description="JFIELD_TYTUL_OPIS"
	required="true" /></source>

Nazwa typu pola nie rozróżnia wielkości liter. Miasta == miAsTA

== Zastępowanie getLabel() ==

Jak wspomniano w sekcji '''[[#Wymagania dla nowego typu pola formularza]]''', niestandardowe typy pól formularza, zazwyczaj nie definiują swojej metody <code>getLabel()</code> . Jeśli chcesz utworzyć własną etykietę, nadal możesz korzystać z <code>getLabel()</code> , pamiętając że każda klasa typu pola, dziedziczy z JFormField, na przykład poprzez zdefiniowanie w następujący sposób:

<source lang="php">public function getLabel() {
     return '<span style="text-decoration: underline;">' . parent::getLabel() . '</span>';
} </source>

Ten kod spowoduje że wszystkie etykiety zostaną podkreślone. Oczywiście , jeśli naszym celem byłoby tylko wprowadzenie podkreślania etykiet, lepiej wykonać to za pomocą CSS.
Nie mniej przykład ten pokazuje nam jak wprowadzać drobne zmiany w etykietach nie pisząc ich kodu od nowa.

Jeśli jednak chcesz zrobić całkowicie nową etykietę możesz to wykonać na przykład tak:

<source lang="php">public function getLabel() {
	// Inicjalizacja zmiennych
	$label = '';
	$replace = '';

	// Pobranie tekstu etykiety z elementu XML, standardowo jest to nazwa elementu.
	$text = $this->element['label'] ? (string) $this->element['label'] : (string) $this->element['name'];

	// Tworzenie klasy etykiety.
	$class = !empty($this->description) ? 'hasTip' : '';
	$class = $this->required == true ? $class.' required' : $class;
		
	// Dodaje pole wyboru checkbox
	$replace = '<input type="checkbox" name="update['.$this->name.']" value="1" />';
		
	// Dodaje tag otwierający etykiety  i głównych atrybutów.
	$label .= '<label id="'.$this->id.'-lbl" for="'.$this->id.'" class="'.$class.'"';

	// Jeśli podany jest Opis, używamy go do zbudowania tooltip-a.
	if (!empty($this->description)) {
		$label .= ' title="'.htmlspecialchars(trim(JText::_($text), ':').'::' .
				JText::_($this->description), ENT_COMPAT, 'UTF-8').'"';
	}

	// Dodaje tekst i zamykający tag etykiety.
	$label .= '>'.$replace.JText::_($text).'</label>';
	
	return $label; 
}</source>

Ten przykład doda przed etykietą pole wyboru typu ''checkbox''.

<noinclude>
== Typy parametrów ==
{{NTP}}
{{NTPF}}

== Zobacz także ==
{{NTPL}}
<noinclude>
[[Kategoria:Formularze|{{{PAGENAME}}}]]
[[Kategoria:Programiści]]
[[Kategoria:Programowanie]]
</noinclude>