Sugar Developer Guide Version 5.1

SugarCRM MVC Implementation

The following is a sequence diagram that highlights some of the main components involved within the SugarCRM MVC framework.

Model

The Sugar Model is represented by the SugarBean and any subclass of the SugarBean. Many of the common Sugar modules also use the SugarObjects class described below.

Sugar Object Templates

Sugar Objects extend the concept of subclassing a step further and allows you to subclass the vardefs. This includes inheriting of fields, relationships, indexes, and language files, but unlike subclassing you are not limited to a single inheritance. If there were a Sugar Object for fields used across every module such as id, deleted, or date_modified, you could have your module inherit from both Basic Sugar Object and the Person Sugar Object.

Now let's say that the Basic type has a field 'name' with length 10 and Company has a field 'name' with length 20. If you inherit from Basic first then Company your field will be of length 20. Now let's say you have defined a field 'name' in your module that is of length 60. Your module will always override any values provided by Sugar Objects.

There are six types of Sugar Object Templates:

•	Basic (contains the basic fields all Sugar modules require)

•	Person (used by the Contacts, Prospects and Leads modules)

•	Issue (used by the Bugs, Cases modules)

•	Company (used by the Accounts module)

•	File (based on Documents)

•	Sale (based on Opportunities)

We can take this a step further and add assignable to the mix. An assignable module would be one that can be assigned to users. Although this isn't used by every module, many modules do let you assign records to users. SugarObject interfaces allow us to add assignable to modules we wish to let users assign records.

SugarObject interfaces and SugarObject templates are very similar to one another, but the main distinction is that templates have a base class you can subclass while interfaces do not. If you look into the file structure you will notice that templates include many additional files including a full metadata directory. This is currently used primarily for Module Builder.

File Structure

•	include/SugarObjects/interfaces

•	include/SugarObjects/templates

Implementation

There are two things you need to do to take advantage of SugarObjects:

1)	Your class needs to subclass the SugarObject class you wish to extend.

class MyClass extends Person{

function MyClass(){

parent::Person();

}

}

2)	In your vardefs.php file add the following to the end:

VardefManager::createVardef('Contacts','Contact', array('default', 'assignable','team_security', 'person'));

 

This tells the VardefManager to create a cache of the Contacts vardefs with the addition of all the default fields, assignable fields, team security fields (Sugar Professional and Enterprise only), and all fields from the person class.

Performance Considerations

VardefManager caches the generated vardefs into a single file which will be the file loaded at run time. Only if that file is not found will it load the vardefs.php file located in your modules directory. The language files also do a similar thing. This caching also includes data for custom fields and any vardef or language extensions that are dropped into the custom/ext framework.

Cache Files

•	cache/modules/<mymodule>/<object_name>vardefs.php

•	cache/modules/<mymodule>/langues/en_us.lang.php

Controller

Version 5.0 introduced a cascading controller concept to increase developer granularity over customizations and to provide additional upgrade-safe capabilities. The main controller, called SugarController, addresses the basic actions of a module from Edit and DetailViews to saving a record. Each module can override this SugarController by adding a controller.php file into its directory. This file extends the SugarController and the naming convention for the class is:

<ModuleName>Controller

 

Inside the controller you define an action method. The naming convention for the method is:

action_<action_name>

 

There are more fine grained control mechanisms a developer can use to override the controller processing. For example if a developer wanted to create a new save action there are 3 places where they could possibly override.

•	action_save - this would be the broadest specification and would give the user full control over the save process.

•	pre_save - a user could override the population of parameters from the form

•	post_save - this is where the view is being setup. At this point the developer could set a redirect url, do some post save processing, or set a different view

Upgrade-Safe Implementation

You can also add a custom Controller that should extend the modules Controller if such controller already exists. For example, if you want to extend the controller for a module that comes with SugarCRM release 5.0, you should check if that module already has a module-specific controller that came with the product. If so, you extend from that controller class otherwise you extend from SugarController class. In both case, you should place the custom controller class file in custom/modules/<MyModule>/Controller.php instead of the module directory. Doing so makes your customization upgrade-safe.

File Structure

•	include/MVC/Controller/SugarController.php

•	include/MVC/Controller/ControllerFactory.php

•	modules/<MyModule>/Controller.php

•	custom/modules/<MyModule>/controller.php

Implementation

class UsersController extends SugarController{

function action_SetTimeZone(){

//Save TimeZone code in here

...

}

}

Mapping actions to files

You can choose not to provide a custom action method as defined above, and instead specify your mappings of actions to files in $action_file_map. Take a look at include/MVC/Controller/action_file_map.php as an example:

$action_file_map['subpanelviewer'] = 'include/SubPanel/SubPanelViewer.php';

$action_file_map['save2'] = 'include/generic/Save2.php';

$action_file_map['deleterelationship'] = 'include/generic/DeleteRelationship.php';

$action_file_map['import'] = 'modules/Import/index.php';

Here the developer has the opportunity to map an action to a file. For example Sugar uses a generic SubPanel file for handling subpanel actions. You can see above that there is an entry mapping the action ‘subpanelviewer' to include/SubPanel/SubPanelViewer.php.

The base SugarController class loads the action mappings in the following path sequence:

•	include/MVC/Controller

•	modules/<Module-Name>

•	custom/modules/<Module-Name>

•	custom/include/MVC/Controller

Each one loads and overrides the previous definition if in conflict. You can drop a new action_file_map in the later path sequence that extends or overrides the mappings defined in the previous one.

Upgrade-Safe Implementation

If you want to add custom action_file_map.php to an existing module that came with the SugarCRM release, you should place the file at custom/modules/<Module-Name>/action_file_map.php

File Structure

•	include/MVC/Controller/action_file_map.php

•	modules/<Module-Name>/action_file_map.php

•	custom/modules/<Module-Name>/action_file_map.php

Implementation

$action_file_map['soapRetrieve'] = 'custom/SoapRetrieve/soap.php';

Classic Support (Not Recommended)

Classic support allows you to have files that represent actions within your module in a manner similar to SugarCRM 4.5.1 and prior. Essentially you can just drop in a PHP file into your module and have that be handled as an action. This is not the recommended, but is considered okay for backwards compatibility. It is a better practice to take advantage of the action_<myaction> structure.

File Structure

•	modules/<MyModule>/<MyAction>.php

Controller Flow Overview

For example if a request comes in for DetailView this is how the controller will handle that request

•	Start in index.php we load the SugarApplication instance

•	SugarApplication instantiates SugarControllerFactory

•	SugarControllerFactory loads the appropriate Controller

•	Check for custom/modules/<MyModule>/Controller.php

o	if not found, check for modules/<MyModule>/Controller.php

o	if not found, load SugarController.php

•	Call on the appropriate action

•	Check for modules/<MyModule>/<MyAction>.php

o	if not found, check for the method action_<MyAction> in the controller.

o	if not found, check for an action_file_mapping

o	if not found, report error "Action is not defined"

View

Views are responsible for the display of information to the browser. Views are not just limited to HTML data, you can have it send down JSON encoded data as part of the view or any other structure you wish. As with the controllers there is a default class called SugarView which implements a lot of the basic logic for views such as handling of headers and footers.

As a developer if you want to create a custom view you would place a view.<view_name>.php file in a views/ subdirectory within the module. For example, for the DetailView you would create a file name view.detail.php and place this within the views/ subdirectory within the module. If a views subdirectory does not exist, you should create one.

In the file you should create a class named: <Module>View<ViewName>. For example, for a list view within the Contacts module the class would be ContactsViewList. Note the first letter of each word is uppercase and all other letters are lowercase.

You can extend the class from SugarView, the parent class of all views, or you can extend from an existing view. For example extending from the out of the box list view can leverage a lot of the logic that has already been done for displaying a list view.

Methods

There are two main methods to be overridden within a view:

•

preDisplay() - This performs preprocessing within a view. When developing a new view you should not worry about this method. It is only relevant for extending existing views. For example, the include/MVC/View/views/view.edit.php file uses this and allows developers who wishes to extend this view to leverage all of the logic done in preDisplay() and either override the display() method completely or within your own display() method call parent::display().

•	display() - This performs the actual displaying of the data to the screen. This is where the logic to display output to the screen should be placed.

Loading the View

The ViewFactory class tries to load the view for view in this sequence and will use the first one it finds:

•	custom/modules/<my_module>/views/view.<my_view>.php

•	modules/<my_module>/views/view.<my_view>.php

•	custom/include/MVC/View/view.<my_view>.php

•	include/MVC/Views/view.<my_view>.php

Implementation

class ContactsViewList extends SugarView{

function ContactsViewList(){

parent::SugarView();

}

 

function display(){

echo 'This is my Contacts ListView';

}

}

File Structure

•	include/MVC/Views/view.<myview>.php

•	custom/include/MVC/Views/view.<myview>.php

•	modules/<mymodule>/views/view.<myview>.php

•	custom/modules/<mymodule>/views/view.<myview>.php

•	include/MVC/Views/SugarView.php

Display Options for Views

The Sugar MVC provides developers with granular control how the screen looks when their view is rendered. Each view can have a config file associated with it. So for the example above, a developer would place a view.edit.config.php within the views/ subdirectory and when the EditView is rendered this config file will be picked up. When loading the view ViewFactory class will merge the view config files from the following possible locations with precedence order (high to low):

•	customs/modules/<module-name>/views/view.<my_view>.config.php

•	modules/<module-name>/views/view.<my_view>.config.php

•	custom/include/MVC/View/views/view.<my_view>.config.php

•	include/MVC/View/views/view.<my_view>.config.php

 

Implementation

The format of these files is as follows:

$view_config = array('actions' =>

array('popup' => array('show_header' => false,

'show_subpanels' => false,

'show_search' => false,

'show_footer' => false,

'show_JavaScript' => true,

),

),

'req_params' => array('to_pdf' =>

array('param_value' => true,

'config' => array('show_all' => false),

),

),

);

To illustrate this process, let’s take a look at how the ‘popup’ action is processed. In this case the system will go to the actions entry within the view_config and determine the proper configuration. Also if the request contains the parameter to_pdf and is set to be true then it will automatically cause the show_all configuration parameter to be set false, which means do not show any of the options.