--=REKLAMA=--

Tworzenie własnych typów pól formularza XML

Z Joomla!WikiPL

Wersja Zwiastun (dyskusja | edycje) z dnia 15:46, 10 gru 2013

(różn.) ← poprzednia wersja | przejdź do aktualnej wersji (różn.) | następna wersja → (różn.)

Tworzenie własnych typów pól formularza dla Joomla! J 16.png J 17.png

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:

  • public function getLabel()
    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ę getLabel() więc zazwyczaj w niestandardowych typach pól formularzy, nie trzeba definiować nowego getLabel() . Jeśli pominiesz definiowanie własnego getLabel(), metody tworzenia etykiet zostaną odziedziczone z klasy JFormField. Zaleca się, aby pominąć metodę getLabel() dla spójności i prędkości, chyba że faktycznie chcesz zmodyfikować etykiety HTML.
  • public function getInput()
    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 <select> z miastami zawartymi w polu <option>.


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 name jest dostępny w kodzie jako $this->name . Podobnie jest z label , description , default , multiple i class - są one również dostępne jako właściwości $this . Inne parametry które sam zdefiniujesz, są dostępne poprzez $this->element tablicy: atrybut size będzie dostępny jako $this->element['size'] .

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ć getOptions() aby metoda zwróciła opcje do pokazania; Metoda getInput() przekonwertuje te opcje do HTML.

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

jimport('joomla.form.helper');
JFormHelper::loadFieldClass('list');

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 administrator/components/<nazwa_Twojego_komponentu>/models/fields . Ścieżkę do nich można określić np. w ten sposób:
JForm::addFieldPath(JPATH_COMPONENT . DS . 'models' . DS . 'fields');
  • Pliki XML, które definiują formularze, zwykle znajdują się w administrator/components/<nazwa_Twojego_komponentu>/models/forms . Aby dodać ścieżkę do nich, możesz użyć np. takiego kodu:
JForm::addFormPath(JPATH_COMPONENT . DS . 'models' . DS . 'forms');

Konwencja nazewnictwa oraz szkielet konstrukcji

Pliki definiujące Twoje typy pól formularzy, powinny znajdować się w <code>administrator/components/<NazwaTwojegoKomponentu>/models/fields/ 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: administrator/components/<NazwaTwojegoKomponentu>/models/fields/color.php. Konstrukcja pliku powinna wyglądać tak:


<?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
	}
}

Grupowanie niestandardowych typów pól

Ikona informacja.png
 Informacja

 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 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 administrator/components/com_phonebook/models/fields/city.php 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 administrator/components/com_ksiazkatelefoniczna/models/fields/miasta.php i napisz coś podobnego do następującego:

<?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>';
	}
}

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 administrator/components/com_ksiazkatelefoniczna/models/forms i dodaj pole w tradycyjny sposób:

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

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() . Jeśli chcesz utworzyć własną etykietę, nadal możesz korzystać z getLabel() , pamiętając że każda klasa typu pola, dziedziczy z JFormField, na przykład poprzez zdefiniowanie w następujący sposób:

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

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:

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; 
}

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


Typy parametrów

Lista wszystkich typów parametrów dla Joomla! 1.5

calendar  : category : editors  : filelist  : folderlist  : helpsites  : hidden  : imagelist  : languages  : list  : menu  : menuitem  : password  : radio  : section  : spacer  : sql  : text  : textarea  : timezones  : usergroup

Lista wszystkich typów pól formularzy dla Joomla! 1.7

accesslevel  : cachehandler  : calendar  : category  : checkbox  : checkboxes  : combo  : componentlayout  : contentlanguage  : editor  : editors  : file  : filelist  : folderlist  : groupedlist  : helpsite  : hidden  : imagelist  : integer  : language  : list  : media  : menu  : menuitem  : modulelayout  : password  : radio  : rules  : sessionhandler  : spacer  : sql  : templatestyle  : text  : textarea  : timezone  : user  : usergroup

Zobacz także



Dziękujemy za wkład

» Stefan Wajda [zwiastun],