X2Model and Dynamic Fields - Revision history

Demitri: /* Introduction */

2014-05-02T21:35:38Z

‎Introduction

Demitri: /* Field Types */

2013-09-07T00:03:18Z

‎Field Types

Demitri: /* Field Types */

2013-02-21T20:05:34Z

‎Field Types

Demitri: /* Introduction */

2013-02-21T20:00:31Z

‎Introduction

Demitri: /* Introduction */

2013-02-21T19:59:19Z

‎Introduction

Demitri: /* Introduction */

2013-02-21T19:53:57Z

‎Introduction

Demitri: /* Introduction */

2013-02-21T19:53:40Z

‎Introduction

Demitri: /* Setting automatic record links in child classes */

2012-09-19T19:28:33Z

‎Setting automatic record links in child classes

Demitri: /* Setting automatic record links in child classes */

2012-09-19T19:26:41Z

‎Setting automatic record links in child classes

Demitri: /* Setting automatic record links in child classes */

2012-09-19T19:25:53Z

‎Setting automatic record links in child classes

← Older revision		Revision as of 21:35, 2 May 2014
Line 3:		Line 3:
	= Introduction =		= Introduction =

−	Typically in Yii, when a model (see: [[yii:CActiveRecord\|CActiveRecord]]) is used to retrieve data from a table in the database, the model's attributes are simply inherited from the schema for that table. However, in order to provide the means to add and remove fields from models (and thus from database tables), in addition to providing more advanced options for setting behaviors of attributes, most of the model classes in ~~X2EngineCRM~~ (the ones that are associated with database tables) are extended from a class [[x2doc:X2Model\|X2Model]]. The attributes of all such models are not derived from the database itself but from an attribute registry stored in the <tt>x2_fields</tt> table. The following columns in the fields table are of particular importance:	+	Typically in Yii, when a model (see: [[yii:CActiveRecord\|CActiveRecord]]) is used to retrieve data from a table in the database, the model's attributes are simply inherited from the schema for that table. However, in order to provide the means to add and remove fields from models (and thus from database tables), in addition to providing more advanced options for setting behaviors of attributes, most of the model classes in X2Engine (the ones that are associated with database tables) are extended from a class [[x2doc:X2Model\|X2Model]]. The attributes of all such models are not derived from the database itself but from an attribute registry stored in the <tt>x2_fields</tt> table. The following columns in the fields table are of particular importance:

@@ Line 130: / Line 130: @@
 |FLOAT
 |Arbitrary numeric value rendered with a percent symbol after it.
 |}

@@ Line 126: / Line 126: @@
 |INT
 |If 1, the record's contents are public. If 0, it is private. If 2, the record is visible only to the user's groups.
 |}

@@ Line 4: / Line 4: @@
 Typically in Yii, when a model (see: [[yii:CActiveRecord|CActiveRecord]]) is used to retrieve data from a table in the database, the model's attributes are simply inherited from the schema for that table. However, in order to provide the means to add and remove fields from models (and thus from database tables), in addition to providing more advanced options for setting behaviors of attributes, most of the model classes in X2EngineCRM (the ones that are associated with database tables) are extended from a class [[x2doc:X2Model|X2Model]]. The attributes of all such models are not derived from the database itself but from an attribute registry stored in the <tt>x2_fields</tt> table. The following columns in the fields table are of particular importance:
 {|class="wikitable" align="left"
 |-
 ! scope="col" | Field Name
 ! scope="col" | Value
 |-
 ! scope="row" | modelName
 | The exact name of the model class to which the field belongs, with a few if any exceptions (i.e. fields with modelName="Quotes" belong to class [[x2doc:Quote|Quote]])
 |-
 ! scope="row" | fieldName
 | The name of the database column
 |-
 ! scope="row" | attributeLabel
 | The attribute label (the name of the field as displayed in the UI)
 |-
 ! scope="row" | modified
 | Whether the field has been modified by the user.
 |-
 ! scope="row" | custom
 | Whether the field has been created by the user.
 |-
 ! scope="row" | type
 | The type of the column. This does not merely specify the canonical MySQL type, but is used for specifying advanced behaviors for the field. See [[#Field Types|Field Types]] for more information.
 |-
 ! scope="row" | required
 | Specifies that the model attribute cannot be null or empty, if set to 1.
 |-
 ! scope="row" | readOnly
 | Signifies that the model attribute cannot be modified through user input, if set to 1.
 |-
 ! scope="row" | linkType
 | In the case that the field is being used as a link, keywords set in this field signify what type of link should be generated in output.
 |-
 ! scope="row" | searchable
 | If set to 1, the field's contents are included in global searches through records.
 |-
 ! scope="row" | relevance
 | A value used for sorting search results: "Low", "Medium" or "High"
 |-
 ! scope="row" | isVirtual
 | If set to 1, the field does not actually correspond to a database column; rather, it is an ephemeral attribute of the model that is used for passing data from the view to the controller and vice-versa. For instance, it would be used in the case of input that needs to be collected as part of the model (initially) so that it can be put through input validation.
 |-
 |}

@@ Line 12: / Line 12: @@
 |-
 ! scope="row" | modelName
-| The exact name of the model class to which the field belongs, with only one exception (fields with modelName="Quotes" belong to class [[x2doc:Quote|Quote]])
+| The exact name of the model class to which the field belongs, with a few if any exceptions (i.e. fields with modelName="Quotes" belong to class [[x2doc:Quote|Quote]])
 | Plain text (filtered/mapped to be human-readable)
 |-
@@ Line 22: / Line 22: @@
 | The attribute label (the name of the field as displayed in the UI)
 | Plain text
 |-
 |}
 = Field Types =

@@ Line 5: / Line 5: @@
 Typically in Yii, when a model (see: [[yii:CActiveRecord|CActiveRecord]]) is used to retrieve data from a table in the database, the model's attributes are simply inherited from the schema for that table. However, in order to provide the means to add and remove fields from models (and thus from database tables), in addition to providing more advanced options for setting behaviors of attributes, most of the model classes in X2EngineCRM (the ones that are associated with database tables) are extended from a class [[x2doc:X2Model|X2Model]]. The attributes of all such models are not derived from the database itself but from an attribute registry stored in the <tt>x2_fields</tt> table. The following columns in the fields table are of particular importance:
-;modelName
+{|class="wikitable" align="left"
-: The exact name of the model class to which the field belongs, with only one exception (fields with modelName="Quotes" belong to class [[x2doc:Quote|Quote]])
+|-
-;fieldName
+! scope="col" | Field Name
-: The name of the database column
+! scope="col" | Value
-;attributeLabel
+! scope="col" | Typically renders as
-: The attribute label (the name of the field as displayed in the UI)
+|-
 ;modified
 : Whether the field has been modified by the user.

@@ Line 99: / Line 99: @@
 Relevant documentation: [[yiiguide:basics.component#component-behavior|Component Behavior]], [[yii:CModel#behaviors-detail|CModel::behaviors()]]
-In cases where <tt>link</tt> and <tt>linkType</tt> are used, [[x2doc:X2LinkableBehavior|X2LinkableBehavior]] comes into play; X2Model inherits the behaviors and attributes from that class, since it is attached as a behavior. The method <tt>getLink</tt> is used for generating controller routes. In this method, it is assumed that the model has the same name as the controller/module. Thus, for every module/controller, the models used by them have the same names, with few exceptions. In the case of any new model that is a child class of X2Model, for which the class does not or cannot follow these naming conventions, the following steps will be necessary:
+In cases where <tt>link</tt> and <tt>linkType</tt> are used, [[x2doc:X2LinkableBehavior|X2LinkableBehavior]] comes into play; X2Model inherits the behaviors and attributes from that class, since it is attached as a behavior. The method <tt>getLink</tt> is used for generating controller routes. In this method, it is assumed that the model has the same name as the controller/module. Thus, for every module/controller, the models used by them have the same names, with few exceptions. Thus, this should typically be taken care of already. However, in the case of any new model that is a child class of X2Model, for which the class '''does not or cannot''' follow these naming conventions (i.e. a second model inside of a module that needs to use the fields table), the following steps will be necessary:
 * Override the <tt>behaviors()</tt> method so that the subclass does not have <tt>X2LinkableBehavior</tt>; have it return an empty array or an array with other desired behaviors
@@ Line 110: / Line 110: @@
 *: The route that will be used for querying auto-complete results for use in auto-completion fields.
 * Create a <tt>getLink</tt> method in the child class that generates the actual link markup.
+(Note: the attributes <tt>baseRoute</tt>, <tt>viewRoute</tt> and <tt>autoCompleteSource</tt> essentially tie the model to a "part" of the web application distinguished by its URL, thus allowing the application to generate URLs for usage of it.)

@@ Line 104: / Line 104: @@
 * Manually set the following attributes:
 *;<tt>baseRoute</tt>
-*: The route prior to any actions; may contain a module and/or a controller ID. This and <tt>viewRoute</tt> essentially tie the model to a "part" of the web application distinguished by its URL.
+*: The route prior to any actions; may contain a module and/or a controller ID.
 *;<tt>viewRoute</tt>
 *: The route (before adding the ID as a GET parameter) used for viewing records.
 *;<tt>autoCompleteSource</tt>
 *: The route that will be used for querying auto-complete results for use in auto-completion fields.
 * Create a <tt>getLink</tt> method in the child class that generates the actual link markup.