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 dwoma polami do uzupełnienia: nazwa oraz email. Po otrzymaniu tych dwóch danych od użytkownika, wyświetlimy z powrotem 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.

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 Model, podstawową klasę dostarczoną przez Yii, głównie używaną do reprezentowania danych z formularzy.

Informacja: Model jest używane jako rodzic dla klasy modeli NIE powiązanych z tabelą bazy danych. 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. Zawiera 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ę validate(), aby uruchomić procedurę sprawdzania poprawności danych. W przypadku wystąpienia błędów w walidacji, wartość hasErrors zostanie ustawiona na true. Możesz zobaczyć jakie błędy wystąpiły za pomocą metody 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ę post(). Jeśli model został prawidłowo uzupełniony(np. jeśli użytkownik wysłał formularz HTML), akcja wywoła metodę validate(), aby upewnić się, że wprowadzone dane są prawidłowe.

Informacja: 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 jak request, response lub db do wsparcia specyficznej funkcjonalności. W powyższym kodzie użyty jest komponent request 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.

Uwaga: W tym prostym przykładzie po prostu renderujemy stronę z potwierdzeniem prawidłowego przesłania danych. W praktyce powinieneś rozważyć użycie refresh() lub 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 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ę field(). Następnie, po polach do wprowadzania danych, wywoływana jest metoda submitButton() do wygenerowania przycisku "Wyślij", który wysyła formularz.

Próba ¶

Aby zobaczyć jak to działa, użyj przeglądarki i przejdź pod dany adres:

https://hostname/index.php?r=site%2Fentry

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 JavaScriptu, kolejnie dopiero po stronie serwera przez PHP. 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 poprawność danych w każdych okolicznościach.

Ostrzeżenie: Walidacja po stronie klienta jest opcją, która zapewnia wygodniejszą współpracę aplikacji z użytkownikiem. Walidacja po stronie serwera jest zawsze wymagana, niezależnie, czy walidacja po stronie klienta jest włączona, czy też 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') ?>

Informacja: 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.