Vardefs

Overview

Vardefs (Variable Definitions) provide the Sugar application with information about SugarBeans. Vardefs specify information on the individual fields, relationships between beans, and the indexes for a given bean.

Each module that contains a SugarBean file has a vardefs.php file located in it, which specifies the fields for that SugarBean. For example, the vardefs for the Contact bean are located in ./modules/Contacts/vardefs.php.

Dictionary Array

Vardef files create an array called $dictionary, which contains several entries including tables, fields, indices, and relationships.

table : The name of the database table (usually, the name of the module) for this bean that contains the fields
audited : Specifies whether the module has field-level auditing enabled
duplicate_check : Determines if duplicate checking is enabled on the module, and what duplicate check strategy will be used if enabled.
fields : A list of fields and their attributes
indices : A list of indexes that should be created in the database
optimistic_locking : Determines whether the module has optimistic locking enabled
- Optimistic locking prevents loss of data by using the bean's modified date to ensure that it is not being modified simultaneously by more than one person or process.
unified_search : Determines whether the module can be searched via Global Search
- This setting defaults to false and has no effect if all of the fields in the fields array have the 'unified_search' field attribute set to false.
unified_search_default_enabled : Determines whether the module should be searched by default for new users via Global Search
- This setting defaults to true but has no effect if unified_search is set to false.
visibility : A list of visibility classes enabled on the module

Duplicate Check Array

The duplicate_check array contains two properties, that control if duplicate checking is enabled on the module, and which duplicate check strategy will be used to check for duplicates.

The two properties for the array are as follows:

Name	Type	Description
enabled	Boolean	Specifies whether or not the Bean is utilizing the duplicate check framework
<class_name>	Array	<class_name> is the name of the duplicate check strategy class that is handling the duplicate checking. It is set to an array of Metadata, specific to the strategy defined in the key. Review the Duplicate Check Framework for further information.

Fields Array

The fields array contains 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.

The list of possible attributes are as follows:

name : The name of the field
vname : The language pack ID for the label of this field
type : The type of the attribute
- assigned_user_name : A linked user name
- bool : A boolean value
- char : A character array
- date : A date value with no time
- datetime : A date and time
- email : An email address field
- enum : An enumeration (dropdown list from the language pack)
- id : A database GUID
- image : A photo-type field
- link : A link through an explicit relationship. This attribute should only be used when working with related fields. It does not make the field render as a link.
- name : A non-database field type that concatenates other field values
- phone : A phone number field to utilize with callto:// links
- relate : Related bean
- team_list : A team-based ID
- text : A text area field
- url : A hyperlinked field on the detail view
- varchar : A variable-sized string
table : The database table the field comes from.
- The table attribute is only needed to join fields from another table outside of the module in focus.
isnull : Whether the field can contain a null value
len : The length of the field (number of characters if a string)
options : The name of the enumeration (dropdown list) in the language pack for the field
dbtype : The database type of the field (if different than the type)
reportable : Determines whether the field will be available in the Reports and Workflow modules
default : The default value for this field. Default values for the record are populated by default on create for the record view (for Sidecar modules) and edit view (for Legacy modules) layout but can be modified by users. The Default Value option is available for all data type fields except HTML, Image, Flex Relate, and Relate.
massupdate : Determines whether the field will show up in the mass-update panel on its module's list view
- Some field types are restricted from mass update regardless of this setting.
rname : For relate-type fields, the field from the related variable that contains the text
id_name : For relate-type fields, the field from the bean that stores the ID for the related bean
source : Set to 'non-db' if the field value does not come from the database
- The source attribute 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 in the presentation of field's information
fields : For concatenated values, an array containing the fields that are concatenated
db_concat_fields : For concatenated values, an array containing the fields to concatenate in the database
unified_search : Determines whether the field can be searched via Global Search
- This has no effect if the dictionary array setting 'unified_search' is not set to true.
enable_range_search : For date, datetime, and numeric fields, determines if this field should be searchable by range in module searches
dependency : Allows a field to have a predefined formula to control the field's visibility
studio : Controls the visibility of the field in the Studio editor
- If set to false, then the field will not appear in any studio screens for the module. Otherwise, you may specify an Array of view keys from which the field's visibility should be removed (e.g. array('listview'=>false) will hide the field in the listview layout screen).

The following example illustrates a standard ID field for a bean:

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

Indices Array

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

name : The unique name of the index
type : The type of index (primary, unique, or index)
fields : An ordered array of the fields to index
source : Set to 'non-db' if you are creating an index for added application functionality such as duplication checking on imports

The following example creates a primary index called 'userspk' on the 'id' column:

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

Relationships Array

The relationships array specifies relationships between beans. Like the indices array entries, it is a list of names with array values.

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 (e.g. one-to-many, many-to-many)
relationship_role_column : The type of relationship role
relationship_role_column_value : Defines the unique identifier for the relationship role

The following example creates a relationship between a contact and the contact that they report to. The reports_to_id field maps to the id of the record that belongs to the higher-ranked contact. This is a one-to-many relationship in that a contact may only report to one person, but many people may report to the same contact.

  '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'
),

Visibility Array

The visibility array specifies the row level visibility classes that are enabled on the bean. Each entry in the array, is a key-value pair, where the key is the name of the Visibility class and the value is set to boolean True. More information on configuring custom Visibility strategies can be found in the Architecture section under Visibility Framework.

Extending Vardefs

More information about extending and overriding vardefs can be found in the Extensions Framework documentation under Vardefs.