FormEngine

Gekosale's
FormEngine
DOKUMENTACJA TECHNICZNA
1. Czym jest FormEngine?
Gekosale,
jako
rozbudowany
system
mający
charakter
aplikacji
internetowej,
do wprowadzania i zarządzania zawartością wykorzystuje przystępne dla użytkownika
formularze. Mając świadomość tego, że dla użytkownika systemu te liczne formularze
będą narzędziem codziennej pracy, nasz Zespół postawił sobie za główny cel wygodę ich
obsługi.
Wykorzystując nowoczesne techniki działające po stronie przeglądarki internetowej,
stworzyliśmy unikalny charakter pracy z systemem Gekosale. Klasyczne elementy
interfejsu użytkownika nigdy nie były tak wygodne w obsłudze i nie dawały takich
możliwości użytkownikowi. Przemyślany i zaawansowany sposób działania komunikacji
użytkownika z systemem stał się jednym z kluczowych elementów, dzięki którym Gekon
zyskał dzisiejszą popularność.
Jednak działające po stronie klienta elementy wymagają odpowiedniego wsparcia ze
strony serwera. Z myślą o osobach piszących rozszerzenia do Systemu, o osobach
wdrażających specjalistyczne rozwiązania oparte o Gekosale, oraz o nas samych, byliśmy
zmuszeni opracować wygodny i elastyczny sposób generowania formularzy. Po próbach i
przejściach z QuickFormem z biblioteki Pear, zdecydowaliśmy się postawić na własne,
przystosowane do potrzeb Gekona rozwiązanie. Tak właśnie powstał FormEngine – do bólu
obiektowy, do szaleństwa prosty i do obłędu rozszerzalny silnik generowania i obsługi
formularzy.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
2. Korzystanie z FormEngine
Struktura formularzy tworzonych w oparciu o FormEngine ma charakter hierarchii.
Formularz, będący elementem nadrzędnym, korzeniem całego drzewa, posiada swoich
potomków. Są to elementy-kontenery, elementy-pola oraz jeden element specjalny –
statyczny.
Elementy struktury formularzy
Kontenery są pojemnikami, które tworzą głębszy poziom w strukturze formularza. Mogą
one zawierać kolejnych potomków, które również mogą być kontenerami. Zresztą sam
korzeń również jest swojego rodzaju kontenerem. Kontener, choć to oczywiście zależy od
intencji twórcy szablonu, może być tłumaczony najczęściej jako element typu <fieldset/>.
Często, na pierwszym poziomie hierarchii, można to utożsamiać z podziałem formularza
na zakładki. Tak właśnie jest to rozwiązane w standardowym Panelu Administracyjnym.
Pola są natomiast elementami, które przyjmują wartości. Są to namacalne elementy
interfejsu użytkownika. Od najprostszych pól tekstowych, przez listy wyboru, edytory Rich
Text, po skomplikowane aplikacje DataGrida i jemu podobnych, charakterystycznych dla
Gekosale cząstek.
Element służy zaś prezentacji krótkiej treści, przerywnika, informacji. Jest niezmienny,
choć może być zależny od wartości pozostałych pól.
Prawdziwą moc kontenerów i hierarchicznego sposobu budowania formularzy można sobie
uświadomić, gdy odkryje się możliwość powtarzalności. Korzystając ze specjalnego
rodzaju powtarzalnych kontenerów można uzyskać fragment formularza, który pozwolimy
użytkownikowi powielać dowolną (lub ograniczoną przez nas) liczbę razy. Jeśli dołączyć do
tego możliwość zwielokrotniania wartości wpisywanych w pojedyncze pola, uzyskujemy
nieopisaną elastyczność.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Inicjalizacja formularza
Miejscem, w którym FormEngine rozwija skrzydła, jest kontroler. Tam inicjujemy
formularz, dodajemy do niego odpowiednie kontenery i pola, ustalamy reguły walidacji,
zależności
między
polami,
filtrację
wartości,
czy
wreszcie
dokonujemy
walidacji
przesłanych danych i wykorzystujemy je po wstępnej obróbce.
Pierwszym krokiem jest inicjalizacja formularza. Jest to utworzenie obiektu klasy FE_Form,
której konstruktor przyjmuje jeden parametr – tak, jak każdy element formularza – który
jest tablicą asocjacyjną składającą się z danych konfiguracyjnych.
$form = new FE_Form(Array(
'name' => 'add_user',
'action' => '/users/add',
'method' => 'post'
));
Każda z klas, a więc każdy z elementów formularza, posiada zasób rozumianych przez nią
danych konfiguracyjnych. Ich listy można znaleźć w dalszej części dokumentacji.
W tym momencie należy zwrócić uwagę, że nazwa (name) formularza musi być
unikatowa. Jest to wykorzystywane w mechanizmie przetwarzania danych.
Budowa formularza
Kiedy formularz został już zainicjalizowany, możemy przystąpić do ustalania jego
zawartości. Do tego celu posłużymy się metodą AddChild() będącą częścią każdego
rodzaju kontenera, a więc i samego formularza będącego kontenerem-korzeniem.
$personalData = $form->AddChild(new FE_Fieldset(Array(
'name' => 'personal_data',
'label' => $this->registry->core->getMessage('TXT_PERSONAL_DATA')
)));
Dzięki powyższemu fragmentowi kodu dodajemy do formularza nowy kontener. Posłuży on
nam do zgrupowania pól dotyczących danych osobowych użytkownika.
Wartość zwrócona z metody AddChild(), czyli de facto nowoutworzony element formularza,
jest użyteczna w wielu późniejszych działaniach – jak choćby podczas dodawania reguł
walidacji, czy zależności między polami. W przypadku kontenera jest ona używana w celu
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
dodawania doń nowych pól, mających się stać jego potomkami.
Pora dodać pole tekstowe, w którym użytkownik wpisze swoje imię.
$personalData->AddChild(new FE_TextField(Array(
'name' => 'firstname',
'label' => $this->registry->core->getMessage('TXT_FIRSTNAME'),
'help' => $this->registry->core->getMessage('TXT_FIRSTNAME_HELP'),
'rules' => Array(
new FE_RuleRequired($this->registry->core
->getMessage('ERR_EMPTY_FIRSTNAME'))
)
)));
Jak widać w powyższym fragmencie kodu, tym razem wywołujemy metodę AddChild() nie
dla formularza, lecz dla naszego utworzonego chwilę wcześniej kontenera. Dzięki temu
pole stanie się jego potomkiem.
Widzimy też ciekawą opcję konfiguracyjną – rules – która jest tablicą reguł walidacji.
W naszym przykładzie pole to jest wymagane, więc walidacja nie powiedzie się, gdy
użytkownik pozostawi je puste. Parametrem konstruktora reguły jest komunikat mówiący
o niepowodzeniu.
Reguły można też alternatywnie dodawać do pola w inny sposób. Jeśli nowoutworzone
pole przypiszemy do zmiennej $firstname, wówczas możemy regułę dodać później w
poniższy sposób:
$firstname->AddRule(
new FE_RuleFormat('Imię jest błędne', '/[a-zA-Z ]{3,}/')
);
Przy okazji dowiedzieliśmy się, że łatwo można dodawać reguły oparte o wyrażenia
regularne.
Warto wspomnieć, że reguły (a także filtry i zależności – choć te ostatnie nie są zalecane
w takim użyciu) można dodawać do kontenerów. Wówczas zostaną one automatycznie
dodane do wszystkich ich potomków. Musimy jedynie pamiętać, że w przypadku
kontenerów reguły można dodawać jedynie sposobem AddRule(), a nie w tablicy
konstruktora.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Wypełnianie formularza danymi i ich pobieranie z formularza
Użytkownikowi
często
trzeba
pomóc
w
wyborze.
Dlatego
dostarczenie
wartości
domyślnych jest w wielu przypadkach niezbędne. W tym celu należy użyć metody
Populate(), którą można wywołać zarówno dla całego formularza, jak i dla pojedynczego
pola.
$form->Populate($userData);
Należy pamiętać, by nie dokonywać tego przed ukończeniem określania struktury
formularza!
Format danych
Bardzo ważną kwestią wymagającą omówienia jest format danych, jaki jest przyjazny dla
FormEngine, oraz jaki zarazem jest (wbrew pierwszej reakcji!) przyjazny dla programisty.
Z racji trzymania się drzewiastej hierarchii budowanej tak, jak w przykładach załączonych
powyżej, pola formularza posiadają nazwy ją uwzględniające. Dlatego też po przesłaniu
wypełnionego
formularza
do
serwera,
wartości
pola
firstname
znajdującego
się
w kontenerze personal_data, należy się doszukiwać w miejscu:
$_POST['personal_data']['firstname']
Jeśli zaś kontener personal_data byłby powtarzalny i użytkownik wprowadziłby dwa
zestawy danych osobowych, wówczas imiona kryłyby się pod takimi zmiennymi:
$_POST['personal_data'][0]['firstname']
$_POST['personal_data'][1]['firstname']
Gdyby to pole firstname okazało się polem powtarzalnym lub wielowartościowym,
mielibyśmy z kolei:
$_POST['personal_data']['firstname'][0]
$_POST['personal_data']['firstname'][1]
Dzięki temu uzyskujemy rozróżnienie dwóch powyższych sytuacji – wiemy, który element
jest iterowany. Jest to szczególnie ważne w sytuacji takiej, jak poniżej:
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
$_POST['personal_data'][0]['firstname'][0]
$_POST['personal_data'][0]['firstname'][1]
$_POST['personal_data'][1]['firstname'][0]
Tak, drogi Czytelniku, zgadłeś – chodzi o powtarzalne pole w powtarzalnym kontenerze.
Podczas „wyciągania” danych z formularza można posłużyć się metodą GetValues(), lub jej
aliasem znanym z QuickForm, a więc getSubmitValues() jeśli wcześniej dokonaliśmy
walidacji lub ręcznie załadowaliśmy (Populate()) dane z tablicy $_POST do obiektu
formularza. Dane te są przefiltrowane i mają postać taką, jak opisana powyżej – a więc
hierarchiczną.
Udogodnieniem, choć niezalecanym, jest możliwość przekazania jako parametru metody
GetValues() (lub jej aliasu) w postaci FE_Form::FORMAT_FLAT, co pozwoli nam na
uzyskanie struktury „płaskiej” zwróconych danych, a więc z pominięciem członów
dotyczących kontenerów. Jeśli dane są zwielokrotnione, wówczas przyjmą postać tablicy o
indeksach numerycznych.
Walidacja danych
Aby
ewaluować
reguły
sprawdzania
poprawności
zdefiniowane
podczas
tworzenia
formularza, należy wywołać metodę Validate(), której argumentem może być tablica z
danymi – choćby surowa tablica $_POST.
if ($form->Validate($_POST)) {
// Poprawne dane nadeszły od użytkownika...
}
Metoda ta nie zwróci prawdy, jeśli dane rzeczywiście nie pochodzą z przesłanego
formularza (podczas submitowania jest automatycznie dodawane ukryte pole o tym
świadczące).
Przesłanie formularza do przeglądarki
Ostatnim etapem tworzenia formularza jest jego przesłanie do szablonu. Dokonujemy tego
po prostu tworząc nową zmienną w szablonie, której przypiszemy jako wartość nasz
obiekt-korzeń.
$this->registry->template->assign('form', $form);
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Teraz wystarczy tylko skorzystać z funkcji Smarty, dostarczonej z FormEngine, by nasz
nowoutworzony formularz wypisać.
Przy wywołaniu tej funkcji musimy podać tryb renderowania – albo „JS”, gdy w efekcie
chcemy uzyskać surowy kod JavaScript, gotowy do współpracy z biblioteką JS Gekosale
(domyślne dla Panelu Administracyjnego), lub tryb „Static” (JESZCZE BRAK!) dla
renderowania w postaci znaczników XHTML.
{fe_form form=$form render_mode="JS"}
Należy pamiętać, że nie musimy (nie powinniśmy!) powyższej linijki zawierać wewnątrz
ręcznie utworzonego formularza. Wszelkie niezbędne znaczniki zostaną utworzone
automatycznie.
Alternatywą jest wypisanie wartości zwróconej z metody Render() formularza.
echo $form->Render('JS');
3. Sposób użycia elementów składowych
Rodzaje pól
Poniżej znajduje się lista pól, które można dodawać do formularza. Są one pogrupowane
zależnie od ich charakteru.
Kontenery
FE_Fieldset
Standardowy rodzaj kontenera służący do grupowania pól. Parametry:
•
name – nazwa kontenera. Używana podczas tworzenia nazw pól potomnych.
Powinna być unikalna dla formularza.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
dependencies – tablica predefiniowanych zależności.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
FE_FieldsetRepeatable
Kontener, który zależnie od potrzeb użytkownika może być powtarzany. Parametry:
•
name – nazwa kontenera. Używana podczas tworzenia nazw pól potomnych.
Powinna być unikalna dla formularza.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
dependencies – tablica predefiniowanych zależności.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
Pola
FE_Hidden
Pole ukryte, a więc zwyczajny <input type=”hidden”/>. Służy przekazaniu informacji
pomocniczych. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
dependencies – tablica predefiniowanych zależności.
FE_TextField
Pole tekstowe. Może być powtarzalne. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
•
filters – tablica predefiniowanych filtrów.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
FE_Password
Pole hasła. Zachowuje się tak samo, jak zwykłe pole tekstowe z tą różnicą, że zawartość
nie jest wyświetlana na ekranie. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
filters – tablica predefiniowanych filtrów.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
FE_Textarea
Pole typu textarea. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
•
cols – liczba kolumn.
•
rows – liczba wierszy.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
filters – tablica predefiniowanych filtrów.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
FE_RichTextEditor
Pole wprowadzania tekstu formatowanego, wyposażone w edytor WYSIWYG. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
cols – liczba kolumn.
•
rows – liczba wierszy.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
filters – tablica predefiniowanych filtrów.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
FE_File
Pole służące do wysyłania pliku przez użytkownika. Może być powtarzalne. Oparte jest o
element
flashowy
SWFUpload,
pozwalający
na
asynchroniczne
wysyłanie
plików.
Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
upload_url – URL dokumentu, który zostanie wywołany w celu inicjalizacji
transferu plików.
•
file_types – tablica sugerowanych nazw plików (np. Array('*.png', '*.jpg')).
•
file_types_description – słowne określenie powyższych rodzajów plików.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
FE_Image
Pole służące do wysyłania orbazu przez użytkownika. Może być powtarzalne. Bazuje na
polu typu FE_File, z tym, że wyświetla miniatury przesłanych plików. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
upload_url – URL dokumentu, który zostanie wywołany w celu inicjalizacji
transferu plików.
•
file_types – tablica sugerowanych nazw plików (np. Array('*.png', '*.jpg')).
•
file_types_description – słowne określenie powyższych rodzajów plików.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
FE_Select
Rozwijana lista wyboru. Może być powtarzalna. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
options – tablica opcji, a więc tablica obiektów typu FE_Option. Np.:
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
// ...
'options' => Array(
new FE_Option('pl', 'Polska'),
new FE_Option('uk', 'Wielka Brytania')
)
// ...
Istnieje możliwość stworzenia takiej tablicy na podstawie zwyczajnej tablicy
asocjacyjnej.
// ...
'options' => FE_Option::Make(
Array('pl' => 'Polska', 'uk' => 'Wielka Brytania')
)
// ...
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
•
repeat_min – minimalna liczba powtórzeń (domyślnie 1).
•
repeat_max – maksymalna liczba powtórzeń (domyślnie 1).
FE_MultiSelect
Lista wyboru umożliwiająca wybranie wielu opcji. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
options – tablica opcji, a więc tablica obiektów typu FE_Option.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
FE_RadioGroup
Grupa pól typu radio, posiadających tę samą nazwę i umożliwiająca wybór tylko jednego z
nich. Parametry:
•
name – nazwa pola. Używana podczas tworzenia nazwy pola przy przesyłaniu
danych.
•
label – tytuł kontenera wyświetlany w przeglądarce.
•
help – Treść pomocy dla pola.
•
comment – tekst pomocniczy pojawiający się obok pola (np. „tylko wielkie litery”).
•
options – tablica opcji, a więc tablica obiektów typu FE_Option.
•
dependencies – tablica predefiniowanych zależności.
•
rules – tablica predefiniowanych reguł walidacji.
Elementy specjalne
FE_StaticText
Statyczny, niezmienny blok tekstu, informacji. Jego wyświetlenie może być uzależnione od
warunku. Parametry:
•
text – treść bloku. Dopuszczalny jest kod XHTML.
•
dependencies – tablica predefiniowanych zależności.
Reguły
Reguły są warunkami, pod których kątem jest przeprowadzana walidacja. Mogą być
nadawane konkretnemu polu (jako element tablicy rules podczas inicjalizacji lub
bezpośrednio wywołując metodę AddRule()), lub grupie pól. Przykład:
$email->AddRule(new FE_RuleRequired('Adres e-mail jest wymagany!'));
$email->AddRule(new FE_RuleEmail('Podano błędny adres e-mail!'));
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Dostępne reguły
Poniżej znajduje się lista dostępnych klas, z użyciem których można definiować reguły
walidacji:
•
FE_RuleRequired – pole jest obowiązkowe. Brak określonej wartości skutkuje
komunikatem błędu. Parametry:
◦ komunikat o błędzie
•
FE_RuleFormat – jeśli wartość pola nie odpowiada podanemu jako drugi
argument wyrażeniu regularnemu, następuje błąd walidacji. Parametry:
◦ komunikat o błędzie
◦ wyrażenie regularne
•
FE_RuleEmail – wartość pola musi być poprawnym adresem e-mail. Tak naprawdę
jest to reguła typu FE_RuleFormat z predefiniowanym wyrażeniem regularnym.
Parametry:
◦ komunikat o błędzie
•
FE_RuleUnique – wartość pola musi być unikalna w zadanej kolumnie zadanej
tabeli bazy danych. Parametry:
◦ komunikat o błędzie
◦ nazwa tabeli
◦ nazwa kolumny
◦ [funkcja-lambda przetwarzająca wartość przed porównaniem]
•
FE_RuleCompare – wartość pola musi być identyczna, jak wartość w innym,
zadanym polu. Parametry:
◦ komunikat o błędzie
◦ pole, z wartością którego wartość ma zostać porównana (nie nazwa pola, tylko
obiekt!)
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Zależności
Zależności pozwalają na modyfikację zachowania pól w uzależnieniu od wartości innego
pola.
Pozwalają
np.
na
ukrycie
pola
w
przypadku
wybrania
przez
użytkownika
nieodpowiedniej wartości w innym polu, pokazanie pola, ignorowanie reguł walidacji w
określonym przypadku, lub automatyczne wypełnienie pola wartością zależną od wartości
innego pola.
Składnia zależności:
new FE_Dependency($rodzaj, $pole_zdalne, $warunek);
W powyższym zapisie $rodzaj przyjmuje wartość jednej ze stałych opisanych poniżej,
$pole_zdalne jest polem formularza którego wartość jest badana, a $warunek jest
warunkiem zbudowanym zgodnie z zasadami opisanymi powyżej. W przypadku zależnościsugestii, warunek jest zastępowany callbackiem do funkcji zwracającej sugestię.
Zależność do pola można dodać metodą AddDependency() lub w konstruktorze pola, jako
jeden z elementów tablicy dependencies.
Rodzaje zależności
•
FE_Dependency::HIDE – jeśli warunek jest spełniony, wówczas pole zostaje
ukryte, a reguły walidacji są ignorowane.
•
FE_Dependency::SHOW – pole jest pokazywane tylko gdy warunek jest spełniony
i tylko wtedy obowiązują reguły walidacji.
•
FE_Dependency::IGNORE – pole jest cały czas widoczne, ale w przypadku
spełnienia warunku reguły walidacji są ignorowane.
•
FE_Dependency::SUGGEST
–
zamiast
warunku
podaje
się
callback
do
funkcji/metody (nazwa funkcji lub tablica Array($obiekt, $nazwa_metody)), która
ma zostać użyta do zmiany wartości bieżącego pola (tego, dla którego dodaje się
zależność) w uzależnieniu od wartości pola zdalnego. Funkcja ma przyjmować
parametr będący wartością pola zdalnego, a zwracać ma wartość pola bieżącego.
Działa tylko po stronie przeglądarki, nie jest istotna po przesłaniu formularza do
serwera.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
Warunki
Warunek jest kombinacją obiektów poniższych klas. Służy do reprezentacji zdania
logicznego, którego spełnienie powoduje wykonanie się zależności, do której warunek jest
dopisany.
FE_ConditionEquals – parametrem jest wartość lub tablica wartości. Zwraca
•
prawdę, jeśli zdalne pole ma wartość równą tej przekazanej w parametrze, lub
dowolnej z wartości w przekazanej tablicy.
FE_ConditionGE – zwraca prawdę, jeśli wartość pola zdalnego jest większa lub
•
równa wartości podanej w parametrze.
FE_ConditionLE – zwraca prawdę, jeśli wartość pola zdalnego jest mniejsza lub
•
równa wartości podanej w parametrze.
•
FE_ConditionNot – zaprzeczenie warunku podanego w parametrze.
•
FE_ConditionAnd – konkatenacja dwóch lub więcej warunków, przekazanych w
parametrze jako tablica.
FE_ConditionOr – alternatywa dwóch lub więcej warunków, przekazanych w
•
parametrze jako tablica.
Przykłady zależności i warunków
$post_code->AddDependency(
new FE_Dependency(
FE_Dependency::IGNORE,
$country,
new FE_ConditionNot(new FE_ConditionEquals('pl'))
)
)
Pole z kodem pocztowym nie będzie walidowane, jeśli użytkownik wybrał inny kraj, niż
Polska.
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009
$pack_as_a_gift->AddDependency(
new FE_Dependency(
FE_Dependency::SHOW,
$weight,
new FE_ConditionAnd(Array(
new FE_ConditionGE(100),
new FE_ConditionLE(2000)
))
)
)
Pole „Zapakuj jako prezent” pojawi się tylko wtedy, gdy wybrana waga produktu znajdzie
się w przedziale 100-2000 gramów.
Filtracja
Filtry służą temu, by wstępnie przetworzyć dane, jeszcze przed poddaniem ich walidacji.
Ważną zaletą filtrów jest to, że można je dodawać z użyciem jednej linijki do całego
formularza.
Obecnie dostępne są następujące, standardowe filtry:
•
FE_FilterTrim – z początku i końca wartości usuwane są białe znaki.
•
FE_FilterNoCode – wartości usuwane są fragmenty kodu (strip_tags()).
Przykładowe użycie:
$form->AddFilter(new FE_FilterTrim());
Filtry można również dodawać jako elementy tablicy filters podczas inicjalizacji pola.
4. Kontakt
W razie pytań i wątpliwości, proszę o kontakt. Postaram się pomóc w każdym przypadku.
Bartek Bazyluk – Frontend Developer
[email protected]
Gekosale's FormEngine – Dokumentacja Techniczna – wersja z 15.09.2009