Overview of VarDefs

[Jacob]

The vardefs are used to provide the Sugar application with information about the SugarBeans. The specify information on the individual fields, relationships between beans, and the indexes for a given bean.

Each module that has a SugarBean file will have a vardefs.php file located in it. This file specifies the fields for that
SugarBean. For the Contact bean, the vardefs will be located in sugarcrm/modules/Contacts/vardefs.php.

Vardef files create an array called "$dictionary" with a bunch of sub-values defined.


Dictionary Array

• 'table' = The database table for this bean
• 'audited' = True if this module has auditing turned on
• 'fields' = The list of fields and attributes about them (see below)
• 'indices' = A list of indexes that should be created in the database (see below)
• 'relationships' = A list of the relationships for this bean (see below)
• 'optimistic_locking' = True if this module should obey optimistic locking. Optimistic locking uses the modified date to ensure that the bean you are working on has not been modified by anybody else when you try and save. This prevents loss of data.

Fields Array

The fields array contains a bunch of arrays. It has one array for each field in the SugarBean. At the top level of this array the key is the name of the field, and the value is an array of attributes about that field.

Here is the list of possible attributes for fields.

• 'name' = The name of the field
• 'vname' = The language pack id for the label of this field
• 'type' = The type of the attribute
  
  • 'relate' = Related Bean
  • 'datetime' = A date and time
  • 'bool' = A boolean value
  • 'enum' = An enumeration (drop down list from the language pack)
  • 'char' = A character array
  • 'assigned_user_name' = A linked user name
  • 'varchar' = A variable sized string
• 'table' = The table this field comes from
• 'isnull' = Is this field allowed to be set to null?
• 'len' = The length of the field (number of characters if a string)
• 'options' = The name of the enumeration in the language pack for this field
• 'dbtype' = The database type of the field (if different than the type)
• 'reportable' = Should this field show up in the list of fields for the reporting module (if applicable).
• 'required' = true if this field is a required field
• 'default' = The default value for this field
• 'massupdate' = false if you do not want this field to show up in the mass update section at the bottom of the list views. Defaults to true.
• 'rname' = (for type relate only) The field from the related variable that has the text
• 'id_name' = (for type relate only) The field from the bean that stores the id for the related Bean
• 'source' = 'nondb' if the field value does not come from the database. This can be used for calculated values or values retrieved in some other way.
• 'sort_on' => The field to sort by if multiple fields are used.
• 'fields' => (for concatinated values only) An array containing the fields that are concatinated.
• 'db_concat_fields'=> (for concatinated values only) An array containing the fields to concatinate in the DB.

Sample Fields Array Entries

     'id' => 
              array (
                'name' => 'id',
                'vname' => 'LBL_ID',
                'type' => 'id',
                'required'=>true,
              ), 
  

This is a standard ID field for a Bean.

 'first_name' => 
              array (
                'name' => 'first_name',
                'vname' => 'LBL_FIRST_NAME',
                'dbType' => 'varchar',
                'type' => 'name',
                'len' => '30',
              ), 
  

First name field retrieved from the database. It is a varchar of size 30. The label that should be used for it is LBL_FIRST_NAME.

    'created_by' => 
              array (
                'name' => 'created_by',
                'rname' => 'user_name',
                'id_name' => 'modified_user_id',
                'vname' => 'LBL_ASSIGNED_TO',
                'type' => 'assigned_user_name',
                'table' => 'users',
                'isnull' => 'false',
                'dbType' => 'id'
              ), 
  

This is specifying a related field. The modified_user_id can be looked up in the users table to retrieve the user_name. This will automatically translate the modified_user_id into the more user friendly user_name for display purposes.

               'full_name' =>
              array (
                'name' => 'full_name',
                'rname' => 'full_name',
                'vname' => 'LBL_NAME',
                'type' => 'name',
                'fields' => array('first_name','last_name'),
                'source' => 'non-db',
                'sort_on' => 'last_name',
                 'db_concat_fields'=> array(0=>'first_name', 1=>'last_name'),
                'len' => '510',
              ), 
  

This creates a non-db field that concatinates the first_name and last_name fields. The sort_on value is set to last name to say that when a user tries to sort a list view on this column, they are specifying sorting on the last_name field.



Indices Array

This array contains a list of arrays that are used to create indexes in the database.
The fields in this array are:

• 'name' = The name of the index. This must be unique in most databases.
• 'type' = The type of the index (primary or index)
• 'fields' = The fields to index. This is an ordered array.

Sample Indices Array Entries

 array('name' =>'userspk', 'type' =>'primary', 'fields'=>array('id')), 
  

Create a primary index called 'userspk' on the 'id' column

         array('name' =>'user_name', 'type' =>'index', 'fields'=>array('user_name')), 
  

Create a normal index called 'user_name' on the user_name column.

         array('name' => 'idx_contact_del_team', 'type' => 'index', 'fields'=>array('deleted', 'team_id')), 
  

Create a normal index called 'idx_contact_del_team' on the deleted and team_id columns.


Relationships Array

The relationships array is used to specify relationships between Beans. Like the Indices array entries, it is a list of names with array values.
The possible attributes of a relationship entry are:

• 'lhs_module' = The module on the left hand side of the relationship
• 'lhs_table' = The table on the left hand side of the relationship
• 'lhs_key' = The primary key column of the left hand side of the relationship
• 'rhs_module' = The module on the right hand side of the relationship
• 'rhs_table' = The table on the right hand side of the relationship
• 'rhs_key' = The primary key column of the right hand side of the relationship
• 'relationship_type' = The type of relationship ('one-to-many' or 'many-to-many')

Sample Relationships Array Entries

         'contact_direct_reports' => array(
                'lhs_module' => 'Contacts', 
                'lhs_table' => 'contacts', 
                'lhs_key' => 'id',
                'rhs_module' => 'Contacts', 
                'rhs_table' => 'contacts', 
                'rhs_key' => 'reports_to_id',    
                'relationship_type' => 'one-to-many'), 
  

This creates the reporting relationship between a contact and the person that they report to. The reports_to_id field is used to map to the id field in the contact of the person they report to. This is a one to many relationship in that each person is only allowed to report to one person. Each person is allowed to have an unlimited number of direct reports.

 'contact_campaign_log' => array(
                'lhs_module'        =>    'Contacts', 
                'lhs_table'        =>    'contacts', 
                'lhs_key'         =>     'id',
                'rhs_module'        =>    'CampaignLog', 
                'rhs_table'        =>    'campaign_log', 
                'rhs_key'         =>     'target_id',    
                'relationship_type'    =>    'one-to-many'), 
  

This creates the campaign log for contacts. Every time an email campaign is sent out, all contacts that are affected get a link to the campaign. The 'target_id' field from the campaign_log links to the 'id' field of the contact. This is also a one to many relationship as contacts can be logged as having participated in multiple campaigns but each campaign log can only have one contact.

There is a helper object in the database called VarDefHandler. It is located in sugarcrm/include/VarDefHandler/VarDefHandler.php. It is used to assist in the parsing of vardefs.

Jacob

[dkmeans]

Absolultely awesome!

[Jacob]

Glad you like it.

Next up should be an overview of the Business Logic Hooks.

Jacob

[rliebscher]

Hi Jacob,

great documentation!

But i think u missed some field-types:

• id
• name
• phone
• email
• text
• link

I think, it will also be good to show the semantic relations for some of these types, like:

type = link, then u have to set source = non-db, relationship="name of relation", link_type, module and so on.
type = phone | email, u have to set dbtype and len to configure db.

I dont know all semantics this time. Maybe it is easy for you to explain.
Or some other forum-user can document it and u extend this docu with there text.

But again, thanks for this documentation

Ronny

[zongjunhu]

From the overview document, 'rname' and 'id_name' are for type 'relate' only. However, I also found they are widely used by other types. For example, in modules/Contacts/vardefs.php, they can also be found in fields, 'created_by' and 'modified_user_id'. I am not able to find out where they have been used. Anyone has any idea?

Another question, why 'id_name' in 'created_by' and 'modified_user_id' are the same?

Thanks.

[bcoullard]

Jacob,

Is there an easy way to relate a custom field?
I have a custom field on leads that stores the id of a related record in another table. Can I define this relationship in the vardef such that I can show these related records in a subpanel fo the lead?

[kbrill]

Jacob,

Is there an easy way to relate a custom field?
I have a custom field on leads that stores the id of a related record in another table. Can I define this relationship in the vardef such that I can show these related records in a subpanel fo the lead?

Is this other table a standard SugarCRM table? If so of course you can tie it together with vardefs.php. If not then it will be a little harder. Supply a little more information.

[lambertr]

Jacob,

Great job on the vardefs reference! It actually sorts out quite a few things.

I am still a little unsure on how to do something though, and was wondering if vardefd is the way to go and how it would be implemented.

I am wanting to have a custom fields to pull related information from the parent ID (let's say account_name from Leads) and use it to partially prepopulate the subject field when creating a new Task or Call.

It seems like vardefs would be the way to do this, but I am not quite getting how to set the relationship and get the field data.

Thanks,
Russell

[kbrill]

Jacob,

Great job on the vardefs reference! It actually sorts out quite a few things.

I am still a little unsure on how to do something though, and was wondering if vardefd is the way to go and how it would be implemented.

I am wanting to have a custom fields to pull related information from the parent ID (let's say account_name from Leads) and use it to partially prepopulate the subject field when creating a new Task or Call.

It seems like vardefs would be the way to do this, but I am not quite getting how to set the relationship and get the field data.

Thanks,
Russell

OK, let me see if I can understand this. You want the subject field to be 'partially' filled when the user selects an account.. right? There really isnt a custom field in that. That would be coded into the pop up window.

[lambertr]

OK, let me see if I can understand this. You want the subject field to be 'partially' filled when the user selects an account.. right? There really isnt a custom field in that. That would be coded into the pop up window.

I guess I left out some detail there. I have no problems modifing the page code to put iin the variable that would be created from vardefs.php as a default in the "subject" field (or anywhere else for that matter). I am just trying to use vardefs as a way to get a variable which I can put in the HTML template that will fill in that information by default. I figure it would be best to do it this way in order to stay within the framework of the application and not have to be writing extra queries and associated code where I don't have to.

Really I understand that that is going to get converted into a query, and since I have serveral modifications of this type that need to be made, I feel that a "simple" example like this is probably the best way to get my hand around how/if vardefs can be used.

Thanks,
Russell