Sugar Developer Guide Version 5.1

SugarField Widgets

SugarFields are the Objects that render the fields specified in the meta data (e.g., your *viewdefs.php files). They can be found in include/SugarFields/Fields. In the directory include/SugarFields/Fields/Base you will see the files for the base templates for rendering a field for DetailView, EditView, ListView and Search Forms. As well as the base class called SugarFieldBase.

File Structure

•	include/SugarFields/Fields/<fieldname>

•	include/SugarFields/Fields/<fieldname>/DetailView.tpl

•	modules/MyModule/vardefs.php

•	modules/MyModule/metadata/<view>defs.php

Implementation

This section describes the SugarFields widgets that are found in the include/SugarFields/Fields directory for release 5.0. Inside this folder you'll find a set of directories that encapsulate the rendering of a field type (i.e. Boolean, Text, Enum etc.). There are also SugarFields directories for grouped display values (e.g. Address, Datetime, Parent, and Relate). What we mean by rendering is that there are user interface paradigms associated with a particular field type. For example, a Boolean field type as defined in a module's vardef.php file can be displayed with a checkbox indicated the boolean nature of the field value (on/off, yes/no, 0/1, etc.). Naturally there are some displays in which the rendered user interface components are very specific to the module's logic. In this case, it is likely that custom code was used in the metadata file definition.

SugarFields widgets are rendered from the metadata framework whenever the new 5.0 MVC EditView, DetailView or list view actions are invoked for a particular module. Each of the SugarFields will be discussed briefly.

Most SugarFields will contain a set of Smarty files to abstract rendering the field contents and supporting HTML. Some SugarFields will also contain a subclass of SugarFieldBase to override particular methods so as to control additional processing and routing of the corresponding Smarty file to use. The subclass naming convention is defined as:

SugarField[Sugar Field Type]

where the first letter of the Sugar Field Type should be in uppercase. The contents should also be placed in a corresponding .php file. For example, the contents of the enum type SugarField (rendered as <select> in HTML) is defined in include/SugarFields/Fields/Enum/SugarFieldEnum.php as:

class SugarFieldEnum extends SugarFieldBase {

function getDetailViewSmarty($parentFieldArray, $vardef, $displayParams, $tabindex) {

if(!empty($vardef['function']['returns']) && $vardef['function']['returns']== 'html'){

$this->setup($parentFieldArray, $vardef, $displayParams);

return $this->fetch('include/SugarFields/Fields/Enum/DetailViewFunction.tpl');

}else{

return parent::getDetailViewSmarty($parentFieldArray, $vardef, $displayParams, $tabindex);

}

}

function getEditViewSmarty($parentFieldArray, $vardef, $displayParams, $tabindex) {

if(!empty($vardef['function']['returns']) && $vardef['function']['returns']== 'html'){

$this->setup($parentFieldArray, $vardef, $displayParams);

return $this->fetch('include/SugarFields/Fields/Enum/EditViewFunction.tpl');

}else{

return parent::getEditViewSmarty($parentFieldArray, $vardef, $displayParams, $tabindex);

}

}

function getSearchViewSmarty($parentFieldArray, $vardef, $displayParams, $tabindex) {

if(!empty($vardef['function']['returns']) && $vardef['function']['returns']== 'html'){

$this->setup($parentFieldArray, $vardef, $displayParams, $tabindex);

return $this->fetch('include/SugarFields/Fields/Enum/EditViewFunction.tpl');

}else{

$this->setup($parentFieldArray, $vardef, $displayParams, $tabindex);

return $this->fetch('include/SugarFields/Fields/Enum/SearchView.tpl');

}

}

}

Here we see how the enum type will use one of six Smarty template file depending on the view (edit, detail or search) and whether or not the enum vardef definition has a 'function' attribute defined to invoke a PHP function to render the contents of the field.

SugarFields Widgets Reference

Address

The Address field is responsible for rendering the various fields that together represent an address value. By default SugarCRM renders address values in the United States format:

Street

City, State Zip

The Smarty template layout defined in DetailView.tpl reflects this. Should you wish to customize the layout depending on the $current_language global variable, you may add new files [$current_language].DetailView.tpl or [$current_language].EditView.tpl to the Address directory that reflect the language locale's address formatting.

Within the metadata definition, the Address field can be rendered with the snippet:

array (

'name' => 'billing_address_street',

'hideLabel' => true,

'type' => 'address',

'displayParams'=>array('key'=>'billing', 'rows'=>2, 'cols'=>30, 'maxlength'=>150)

),

 

name	The vardefs.php entry to key field off of. Though not 100% ideal, we use the street value
hideLabel	Boolean attribute to hide the label that is rendered by metadata framework. We hide the billing_address_street label because the Address field already comes with labels for the other fields (city, state). Also, if this is not set to false, the layout will look awkward.
type	This is the field type override. billing_address_street is defined as a varchar in the vardefs.php file, but since we are interested in rendering an address field, we are overriding this here
displayParams	key - This is the prefix for the address fields. The address field assumes there are [key]_address_street, [key]_address_state, [key]_address_city, [key]_address_postalcode fields so this helps to distinguish in modules where there are two or more addresses (e.g. 'billing' and 'shipping'). rows, cols, maxlength - This overrides the default HTML <textarea> attributes for the street field component.

Note also the presence of file include/SugarFields/Fields/Address/SugarFieldAddress.js. This file is responsible for handling the logic of copying address values (from billing to shipping, primary to alternative, etc.). The JavaScript code makes assumptions using the key value of the grouped fields.

To customize various address formats for different locales, you may provide a locale specific implementation in the folder include/SugarFields/Fields/Address. There is a default English implementation provided. Locale implementations are system wide specific (you cannot render an address format for one user with an English locale and another format for another with a Japanese locale). SugarCRM locale settings are system wide and the SugarField implementation reflects this. To modify based on a user's locale preferences will require some customizations, but is possible.

Base

The Base field is the default parent field. It simply renders the value as is for DetailViews and an HTML text field <input type="text"> for EditViews. All SugarFields that have a corresponding PHP file extend from SugarFieldBase.php.

Bool

The Bool field is responsible for rendering a checkbox to reflect the state of the value. In release 5.0 all boolean fields are stored as integer values. The Bool field will render a disabled checkbox for DetailViews. If the field value is "1" then the checkbox field will be checked. There isno special parameter to pass into this field from the metadata definition. As with any of the fields you have the option to override the label key string.

For example, in the metadata definition, the Boolean field do_not_call can be specified as:

'do_not_call'

or

array (

array('name'=>'do_not_call',

'label'=>'LBL_DO_NOT_CALL' // Overrides label as defined in vardefs.php

)

),

Datetime

The Datetime field is responsible for rendering an input text field along with an image to invoke the popup calendar picker. The Datetime field is different from the Datetimecombo field in that there is no option to select the time values of a datetime database field.

Within the metadata definition, the Datetime field can be rendered with the snippet:

'date_quote_expected_closed', // Assumes that date_quote_exected_closed is defined

// as a datetime field in vardefs.php file

or

array('name'=>'date_quote_expected_closed',

'displayParams'=>array('required'=>true, 'showFormats'=>true)

),

 

name	Standard name definition when metadata definition is defined as an array
displayParams	required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. showFormats (optional) - Displays the user's date display preference as retrieved from the global $timedate variable's get_user_date_format() method.

Datetimecombo

The Datetimecombo field is similar to the Datetime field with additional support to render dropdown lists for the hours and minutes values as well as a checkbox to enable/disable the entire field. New in Sugar5.x is the consolidation of the date portion (e.g. 12/25/2007) and time portion (e.g. 23:45) of the database fields. For example, in the 4.5.x versions, the Calls and Meetings module defined two separate vardefs.php entries for the date and time portion. Now that these two fields are consolidated, care must be taken by the module developer to handle input from three HTML field values within the module class code. Take for instance the vardefs.php definition for the date_start field in the Calls module:

'date_start' => array (

'name' => 'date_start',

'vname' => 'LBL_DATE',

'type' => 'datetime',

'required' => true,

'comment' => 'Date in which call is schedule to (or did) start'

),

There is one database field, but when the Datetimecombo widget is rendered, it will produce three HTML fields for display- a text box for the date portion and two dropdown lists for the hours and minutes values. The Datetimecombo widget will render the hours and menu dropdown portion in accordance to the user's $timedate preferences. An optional AM/PM meridiem drop down is also displayed should the user have selected a 12 hour base format (e.g. 11:00).

Within the metadata definition, the Datetimecombo field can be rendered with the snippet:

array('name'=>'date_start',

'type'=>'datetimecombo',

'displayParams'=>array('required' => true,

'updateCallback'=>'SugarWidgetScheduler.update_time();',

'showFormats' => true,

'showNoneCheckbox' => true),

'label'=>'LBL_DATE_TIME'),

 

name	Standard name definition when metadata definition is defined as an array
type	metadata type override. By default, the field defaults to Datetime so we need to override it here in the definition.
displayParams	required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. updateCallback (optional) - Defines custom JavaScript function to invoke when the values in the field are changed (date, hours or minutes). showFormats (optional) - Displays the user's date display preference as retrieved from the global $timedate variable's get_user_date_format() method. showNoneCheckbox (optional) - Displays a checkbox that when checked will disable all three field values
label (optional)	Standard metadata label override just to highlight this exhaustive example

Download

The File field renders a link that references the download.php file for the given displayParam['id'] value when in DetailView mode.

Within the metadata definition, the Download field can be rendered with the snippet:

array (

'name' => 'filename',

'displayParams' => array('link'=>'filename', 'id'=>'document_revision_id')

),

 

name	Standard name definition when metadata definition is defined as an array
displayParams	required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. id (required for DetailView) - The field for which the id of the file will be opened via the download link. link (required for DetailView) - The field for which the hyperlink value is displayed.

Enum

The Enum field renders an HTML <select> form element that allows for a single value to be chosen. The size attribute of the <select> element is not defined so the element will render as a dropdown display in the EditView.

This field accepts the optional function override behavior that is defined at the vardefs.php file level. For example, in the Bugs module we have for the found_in_release field:

'found_in_release'=>

array(

'name'=>'found_in_release',

'type' => 'enum',

'function'=>'getReleaseDropDown',

'vname' => 'LBL_FOUND_IN_RELEASE',

'reportable'=>false,

'merge_filter' => 'enabled',

'comment' => 'The software or service release that manifested the bug',

'duplicate_merge' => 'disabled',

'audited' =>true,

),

 

The function override is not handled by the SugarFields library, but by the rendering code in include/EditView/EditView2.php.

Within the metadata definition, the Download field can be rendered with the snippet:

array (

'name' => 'my_enum_field',

'type' => 'enum',

'displayParams' => array('javascript'=>'onchange="alert(\'hello world!\')";')

),

 

 

name

Standard name definition when metadata definition is defined as an array

displayParams

size (optional) – Controls the size of the field (affects SearchForm control on the browser only). Defaults to value of 6 for SearchForm. required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. javascript (optional) - Custom JavaScript to embed within the <select> tag element (see above example for onchange event implementation).

File

The File field renders a file upload field in EditView and a hyperlink to invoke download.php in DetailView. Note that you will need to override the HTML form's enctype attribute to be "multipart/form-data" when using this field and handle the upload of the file contents in your code. This form enctype attribute should be set in the editviewdefs.php file. For example, for the Document's module we have the form override:

$viewdefs['Documents']['EditView'] = array(

'templateMeta' => array('form' =>

array('enctype'=>'multipart/form-data', // <--- override the enctype

),

)

Within the metadata file, the File field can be rendered with the snippet:

array (

'name' => 'filename',

'displayParams' => array('link'=>'filename', 'id'=>'document_revision_id'),

),

 

name

Standard name definition when metadata definition is defined as an array

displayParams

required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. id (required for detailviewdefs.php) - The record id that download.php will use to retrieve file contents link (required for detailviewdefs.php) - The text to display between the <a> </> tags. size (optional) - Affects EditView only. Override to set the display length attribute of the input field. maxlength(optional) - Affects EditView only. Override to set the display maxlength attribute of the input field (defaults to 255).

Html

The Html field is a simple field that renders read-only content after the content is run through the from_html method of include/utils/db_utils.php to encode entity references to their HTML characters (i.e. "&gt;" => ">"). The rendering of the Html field type should be handled by the custom field logic within SugarCRM.

name	Standard name definition when metadata definition is defined as an array.
displayParams	none

 

Iframe

In the DetailView, the Iframe field creates an HTML <iframe> element where the src attribute points to the given URL value supplied in the EditView. Alternativly, the URL may be generated from the values of other fields, and the base URL in the vardefs. If this is the case, the field is not editable in the EditView.

name	Standard name definition when metadata definition is defined as an array.
displayParams	None

 

Image

Similar to the Html field, the Image field is simply renders a <img> tag where the src attribute points to the value of the field. Image fields are rendered for DetailViews only.

Within the metadata file, the Image field can be rendered with the snippet:

array (

'name' => 'my_image_value', // <-- The value of this is assumed to be some

// URL to an image file

'type' => 'image',

'displayParams'=>array('width'=>100, 'length'=>100,

'link'=>'http://www.cnn.com', 'border'=>0),

),

 

name	Standard name definition when metadata definition is defined as an array
displayParams	link (optional) - Hyperlink for the image when clicked on. width (optional) - Width of image for display. height (optional) - Height of image for display. border (optional) - Border thickness of image for display

Link

The link field simply generates an <a> HTML tag with a hyperlink to the value of the field for DetailViews. For EditViews, it provides the convenience of pre-filling the "http://" value. Alternatively, the URL may be generated from the values of other fields, and the base URL in the vardefs. If this is the case, the field is not editable in the EditView.

Within the metadata file, the Link field can be rendered with the snippet:

array (

'name' => 'my_image_value', // <-- The value of this is assumed to

// be some URL to an image file

'type' => 'link',

'displayParams'=>array('title'=>'LBL_MY_TITLE'),

),

 

name

Standard name definition when metadata definition is defined as an array

displayParams

required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. title (optional for detailviewdefs.php only) - The <a> tag's title attribute for browsers to display the link in their status area size (optional) - Affects EditView only. Override to set the display length attribute of the input field. maxlength(optional) - Affects EditView only. Override to set the display maxlength attribute of the input field (defaults to 255).

Multienum

The Multienum fields renders a bullet list of values for DetailViews and renders a <select> form element for EditViews that allow multiple values to be chosen. Typically, the custom field handling in SugarCRM will map multienum types created via Studio so you would not need to declare metadata code to specify the type override. Nevertheless, within the metadata file, the Multienum field can be rendered with the snippet:

array (

'name' => 'my_multienum_field',

'type' => 'multienum',

'displayParams' => array('javascript'=>'onchange="alert(\'hello world!\')";')

),

 

name

Standard name definition when metadata definition is defined as an array

displayParams

size (optional) – Controls the size of the field (affects SearchForm control on browser only). Defaults to value of 6 for SearchForm. required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. javascript (optional) - Custom JavaScript to embed within the <select> tag element (see above example for onchange event implementation).

Parent

The parent field combines a blend of a dropdown for the parent module type and a text field with code to allow quicksearch for quicksearch enabled modules (please see include/SugarFields/Fields/Parent/EditView.tpl file contents and the JavaScript code there for more info on quicksearch enabling). There are also buttons to invoke popups and a button to clear the value. Because the parent field assumes proper relationships within the SugarCRM modules it is not a field you can add via Studio nor a field you should attempt to type override in the metadata files.

Password

The password field simply renders an input text field with the type attribute set to "password" to hide user input values. It is available to EditViews only.

name	Standard name definition when metadata definition is defined as an array
displayParams	required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. size (optional) - Override to set the display length attribute of the input field (defaults to 30).

Phone

The phone field simply invokes the callto:// URL references that could trigger Skype or other VOIP applications installed on the user's system. It is rendered for DetailViews only.

Radioenum

The Radioenum field renders a group of radio buttons. Radioenum fields are similar to the enum field, but only one value can be selected from the group.

Readonly

The readonly field simply directs EditView calls to use the SugarField's DetailView display. There are no Smarty .tpl files associated with this field.

Relate

The Relate field combines a blend of a text field with code to allow quicksearch. The quicksearch code is generated for EditViews (see include/TemplateHandler/TemplateHandler.php). There are also buttons to invoke popups and a button to clear the value. For DetailViews, the Relate field creates a hyperlink that will bring up a DetailView request for the field's value.

Within the metadata file, the Relate field can be rendered with the snippet:

array (

array('name'=>'account_name',

'type'=>'relate',

'displayParams'=>array('allowNewValue'=>true)

),

),

This will create a relate field that allows the user to input a value not found in the quicksearch list.

name

Standard name definition when metadata definition is defined as an array

displayParams

required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. readOnly (optional for editviewdefs.php file only) - Makes the text field input area readonly so that you have to just use the popup selection. popupData - This field is generated for you by default. See include/SugarFields/Fields/SugarFieldRelate.php for more information. You should not need to override this setting. allowNewValue (optional for editviewdefs.php file only) - This setting allows the user to specify a value that is not found from the quicksearch list of results. hideButtons (optional for editviewdefs.php SearchForm.php and popupdefs.php) – Hides the Select and Clear buttons normally displayed next to the editable Relate field.

Text

The Text field renders a <textarea> HTML form element for EditViews and dislpays the field value with newline characters converted to HTML elements in DetailViews.

name

Standard name definition when metadata definition is defined as an array

displayParams

required (optional) - Marks the field as required and applies clients side validation to ensure value is present when save operation is invoked from EditView. maxlength (optional for editviewdefs.php file only) - Sets the maximum length of character input allowed in the <textarea> field. rows (optional for editviewdefs.php file only) - Sets the number of rows in the <textarea>field. cols (optional for editviewdefs.php file only) - Sets the number of cols in the <textarea> field.

Username

The Username field is a helper field that assumes a salutation, first_name and last_name field exists for the vardefs of the module. It displays the three fields in the format:

[salutation] [first_name] [last_name]