8.9 KiB
Tworzenie formularzy
Podstawowym sposobem korzystania z formularzy w Yii jest użycie yii\widgets\ActiveForm. Ten sposób powinien być używany, jeśli formularz jest bazowany na modelu. Dodatkowo, klasa yii\helpers\Html zawiera sporo użytecznych metod, które zazwyczaj używane są do dodawania przycisków i tekstów pomocniczych do każdego formularza.
Formularz, który jest wyświetlany po stronie klienta, w większości przypadków, posiada odpowiedni model, który jest używany do walidacji danych wejściowych po
stronie serwera (sprawdź sekcję Walidacja danych wejściowych aby uzyskać więcej szczegółów).
Podczas tworzenia formularza na podstawie modelu, pierwszym krokiem jest zdefiniowanie samego modelu.
Model może być bazowany na klasie Active Record, reprezentując dane z bazy danych, lub może być też bazowany na klasie generycznej yii\base\Model,
aby przechwytywać dowolne dane wejściowe, np. formularz logowania.
W poniższym przykładzie pokażemy, jak model generyczny może być użyty do formularza logowania:
<?php
class LoginForm extends \yii\base\Model
{
public $username;
public $password;
public function rules()
{
return [
// zasady walidacji
];
}
}
W kontrolerze przekażemy instancję tego modelu do widoku, gdzie widżet yii\widgets\ActiveForm zostanie użyty do wyświetlenia formularza:
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
$form = ActiveForm::begin([
'id' => 'login-form',
'options' => ['class' => 'form-horizontal'],
]) ?>
<?= $form->field($model, 'username') ?>
<?= $form->field($model, 'password')->passwordInput() ?>
<div class="form-group">
<div class="col-lg-offset-1 col-lg-11">
<?= Html::submitButton('Login', ['class' => 'btn btn-primary']) ?>
</div>
</div>
<?php ActiveForm::end() ?>
W powyższym kodzie, yii\widgets\ActiveForm::begin() nie tylko tworzy instancję formularza, ale zaznacza też jego początek.
Cała zawartość położona pomiędzy yii\widgets\ActiveForm::begin() i yii\widgets\ActiveForm::end() zostanie otoczona tagiem HTML'owym <form>
.
Jak w przypadku każdego widżetu, możesz określić kilka opcji z jakimi widżet powinien być skonfigurowany przez przekazanie tablicy do metody begin
.
W tym przypadku dodatkowa klasa CSS i identyfikator ID zostały przekazane do otwierającego tagu <form>
.
Aby zobaczyć wszystkie dostępne opcje, zajrzyj do dokumentacji API yii\widgets\ActiveForm.
Do utworzenia formularza, wraz z elementami etykiet oraz wszelkimi walidacjami JavaScript, wywoływana jest metoda yii\widgets\ActiveForm::field(), która zwraca instancję obiektu yii\widgets\ActiveField. Kiedy rezultat tej metody jest bezpośrednio wyświetlany, tworzone jest regularne pole tekstowe. Aby dostosować pola, możesz używać dodatkowych metod łączonych yii\widgets\ActiveField:
// pole hasła
<?= $form->field($model, 'password')->passwordInput() ?>
// dodanie podpowiedzi oraz zmiana etykiety
<?= $form->field($model, 'username')->textInput()->hint('Please enter your name')->label('Name') ?>
// utworzenie pola email w formacie HTML5
<?= $form->field($model, 'email')->input('email') ?>
Powyższy kod utworzy tagi <label>
, <input>
oraz wszystkie inne, według pól formularza zdefiniowanych w yii\widgets\ActiveField::$template.
Nazwa pola określana jest automatycznie z modelu yii\base\Model::formName() i nazwy atrybutu.
Dla przykładu, nazwą pola dla atrybutu username
w powyższym przykładzie będzie LoginForm[username]
.
Ta zasada nazewnictwa spowoduje, że tablica wszystkich atrybutów z formularza logowania będzie dostępna w zmiennej $_POST['LoginForm']
po stronie serwera.
Określanie atrybutów modelu może być wykonane w bardziej wyrafinowany sposób.
Dla przykładu, kiedy atrybut będzie potrzebował pobierać tablicę wartości, podczas przesyłania wielu plików lub wybrania wielu pozycji, możesz określić go jako tablicę dodając []
do
nazwy atrybutu:
// pozwól na przesłanie wielu plików
echo $form->field($model, 'uploadFile[]')->fileInput(['multiple'=>'multiple']);
// pozwól na zaznaczenie wielu pozycji
echo $form->field($model, 'items[]')->checkboxList(['a' => 'Item A', 'b' => 'Item B', 'c' => 'Item C']);
Bądź ostrożny podczas nazywania elementów formularza takich jak przyciski wysyłania. Odnosząc się do dokumentacji jQuery, istnieje kilka zarezerwowanych nazw, które mogą powodować konflikty.
Formularz i jego elementy podrzędne powinny nie używać nazw pól lub nazw identyfikatorów które tworzą konflikt z właściwościami formularza, takich jak
submit
,length
lubmethod
. Konflikty nazw mogą powodować mylące błędy. Kompletna lista zasad oraz walidator znaczników dla tych problemów znajduje się na stronie DOMLint.
Dodatkowe tagi HTML mogą zostać dodane do formularza używając czystego HTML'a lub używając metody z klasy pomocniczej - yii\helpers\Html, tak jak było to zrobione w przykładzie wyżej z yii\helpers\Html::submitButton().
Tip: Jeśli używasz Twitter Bootstrap CSS w Twojej aplikacji, możesz użyć yii\bootstrap\ActiveForm zamiast yii\widgets\ActiveForm. Rozszerza on yii\widgets\ActiveForm i podczas generowania pól formularza używa stylu specyficznego dla Bootstrap.
Tip: Jeśli chcesz oznaczyć wymagane pola gwiazdką, możesz uzyć poniższego kodu CSS:
div.required label:after { content: " *"; color: red; }
Tworzenie listy rozwijanej
Możemy użyć metody klasy ActiveForm yii\widgets\ActiveForm::dropDownList() do utworzenia rozwijanej listy:
use app\models\ProductCategory;
/* @var $this yii\web\View */
/* @var $form yii\widgets\ActiveForm */
/* @var $model app\models\Product */
echo $form->field($model, 'product_category')->dropdownList(
ProductCategory::find()->select(['category_name', 'id'])->indexBy('id')->column(),
['prompt'=>'Select Category']
);
Wartość z Twojego modelu będzie automatycznie wybrana po wyświetleniu formularza.
Praca z Pjaxem
Widżet yii\widgets\Pjax pozwala na aktualizację określonej sekcji strony, zamiast przeładowywania jej całkowicie. Możesz użyć go do odświeżenia formularza i podmienić jego zawartość po wysłaniu danych.
Możesz skonfigurować yii\widgets\Pjax::$formSelector, aby wskazać,
które formularze powinny wyzwalać użycie pjaxa. Jeśli nie zostanie to ustawione inaczej,
wszystkie formularze z atrybutem data-pjax
objęte widżetem Pjax będą wyzwalały jego użycie.
use yii\widgets\Pjax;
use yii\widgets\ActiveForm;
Pjax::begin([
// opcje Pjaxa
]);
$form = ActiveForm::begin([
'options' => ['data' => ['pjax' => true]],
// więcej opcji ActiveForm
]);
// zawartość ActiveForm
ActiveForm::end();
Pjax::end();
Tip: Należy być ostrożnym z użyciem linków wewnątrz widżetu yii\widgets\Pjax, ponieważ ich cel również zostanie wyrenderowany wewnątrz widżetu. Aby temu zapobiec, należy użyć atrybutu HTML
data-pjax="0"
.
Wartości w przyciskach submit i przesyłanie plików
Znane są problemy z użyciem jQuery.serializeArray()
podczas obsługi
plików i
wartości przycisku submit, które nie
będą jednak rozwiązane i zamiast tego zostały porzucone na rzecz klasy FormData
wprowadzonej w HTML5.
Oznacza to, że oficjalne wsparcie dla plików i wartości przycisku submit używanych w połączeniu
z ajaxem lub widżetem yii\widgets\Pjax zależy od
wsparcia przeglądarki
dla klasy FormData
.
Dalsza lektura
Następna sekcja Walidacja danych wejściowych dotyczy walidacji przesłanych przed formularz danych po stronie serwera, przy użyciu ajax oraz walidacji po stronie klienta.
Aby przeczytać o bardziej złożonych użyciach formularzy możesz zajrzeć do poniższych sekcji:
- Odczytywanie tablicowych danych wejściowych - do pobierania danych dla wielu modeli tego samego rodzaju.
- Pobieranie danych dla wielu modeli - do obsługi wielu różnych modeli w tym samym formularzu.
- Wysyłanie plików - jak używać formularzy do przesyłania plików.