רכיב

האפליקציות ב Yii נבנות תחת רכיבים שהינם אובייקטים אשר נכתבים על פי מפרט מסויים. רכיב הינו אובייקט של CComponent או מחלקות אשר נמצאות תחתיו. שימוש ברכיב בדרך כלל משמש כדי לגשת למאפיינים של אותו רכיב והעלאה וניהול של אירועים המוגדרים בו. המחלקה הבסיסית (הראשית) CComponent מציינת כיצד להגדיר את המאפיינים והאירועים.

1. מאפייני רכיב ¶

מאפיין רכיב הוא כמו משתנה במחלקה. ניתן לקרוא את הערך שבו או להגדיר לו ערך חדש. לדוגמא,

$width=$component-»textWidth;     // get the textWidth property
$component-»enableCaching=true;   // set the enableCaching property

כדי להגדיר מאפיין רכיב, כל מה שצריך לעשות זה פשוט להגדיר משתנה במחלקה של אותו רכיב. למרות זאת, אפשרות יותר גמישה תיהיה על ידי הגדרת פונקציות קריאה ו כתיבה בצורה הבאה:

public function getTextWidth()
{
    return $this-»_textWidth;
}
 
public function setTextWidth($value)
{
    $this-»_textWidth=$value;
}

הקוד המוצג למעלה מגדיר מאפיין הניתן לכתיבה בשם textWidth (השם אינו רגיש לאותיות גדולות-קטנות). בעת קריאה של מאפיין זה הפונקציה getTextWidth נכנסת לפעולה והערך שמוחזר ממנה הוא הערך של המשתנה במחלקה; באותו אופן, בעת שמירת ערך למאפיין זה הפונקציה setTextWidth נכנסת לפעולה. אם לא הוגדרה פונקציה לכתיבה של אותו מאפיין, המאפיין יהיה ניתן לקריאה-בלבד ובעת ניסיון לשנות את הערך שלו תזרק שגיאה. שימוש בפונקציות קריאה וכתיבה של משתנים/מאפיינים כדי לקרוא אותם ולהגדירם מאפשרת הרצת בדיקות ולוגיקות נוספות (לדוגמא ביצוע אימות נתונים, העלאת אירועים).

»Note|הערה: ישנו הבדל קטן בין מאפיין אשר מוגדר בעזרת פונקציות קריאה/כתיבה ומאפיין אשר מוגדר בעזרת משתנה במחלקה. מאפיין המוגדר בעזרת פונקציות שמו לא רגיש לאותיות גדולות-קטנות, לעומת משתנה במחלקה שהינו רגיש לאותיות גדולות-קטנות.

2. אירועים ברכיב ¶

אירועי רכיב הם תכונות מיוחדות הלוקחות פונקציות (הנקראות event handlers) בתור הערכים שלהם. צירוף (הקצאת) פונקציה לאירוע מסויים יגרום לפונקציה לרוץ אוטומטית במקומות בהם האירוע מתרחש. לכן, ההתנהלות של הרכיב יכולה להשתנות בצורה כזאת שלא ניתן לצפות בה מראש במהלך פיתוח הרכיב.

אירוע ברכיב מוגדר על ידי הגדרת פונקציה ששמה מתחיל ב 'on'. כמו שמות מאפיינים המוגדרים בעזרת פונקציות קריאה/כתיבה, שמות האירועים אינם רגישים לאותיות גדולות-קטנות. הקוד הבא מגדיר אירוע onClicked:

public function onClicked($event)
{
    $this-»raiseEvent('onClicked', $event);
}

איפה ש event$ הוא אובייקט של CEvent או מחלקות אשר נמצאות תחתיו המייצג את פרמטר האירוע.

ניתן לצרף פונקציה לאירוע זה בצורה הבאה:

$component-»onClicked=$callback;

כש callback$ מכוון לפונקצית PHP תקינה. פונקציה זו יכולה להיות פונקציה גלובלית או מתודה במחלקה. אם הוגדר שהיא הינה מתודה במחלקה, יש להגדיר את הערך כמערך כשהאלמנט הראשון הוא האובייקט של אותה מחלקה והשני הוא שם המתודה:

array($object,'methodName')

פונקציה המטפלת באירוע כלשהו צריכה להראות בדומה לקוד הבא:

function methodName($event)
{
    ......
}

כש event$ הוא משתנה המכיל מידע אודות האירוע שהועלה (הוא נוצר מהקריאה של raiseEvent). המשתנה event$ הוא אובייקט של CEvent או מחלקות הנמצאות תחתיו. המינימום הוא שיכיל מידע של מי העלאה את האירוע.

החל מגרסא 1.0.10, ניתן לנהל אירוע על ידי פונקציה אנונימית אשר נתמכת בגרסאת PHP 5.3 ומעלה, לדוגמא,

$component-»onClicked=function($event) {
    ......
}

אם נקרא ל onClicked עכשיו, האירוע onClicked יבוצע (בתוך הפונקציה onClicked), והפונקציה אשר מטפלת באירוע זה תקרא אוטומטית.

ניתן לצרף כמה פונקציות לטיפול באותו אירוע. כשהאירוע יבוצע והפונקציות יקראו, הם יבוצעו בסדר שהם צורפו לאותו אירוע. אם אחד מהפונקציות המטפלות באירוע רוצה למנוע קריאה לשאר הפונקציות המטפלות באותו האירוע, ניתן להגדיר $event-»handled לערך השווה ל true ולא יקראו פונקציות נוספות לטיפול באירוע זה.

3. ניהול הרכיב ¶

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

מחלקות ניהוליות חייבות ליישם את הממשק IBehavior. רוב המחלקות הניהוליות מרחיבות תחת המחלקה הבסיסית CBehavior. אם מחלקה ניהולית צריכה להיות מצורפת למודל, ניתן להרחיב אותה גם מ CModelBehavior או CActiveRecordBehavior אשר מיישמות אפשרויות נוספות ספציפיות למודלים.

בכדי להשתמש במחלקה ניהולית, חובה לצרף אותה לרכיב קודם על ידי קריאה למתודה בשם attach. לאחר מכן אנו קוראים למתודה של מחלקה ניהולית דרך הרכיב:

// $name uniquely identifies the behavior in the component
$component-»attachBehavior($name,$behavior);
// test() is a method of $behavior
$component-»test();

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

$behavior=$component-»tree;
// equivalent to the following:
// $behavior=$component-»asa('tree');

ניתן לכבות זמנית מחלקה מצורפת כדי שלא יהיה ניתן לגשת למתודות שלה דרך הרכיב. לדוגמא:

$component-»disableBehavior($name);
// the following statement will throw an exception
$component-»test();
$component-»enableBehavior($name);
// it works now
$component-»test();

ישנה אפשרות ששני מחלקות ניהוליות אשר מצורפות לאותו רכיב יכילו מתודות זהות בשמם. במקרה הזה, המתודה של המחלקה שצורפה קודם לכן תקבל זכות על פני השנייה.

כשמשתמשים ביחד עם אירועים, מחלקות ניהוליות הרבה יותר שימושיות. מחלקה ניהולית, בעת צירופה לרכיב, יכולה לצרף כמה מתודות שלה לכמה אירועים ברכיב. על ידי ביצוע פעולה זו, המחלקה הניהולית מקבלת הזדמנות להתבונן או לשנות את רצף הביצועים הרציפים של הרכיב.

החל מגרסא 1.1.0, ניתן לקרוא למאפיינים של מחלקה ניהולית דרך הרכיב אליו הם מצורפים. המאפיינים מכילים גם את המשתנים של המחלקה והמאפיינים אשר מוגדרים באמצעות פונקציות קריאה/כתיבה במחלקה הניהולית. לדוגמא, אם מחלקה ניהולית מכילה מאפיין בשם xyz והיא מצורפת לרכיב a$, אז נוכל להשתמש בביטוי a-»xyz$ כדי לגשת למאפיין של המחלקה הניהולית המצורפת לרכיב.