Customizing Post Model
======================

The `Post` model class generated by the `Gii` tool mainly needs to be modified in two places:

 - the `rules()` method: specifies the validation rules for the model attributes;
 - the `relations()` method: specifies the related objects;

> Info: A [model](http://www.yiiframework.com/doc/guide/basics.model) consists of a list of attributes, each associated with a column in the corresponding database table. Attributes can be declared explicitly as class member variables or implicitly without any declaration.


Customizing `rules()` Method
----------------------------

We first specify the validation rules which ensure the attribute values entered by users are correct before they are saved to the database. For example, the `status` attribute of `Post` should be an integer 1, 2 or 3. The `Gii` tool also generates validation rules for each model. However, these rules are based on the table column information and may not be appropriate.

Based on the requirement analysis, we modify the `rules()` method as follows:

~~~
[php]
public function rules()
{
	return array(
		array('title, content, status', 'required'),
		array('title', 'length', 'max'=>128),
		array('status', 'in', 'range'=>array(1,2,3)),
		array('tags', 'match', 'pattern'=>'/^[\w\s,]+$/',
			'message'=>'Tags can only contain word characters.'),
		array('tags', 'normalizeTags'),

		array('title, status', 'safe', 'on'=>'search'),
	);
}
~~~

In the above, we specify that the `title`, `content` and `status` attributes are required; the length of `title` should not exceed 128; the `status` attribute value should be 1 (draft), 2 (published) or 3 (archived); and the `tags` attribute should only contain word characters and commas. In addition, we use `normalizeTags` to normalize the user-entered tags so that the tags are unique and properly separated with commas. The last rule is used by the search feature, which we will describe later.

The validators such as `required`, `length`, `in` and `match` are all built-in validators provided by Yii. The `normalizeTags` validator is a method-based validator that we need to define in the `Post` class. For more information about how to specify validation rules, please refer to [the Guide](http://www.yiiframework.com/doc/guide/form.model#declaring-validation-rules).

~~~
[php]
public function normalizeTags($attribute,$params)
{
	$this->tags=Tag::array2string(array_unique(Tag::string2array($this->tags)));
}
~~~

where `array2string` and `string2array` are new methods we need to define in the `Tag` model class:

~~~
[php]
public static function string2array($tags)
{
	return preg_split('/\s*,\s*/',trim($tags),-1,PREG_SPLIT_NO_EMPTY);
}

public static function array2string($tags)
{
	return implode(', ',$tags);
}
~~~

The rules declared in the `rules()` method are executed one by one when we call the [validate()|CModel::validate] or [save()|CActiveRecord::save] method of the model instance.

> Note: It is very important to remember that attributes appearing in `rules()` must be those to be entered by end users. Other attributes, such as `id` and `create_time` in the `Post` model, which are set by our code or database, should not be in `rules()`. For more details, please refer to [Securing Attribute Assignments](http://www.yiiframework.com/doc/guide/form.model#securing-attribute-assignments).

After making these changes, we can visit the post creation page again to verify that the new validation rules are taking effect.


Customizing `relations()` Method
--------------------------------

Lastly we customize the `relations()` method to specify the related objects of a post. By declaring these related objects in `relations()`, we can exploit the powerful [Relational ActiveRecord (RAR)](http://www.yiiframework.com/doc/guide/database.arr) feature to access the related object information of a post, such as its author and comments, without the need to write complex SQL JOIN statements.

We customize the `relations()` method as follows:

~~~
[php]
public function relations()
{
	return array(
		'author' => array(self::BELONGS_TO, 'User', 'author_id'),
		'comments' => array(self::HAS_MANY, 'Comment', 'post_id',
			'condition'=>'comments.status='.Comment::STATUS_APPROVED,
			'order'=>'comments.create_time DESC'),
		'commentCount' => array(self::STAT, 'Comment', 'post_id',
			'condition'=>'status='.Comment::STATUS_APPROVED),
	);
}
~~~

We also introduce in the `Comment` model class two constants that are used in the above method:

~~~
[php]
class Comment extends CActiveRecord
{
	const STATUS_PENDING=1;
	const STATUS_APPROVED=2;
	......
}
~~~

The relations declared in `relations()` state that

 * A post belongs to an author whose class is `User` and the relationship is established based on the `author_id` attribute value of the post;
 * A post has many comments whose class is `Comment` and the relationship is established based on the `post_id` attribute value of the comments. These comments should be sorted according to their creation time and the comments must be approved.
 * The `commentCount` relation is a bit special as it returns back an aggregation result which is about how many comments the post has.


With the above relation declaration, we can easily access the author and comments of a post like the following:

~~~
[php]
$author=$post->author;
echo $author->username;

$comments=$post->comments;
foreach($comments as $comment)
	echo $comment->content;
~~~

For more details about how to declare and use relations, please refer to [the Guide](http://www.yiiframework.com/doc/guide/database.arr).


Adding `url` Property
---------------------

A post is a content that is associated with a unique URL for viewing it. Instead of calling [CWebApplication::createUrl] everywhere in our code to get this URL, we may add a `url` property in the `Post` model so that the same piece of URL creation code can be reused. Later when we describe how beautify URLs, we will see adding this property will bring us great convenience.

To add the `url` property, we modify the `Post` class by adding a getter method like the following:

~~~
[php]
class Post extends CActiveRecord
{
	public function getUrl()
	{
		return Yii::app()->createUrl('post/view', array(
			'id'=>$this->id,
			'title'=>$this->title,
		));
	}
}
~~~

Note that in addition to the post ID, we also add the post title as a GET parameter in the URL. This is mainly for search engine optimization (SEO) purpose, as we will describe in [Beautifying URLs](/doc/blog/final.url).

Because [CComponent] is the ultimate ancestor class of `Post`, adding the getter method `getUrl()` enables us to use the expression like `$post->url`. When we access `$post->url`, the getter method will be executed and its result is returned as the expression value. For more details about such component features, please refer to [the guide](/doc/guide/basics.component).


Representing Status in Text
---------------------------

Because the status of a post is stored as an integer in the database, we need to provide a textual representation so that it is more intuitive when being displayed to end users. In a large system, the similar requirement is very common.

As a generic solution, we use the `tbl_lookup` table to store the mapping between integer values and textual representations that are needed by other data objects. We modify the `Lookup` model class as follows to more easily access the textual data in the table,

~~~
[php]
class Lookup extends CActiveRecord
{
......

	private static $_items=array();

	public static function items($type)
	{
		if(!isset(self::$_items[$type]))
			self::loadItems($type);
		return self::$_items[$type];
	}

	public static function item($type,$code)
	{
		if(!isset(self::$_items[$type]))
			self::loadItems($type);
		return isset(self::$_items[$type][$code]) ? self::$_items[$type][$code] : false;
	}

	private static function loadItems($type)
	{
		self::$_items[$type]=array();
		$models=self::model()->findAll(array(
			'condition'=>'type=:type',
			'params'=>array(':type'=>$type),
			'order'=>'position',
		));
		foreach($models as $model)
			self::$_items[$type][$model->code]=$model->name;
	}
}
~~~

Our new code mainly provides two static methods: `Lookup::items()` and `Lookup::item()`. The former returns a list of strings belonging to the specified data type, while the latter returns a particular string for the given data type and data value.

Our blog database is pre-populated with two lookup types: `PostStatus` and `CommentStatus`. The former refers to the possible post statuses, while the latter the comment statuses.

In order to make our code easier to read, we also declare a set of constants to represent the status integer values. We should use these constants through our code when referring to the corresponding status values.

~~~
[php]
class Post extends CActiveRecord
{
	const STATUS_DRAFT=1;
	const STATUS_PUBLISHED=2;
	const STATUS_ARCHIVED=3;
	......
}
~~~

Therefore, we can call `Lookup::items('PostStatus')` to get the list of possible post statuses (text strings indexed by the corresponding integer values), and call `Lookup::item('PostStatus', Post::STATUS_PUBLISHED)` to get the string representation of the published status.


<div class="revision">$Id$</div>