Model uses objects to describe each of it’s field. Therefore when you create a model with 10 fields, it would populate at least 12 objects:
Model’s object. One object for each field. DSQL object for a model. Fields object play a very direct role in creating queries for the model such as select, update and insert queries.
Normally you would rely on the standard Model Field class, which is populated when you call addField(), however you should know that it’s possible to extend fields significantly.
One of he significant roles carried out by Model Field is collecting of the information about the field. Information such as caption, type, possible values, associated model is stored in Field’s properties and can be extended to hold even more information such as caption, validation rules etc.
Model will operate with internal DSQL object. It is however responsibility for the field object to populate queries with field information.
You would typically create a new field by calling Model::addField method. This method is a shortcut for add('Field', $name). but should be used for standard field definition. If you are adding non-standard field class (such as Field_File), you can use AbstractObject::add.
Here is how we add few fields to our model:
$this->addField('name'); $this->addField('gender')->enum(array('m','f')); $this->addfield('language')->setValueList($languages);
There are several classes which extend “Field”, such as:
Some of them will automatically be used by the Model when you call a dedicated method (addExpression(), hasOne()), others can me manually added using add() method.
The short_name of the field object corresponds to the field name and will be used for internal referencing as well as in result sets. If you pass second argument to addField(), then you can specify a different actual database field.
$this->addField('name','full_name'); $field = $this->getElement('name');
Anything what was said in the AbstractObject section still applies to the field, for example - you can remove fields from model: $field->destroy();
Since fields are associated with models and models know which table they work with, you can use Fields of Relational Models inside SQL expressions.
$model->dsql() ->set($model->getElement('name'),'John') ->update();
It’s highly advisable that if you use field of a model model->dsql();`
Several methods of the field are acting to describe model type.
You must remember, that properties of a model serve the purpose of configuring Views to comply with your configuration. They will not restrict or validate the actual model. For example - you can still create model entry with a empty mandatory field.
If you wish to validate fields on the model level, you will need to use beforeSave hook, this will have a system-wide access regardless of who is accessing the model. Even if you create a validation like that, you can still use model’s DSQL to manually create a query which would bypass the validation.
Typically there are many more fields in a model than you would need to display on the forms. With actual fields, you can specify which fields you need to display to user and in which order.
While actual fields primarily is a functionality of a respective view (such as defining which columns are visible inside grid), it also has impact on the query. Agile Toolkit models will never use “*” to load model data.
This code will display grid with only two fields in exactly the specified order. Not always you would wan to specify a list of fields. If field list is omitted, then model will attempt to determine which fields to display based on number of flags.
These methods can accept “true”, “false” or “undefined” value.
Some fields contain one value, but the value needs to be displayed differently. For example it’s typical to have ‘m’ for Male and ‘f’ for Female.
There are some properties which are used on a low-level and allows to change the way how field queries are created. Do not call those methods directly unless you know what you are doing:
You may specify additional attributes by calling setterGetter() method:
$model->addField('bio')->setterGetter('hint','Type your bio here');
You would need to extend views to make them capable of interpreting your additional parameters. You can also access properties directly if you prefer it that way.
In several situations, you would want to have your own field class, such as:
If you are willing to create your own field, be sure to extend it from the “Field” class.