View

Overview

Displaying information to the browser.

What are Views?

Views, otherwise known as actions, are typically used to render views or to process logic. Views are not just limited to HTML data. You can send JSON encoded data as part of a view or any other structure you wish. As with the controllers, there is a default class called SugarView which implements much of the basic logic for views, such as handling of headers and footers.

There are five main actions for a module:

• Display Actions
  • Detail View: A detail view displays a read-only view of a particular record. Usually, this is accessed via the list view. The detail view displays the details of the object itself and related items (subpanels).
    Subpanels are miniature list views of items that are related to the parent object. For example, Tasks assigned to a Project, or Contacts for an Opportunity will appear in subpanels in the Project or Opportunity detail view. The file ./<module>/metadata/detailviewdefs.php defines a module's detail view page layout. The file ./<module>/metadata/subpaneldefs.php defines the subpanels that are displayed in the module's detail view page.
  • Edit View: The edit view page is accessed when a user creates a new record or edits details of an existing one. Edit view can also be accessed directly from the list view. The file ./<module>/metadata/editviewdefs.php defines a module's edit view page layout.
  • List View: This Controller action enables the search form and search results for a module. Users can perform actions such as delete, export, update multiple records (mass update), and drill into a specific record to view and edit the details. Users can see this view by default when they click one of the module tabs at the top of the page. Files in each module describe the contents of the list and search view.
• Process Actions
  • Save: This Controller action is processed when the user clicks Save in the record's edit view.
  • Delete: This action is processed when the user clicks "Delete" in the detail view of a record or in the detail view of a record listed in a subpanel.

Implementation

Class File Structure

• ./include/MVC/Views/SugarView.php
• ./include/MVC/Views/view.<view>.php
• ./custom/include/MVC/Views/view.<view>.php
• ./modules/<module>/views/view.<view>.php
• ./custom/modules/<module>/views/view.<view>.php

Class Loading

The ViewFactory class loads the view based off the the following sequence loading the first file it finds:

• ./custom/modules/<module>/views/view.<view>.php
• ./modules/<module>/views/view.<view>.php
• ./custom/include/MVC/View/view.<view>.php
• ./include/MVC/Views/view.<view>.php

Methods

There are two main methods to override within a view:

• preDisplay(): This performs pre-processing within a view. This method is relevant only for extending existing views. For example, the include/MVC/View/views/view.edit.php file uses it, and enables 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 method displays the data to the screen. Place the logic to display output to the screen here.

Creating Views

Creating a new/view action consists of a controller action and a view file. The first step is to define your controller action. If the module does not contain a controller.php file in ./modules/<module>/ you will create the following file:

./custom/modules/<module>/controller.php

  <?php

class <module>Controller extends SugarController
{
    function action_MyView()
    {
        $this->view = 'myview';
    }
}

More information on controllers can be found in the Controller section.

The next step is to define your view file. This example extends the ViewDetail class but you can extend any of the classes you choose in ./include/MVC/View/views/.

./custom/modules/<module>/views/view.newview.php

  <?php

require_once 'include/MVC/View/views/view.detail.php' ;

class <module>ViewMyView extends ViewDetail
{
    function display()
    {
        echo 'This is my new view<br>';
    }
}

Overriding Views

The following section will demonstrate how to extend and override a view. When overriding existing actions and views, you won't need to make any changes to the controller. This approach will be very similar for any view you may choose to modify. If the module you are extending the view for does not contain an existing view in its modules views directory ( ./modules/<module>/views/ ), you will need to extend the views base class. Otherwise, you will extend the view class found within the file.

In the case of a detail view, you would check for the file ./modules/<module>/views/view.detail.php. If this file does not exist, you will create ./custom/modules/<module>/views/view.detail.php and extend the base ViewDetail class with the name <module>ViewDetail.

./custom/modules/<module>/views/view.detail.php

  <?php

require_once('include/MVC/View/views/view.detail.php');

class <module>ViewDetail extends ViewDetail
{
    function display()
    {
        echo 'This is my addition to the DetailView<br>';

        //call parent display method
        parent::display();
    }
}

If ./modules/<module>/views/view.detail.php does exist, you would create ./custom/modules/<module>/views/view.detail.php and extend the base <module>ViewDetail class with the name Custom<module>ViewDetail.

./custom/modules/<module>/views/view.detail.php

  <?php

require_once('modules/<module>/views/view.detail.php');

class Custom<module>ViewDetail extends <module>ViewDetail
{
    function display()
    {
        echo 'This is my addition to the DetailView<br>';

        //call parent display method
        parent::display();
    }
}

Display Options for Views

The Sugar MVC provides developers with granular control over how the screen looks when a view is rendered. Each view can have a config file associated with it. In the case of an edit view, the developer would create the file ./customs/modules/<module>/views/view.edit.config.php . When the edit view 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>/views/view.<view>.config.php
• ./modules/<module>/views/view.<view>.config.php
• ./custom/include/MVC/View/views/view.<view>.config.php
• ./include/MVC/View/views/view.<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 us 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. 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 none of the options will be displayed.