מדריך Yii – עבודה עם טפסים

אחרי המדריך הקודם, בו תיארנו את ה-Actions וה-Views , המדריך  זה מתאר איך ליצור דף חדש באתר,  עם טופס לקבלת נתונים ממשתמשים. בדף שניצור יהיה טופס עם 2 שדות : שם + אימייל. ואחרי שנקבל את הפרטים האלו מהגולש, נבדוק אותם, ונציג אותם חזרה למשתמש.

כדי לבצע את המשימה הזו – יצירת דף עם טופס, צריך ללמוד גם ליצור model (אחרי שלמדנו כבר על view, action ).

במדריך הזה נלמד :

  • ליצור model
  • איך רושמים כללים לאימות/validation של הנתונים במודל
  • לבנות טופס Html באמצעות Yii

יצירת מודל ב- Yii

הגולש יכניס נתונים לתוך טופס, את הנתונים, אנחנו נשמור בתוך מחלקה מסוג model  בקובץ  models/EntryForm.php. (אם אתה עדין לא מכיר את הכללים ליצירת שמות קבצים ומחלקות, עיין בסעיף AutoLoading).

<?php

namespace appmodels;

use yiibaseModel;

class EntryForm extends Model
{
    public $name;
    public $email;

    public function rules()
    {
        return [
            [['name', 'email'], 'required'],
            ['email', 'email'],
        ];
    }
}

 

המחלקה שיצרנו מרחיבה (extends) את המחלקה yiibaseModel , שהיא מחלקה בסיסית ש-Yii מספקת לנו, עבור מודלים.

הערה : המחלקה yiibaseModel משמשת ליצירת מודלים שלא מבוססים על DB, עבור מודלים שמבוססים על DB יש מחלקה אחרת שנקראת yiidbActiveRecord.

המחלקה EntryForm מכילה 2 משתנים ציבוריים : name,email. המשתנים האלו ישמשו לאחסון המידע שהגולש יקליד בטופס.

בנוסף, המודל מכיל גם מערך של כללים , המשמשים לבדיקת הנתונים (validition), יש שם 2 כללים :

  • 2 השדות הם חובה
  • האימייל חייב להיות אימייל תקין

נניח ויש לך אוביקט של EntryForm שמכיל כבר את הנתונים מהגולש, ואתה מעוניין רק לבדוק אותו , לעשות לו וואלידציה, אז הקוד יראה  כך  (אם הוואלידציה לא מצליחה, תקבל hasErrors  = false והשגיאות יופיעו באוביקט errors ) :

<?php
$model = new EntryForm();
$model->name = 'Qiang';
$model->email = 'bad';
if ($model->validate()) {
    // Good!
} else {
    // Failure!
    // Use $model->getErrors()
}

יצירת Action

כעת, צריך ליצור Action שיקרא Entry בתוך ה-Controller , כאשר ה-Action , יעשה שימוש במודל החדש שיצרנו.

<?php

namespace appcontrollers;

use Yii;
use yiiwebController;
use appmodelsEntryForm;

class SiteController extends Controller
{
    // ...existing code...

    public function actionEntry()
    {
        $model = new EntryForm;

        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
            // valid data received in $model

            // do something meaningful here about $model ...

            return $this->render('entry-confirm', ['model' => $model]);
        } else {
            // either the page is initially displayed or there is some validation error
            return $this->render('entry', ['model' => $model]);
        }
    }
}

המתודה actionEntry , מתחילה בכך שהיא  יוצרת אובייקט EntryForm.
לאחר מכן, המתודה מנסה להכניס את הנתונים שהגיעו ב-Post אל תוכל המודל, ולשם כך המתודה נעזרת ב yiiwebRequest::post() שמסופק על yii.  אם המתודה מצליחה להכניס את הנתונים למודל היא קוראת לפונקציה validate() כדי לוודא שהנתונים שהוקלדו נכונים.

מידע: הביטוי  Yii::$app הוא מופע (instance) של אוביקט  application  (אוביקט עם מופע יחיד – סינגלטון).  הוא מאפשר לנו לגשת לאוביקטים חשובים, כמו כמו request, response, db. בדוגמא הספציפית שלנו, הוא איפשר לנו לגשת לאוביקט request ולמשוך מתוכו את הנתונים שהגיעו ב-Post.

אם הכל תקין בטופס, אז ה-Action תקרא לפונקציה render() כדי ליצור view בשם entry-confirm .

אם אין נתונים, או שהגולש הקליד נתונים שלא עומדים בכללי הוואלידציה, אז הפונקציה render() תייצר view אחר, שנקרא entry – שזהו בעצם הטופס עצמו, כלומר המשתמש מוחזר לטופס עם ציון השגיאות שעליו לתקן.

הערה: זוהי דוגמא ממש פשוטה, ולכן רק יצרנו "דף אישור" אחרי שהטופס עובר בהצלחה, אבל ברור שבמקרים אמיתיים, צריך להשתמש בפעולות אחרות, כמו למשל refresh() או redirect() , כדי להימנע מבעיות של שליחה-מחדש של טפסים.

יצירת Views

השלב האחרון במדריך הוא ליצור 2 קבצי view, אחד יקרא בשם entry-confirm  והשני יקרא פשוט entry. ה-view שיקרא entry-confirm פשוט מציג את הנתונים שהוקלדו בטופס.

צור קובץ במיקום views/site/entry-confirm.php :

<?php
use yiihelpersHtml;
?>
<p>You have entered the following information:</p>

<ul>
    <li><label>Name</label>: <?= Html::encode($model->name) ?></li>
    <li><label>Email</label>: <?= Html::encode($model->email) ?></li>
</ul>

הקובץ השני הוא views/site/entry.php והוא יכיל את טופס ה-html עצמו :

<?php
use yiihelpersHtml;
use yiiwidgetsActiveForm;
?>
<?php $form = ActiveForm::begin(); ?>

    <?= $form->field($model, 'name') ?>

    <?= $form->field($model, 'email') ?>

    <div class="form-group">
        <?= Html::submitButton('Submit', ['class' => 'btn btn-primary']) ?>
    </div>

<?php ActiveForm::end(); ?>

בקוד של ה-view הזה בטח הבחנת שאנו משתמשים ב-widget עוצמתי של Yii שנקרא ActiveForm כדי לבנות את טופס ה-Html. המתודות begin() ו- end() יוצרות את תגי הפתיחה והסיום של הטופס, והמתודה field() מציגה שדה בודד.

לסיום המתודה yiihelpersHtml::submitButton()  מייצרת כפתור Submit לשליחת הנתונים.

נסה את זה בעצמך

כדי לנסות את הטופס החדש באפליקציה גלוש אל

http://hostname/index.php?r=site/entry

אם תשחק עם הטופס ותנסה להקליד נתונים שגויים וללחוץ submit תראה שתקבל הודעות שגיאה, כמו בתמונה הבאה :

אך לעומת זאת אם תקליד נתונים שעומדים בכלל הוואלידציה תקבל את ה-view שיצרת שנקרא entry-confirm שנראה כך :

 איך הוודליאציה עובדת בלי רענון של הדף (מה הטריק ? )

הרכיב שנקרא yiiwidgetsActiveForm הוא רכיב חכם שמייצר בעצם 2 נדבכים של וואלידציה, הראשון הוא JavaScript , ורק במידה ואצל הגולש – ה-JS לא מופעל בדפדפן, אזי בכל מקרה, תהיה גם וואלידציה בצד השרת (php כמובן).

ותגיות ה-label מיוצרות אוטומטית באמצעות הפונקציה field().

אם אתה מעוניין לשנות את ה-labels, אפשר לשנות אותם בצורה הבאה:

<?= $form->field($model, 'name')->label('Your Name') ?>
<?= $form->field($model, 'email')->label('Your Email') ?>

הערה : Yii מספק הרבה widgets  כאלו שיעזרו לך לבנות במהירות אפליקציות ואתרים  מורכבים.גם לבנות בעצמך widgets זה קל מאוד.

 סיכום – טפסים ב-Yii

במדקיך הזה נגענו בכל החלקים של שיטת MVC. יצרנו מחלקה עבור model, שייצג את הנתונים שקיבלנו מהמשתמש. וראינו איך ליצור וואלידציה במודל.

בנוסף, ראינו איך ליצור טפסי Html ואיך להשתמש ב-widgets של Yii.
במדריך הבא, נראה איך לעבוד עם DBs .

המדריך מפורסם לפי התנאים של Yii , והמקור נמצא כאן .