10 KiB
Praca z formularzami
Ta sekcja opisuje jak utworzyć nową stronę z formularzem pobierającym dane od użytkownika.
Strona będzie wyświetlała formularz z polami dwoma polami do uzupełnienia: nazwa
oraz email
.
Po otrzymaniu tych dwóch danych od użytkownika, wyświetlimy spowrotem wprowadzone wartości w celu ich potwierdzenia.
Aby to osiągnąć, oprócz utworzenia akcji i dwóch widoków, będziesz musiał utworzyć model.
W tym poradniku nauczysz się jak:
- utworzyć model reprezentujący dane wprowadzone przez użytkownika przez formularz,
- zadeklarować zasady do sprawdzenia wprowadzonych danych,
- zbudować formularz HTML w widoku.
- build an HTML form in a view.
Tworzenie modelu
Dane które pobierzemy od użytkownika będą reprezentowane przez klasę modelu EntryForm
, która pokazana jest poniżej. Jest ona zapisana w pliku models/EntryForm.php
.
Po więcej szczegółów odnośnie konwencji nazewnictwa plików zajrzyj do sekcjiautoładowania klas
<?php
namespace app\models;
use Yii;
use yii\base\Model;
class EntryForm extends Model
{
public $name;
public $email;
public function rules()
{
return [
[['name', 'email'], 'required'],
['email', 'email'],
];
}
}
Klasa EntryForm
rozszerza yii\base\Model, podstawową klasę dostarczoną przez Yii, głównie używaną do reprezentowania danych z formularzy.
Info: yii\base\Model jest używane jako rodzic dla klasy modeli NIE powiązanych z tabelą bazy danych. yii\db\ActiveRecord jest rodzicem dla klas modeli powiązanych z tabelami bazy danych.
Klasa EntryForm
zawiera dwa elementy publiczne, name
oraz email
, które są używane do przechowania danych wprowadzonych przez użytkownika.
Zawieta również metodą nazwaną rules()
, która zwraca zestaw zasad do walidacji wprowadzonych danych. Zadeklarowane zasady oznaczają:
- wartości w polach
name
oraz `email są wymagane - wartość pola
email
musi być prawidłowym adresem email
Jeśli posiadasz uzupełniony obiekt EntryForm
danymi wprowadzonymi przez użytkownika, możesz wywołać jego funkcję yii\base\Model::validate(), aby uruchomić procedurę sprawdzania poprawności danych.
W przypadku wystąpienia błędów w walidacji, wartość yii\base\Model::hasErrors zostanie ustawiona na true
. Możesz zobaczyć jakie błędy wystąpiły za pomocą metody yii\base\Model::getErrors.
<?php
$model = new EntryForm();
$model->name = 'Qiang';
$model->email = 'bad';
if ($model->validate()) {
// Dobrze!
} else {
// Źle!
// Use $model->getErrors()
}
Tworzenie akcji
Następnie musisz utworzyć akcję o nazwie entry
w kontrolerze site
, która użyje Twojego nowego modelu. Proces tworzenia i używania akcji był wytłumaczony w sekcji Witaj świecie
<?php
namespace app\controllers;
use Yii;
use yii\web\Controller;
use app\models\EntryForm;
class SiteController extends Controller
{
// ...obecny kod...
public function actionEntry()
{
$model = new EntryForm();
if ($model->load(Yii::$app->request->post()) && $model->validate()) {
// walidacja otrzymanych danych w modelu
// zrób coś sensownego z modelem
return $this->render('entry-confirm', ['model' => $model]);
} else {
// w przypadku błędów walidacji wyświetlana jest strona z błędami
return $this->render('entry', ['model' => $model]);
}
}
}
Akcja tworzy na początku obiekt EntryForm
. Następnie próbuje uzupełnić model danymi ze zmiennej $_POST
, dostarczanymi w Yii przez metodę yii\web\Request::post().
Jeśli model został prawidłowo uzupełniony(np. jeśli użytkownik wysłał formularz HTML), akcja wywoła metodę yii\base\Model::validate() aby upewnić się, że wprowadzone dane są prawidłowe.
Info: Wyrażenie
Yii::$app
reprezentuje instancję aplikacji, która jest globalnie dostępnym singletonem. Jest również lokatorem usług, który dostarcza komponenty takie jakrequest
,response
lubdb
do wsparcia specyficznej funkcjonalności. W powyższym kodzie użyty jest komponentrequest
aby uzyskać dostęp do danych w zmiennej$_POST
.
Jeśli wszystko jest w porządku, akcja wyrenderuje widok o nazwie entry-confirm
w celu potwierdzenia prawidłowego przesłania danych przez użytkownika.
Jeśli nie zostały wysłane żadne dane lub dane zawierają błędy, zostanie wyrenderowany widok entry
, w którym będzie pokazany formularz HTML wraz z wiadomościami błędów walidacji.
Note: W tym prostym przykładzie po prostu renderujemy stronę z potwierdzeniem prawidłowego przesłania danych. W praktyce powinieneś rozważyć użycie yii\web\Controller::refresh() lub yii\web\Controller::redirect() aby uniknąć problemów z ponownym przesłaniem formularza.
Tworzenie widoku
Na koniec, utwórz dwa pliki o nazwach entry-confirm
oraz entry
. Będą one renderowane przez akcję entry
, tak jak to przed chwilą opisaliśmy.
Widok entry-confirm
wyświelta po prostu dane name
oraz email
. Powinien być zapisany w pliku views/site/entry-confirm.php
.
<?php
use yii\helpers\Html;
?>
<p>Wpisałeś następujące informacje:</p>
<ul>
<li><label>Nazwa</label>: <?= Html::encode($model->name) ?></li>
<li><label>Email</label>: <?= Html::encode($model->email) ?></li>
</ul>
Widok entry
wyświetla formularz HTML. Powinien być zapisany w pliku views/site/entry.php
.
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;
?>
<?php $form = ActiveForm::begin(); ?>
<?= $form->field($model, 'name') ?>
<?= $form->field($model, 'email') ?>
<div class="form-group">
<?= Html::submitButton('Wyślij', ['class' => 'btn btn-primary']) ?>
</div>
<?php ActiveForm::end(); ?>
Widok używa potężnego widżetu nazwanego yii\widgets\ActiveForm do budowania formularza HTML.
Metody begin()
oraz end()
renderują odpowiednio otwierające i zamykające tagi formularza. Pomiędzy wywołaniami tych dwóch metod, pola do wprowadzania są tworzone przez metodę yii\widgets\ActiveForm::field().
Następnie, po polach do wprowadzania danych, wywoływana jest metoda yii\helpers\Html::submitButton() do wygenerowania przycisku "Wyślij", który wysyła formularz.
Próba
Aby zobaczyć jak to działa, użyj przeglądarki aby przejść pod dany adres:
http://hostname/index.php?r=site/entry
Zobaczysz stronę wyświetlającą formularz z dwoma polami. Przed każdym polem znajduje się etykieta opisująca to pole. Jeśli klikniesz przycisk "Wyślij" nie wpisując żadnych danych, lub jeśli nie wprowadzisz prawidłowego adresu email, zobaczysz wiadomość błędu wyświeloną pod polem którego ona dotyczy.
Po wpisaniu prawidłowej nazwy, adresu email oraz kliknięciu przycisku "Wyślij", zobaczysz nową stronę wyświetlającą dane, które właśnie wprowadziłes.
"Wyjaśnienie magii"
Możesz się zastanawiać, jak działa ten formularz HTML, ponieważ wydaje się prawie magicznym to, że wyświetla etykietę do każdego pola oraz wyświetla komunikat błędu, jeśli wprowadzisz błędne dane, bez przeładowania strony.
Wstępna walidacja jest wykonywana po stronie klienta używając JavaScript'u, kolejnie dopiero po stronie serwera przez PHP.
yii\widgets\ActiveForm potrafi wyodrębnić zasady walidacji, które zadeklarowałeś w EntryForm
, przekształcić je w wykonywalny kod JavaScript oraz użyć go do walidacji danych.
Jeśli zablokowałeś JavaScript w swojej przeglądarce, walidacja wciąż będzie wykonywana po stronie serwera, jak pokazano w metodzie actionEntry()
.
Gwarantuje to prawidłowość danych w każdych okolicznościach.
Warning: Walidacja po stronie klienta jest opcją, która zapewnia lepsze doświadczenia dla użytkownika. Walidacja po stronie serwera jest zawsze wymagana, niezależnie czy walidacja po stronie klienta jest włączona, czy nie.
Etykiety dla pól w formularzu generowane są przy pomocy metody field()
, używającej nazw właściwości z modelu.
Dla przykładu, etykieta Name
zostanie wygenerowana dla właściwości name
.
Możesz dostosowywać etykiety w widoku, używając poniższego kodu:
<?= $form->field($model, 'name')->label('Your Name') ?>
<?= $form->field($model, 'email')->label('Your Email') ?>
Info: Yii dostarcza wiele podobnych widżetów, które pomogą Ci szybko tworzyć złożone i dynamiczne widoki. Tak jak nauczysz się później, pisanie nowego widżetu jest ekstremalnie łatwe. Będziesz mógł przekształcić Twój kod widoku na widżet do wielokrotnego użytku, aby uprościć rozwój swoich widoków w przyszłości.
Podsumowanie
W tej sekcji poradnika dotknęliśmy każdej części struktury MVC. Nauczyłeś się jak utworzyć klasę modelu, aby reprezentowała dane użytkownika oraz je walidowała.
Nauczyłeś się także, jak pobierać dane od użytkowników oraz jak wyświetlać pobrane dane w przeglądarce. To zadanie mogłoby zabrać Ci wiele czasu podczas pisania aplikacji, jednak Yii dostarcza wiele widżetów, które bardzo je ułatwiają.
W następnej sekcji nauczysz się pracy z bazą danych, która jest wymagana w niemalże każdej aplikacji.