Let the platform do the work

Views

Overview

Views are component plugins that render data from a context. View components may contain field components and are typically made up of a controller JavaScript file (.js) and at least one Handlebars template (.hbs).

Load Order Hierarchy Diagram

The view components are loaded in the following manner:

rest/v11/doc_PagesFiles/4d8c0cdf-d9ec-0cb4-d1bd-550286480878/file/uploadfile?force_download=0&platform=base

Note: The Sugar application's client type is "base". For more information on the various client types, please refer to the User Interface page.

Components

Views are made up of a controller and a Handlebar template.

Controller

The view's controller is what controls the view in how data is loaded, formatted, and manipulated. The controller is the JavaScript file named after the view. A controller file can be found in any of the directories shown in the hierarchy diagram above. In the example of the record view, the main controller file is located in ./clients/base/views/record/record.js and any modules extending this controller will have a file located in ./modules/<module>/clients/base/views/record/record.js.  

Handlebar Template

The views template is built on Handlebars and is what adds the display markup for the data. The template is typically named after the view or an action in the view. In the example of the record view, the main template us located in ./clients/base/views/record/record.hbs. This template will take the data fetched from the REST API to render the display for the user. More information on templates can be found in the Handlebars section.

Extending Views

When working with module views, it is important to understand the difference between overriding and extending a view. Overriding is essentially creating or copying a view to be used by your application that is not extending its parent. By default, some module views already extend the core ./clients/base/views/record/record.js controller. An example of this is the accounts RecordView

./modules/Accounts/clients/base/views/record/record.js

  ({
    extendsFrom: 'RecordView',

    /**
     * @inheritdoc
     */
    initialize: function(options) {
        this.plugins = _.union(this.plugins || [], ['HistoricalSummary']);
        this._super('initialize', [options]);
    }
})

As you can see, this view has the property: extendsFrom: 'RecordView'. This property tells Sidecar that the view is going to extend its parent RecordView. In addition to this, you can see that the initialize method is also calling this._super('initialize', [options]);. Calling this._super tells Sidecar to execute the parent function. The major benefit of doing this is that any updates to ./clients/base/views/record/record.js will be reflected for the module without any modifications being made to ./modules/Accounts/clients/base/views/record/record.js. You should note that when using extendsFrom, the parent views are called similarly to the load hierarchy: 

 rest/v11/doc_PagesFiles/3b32e41d-4675-d2c5-ad1b-55029298f01f/file/uploadfile?force_download=0&platform=base

Create View and Record View Inheritance

The diagram below demonstrates the inheritance of the create and record views for the Quotes module. This inheritance structure is the same for stock and custom modules alike. 

Inheritance In Between Record and Create View

Basic View Example

A simple view for beginners is the access-denied view. The view is located in ./clients/base/views/access-denied/ and is what handles the display for restricted access. The sections below will outline the various files that render this view.

Controller

The access-denied.js, shown below, controls the manipulation actions of the view.

./clients/base/views/access-denied/access-denied.js

  ({
    className: 'access-denied tcenter',
    cubeOptions: {spin: false},
    events: {
        'click .sugar-cube': 'spinCube'
    },

    spinCube: function() {
        this.cubeOptions.spin = !this.cubeOptions.spin;
        this.render();
    }
})

Attributes

Attribute Description
className The CSS class to apply to the view.
cubeOptions A set of options that are passed to the spinCube function when called.
events A list of the view events. This view executes the spinCube function when the sugar cube is clicked.
spinCube Function to control the start and stop of the cube spinning.

Handlebar Template

The access-denied.hbs file defines the format of the views content. As this view is used for restricting access, it displays a message to the user describing the restriction.

./clients/base/views/access-denied/access-denied.hbs

  <div class="error-message">
    <h1>{{str 'ERR_NO_VIEW_ACCESS_TITLE'}}</h1>
    <p>{{str 'ERR_NO_VIEW_ACCESS_REASON'}}</p>
    <p>{{str 'ERR_NO_VIEW_ACCESS_ACTION'}}</p>
</div>

{{{subFieldTemplate 'sugar-cube' 'detail' cubeOptions}}}

Helpers

Name Description
str Handlebars helper to render the label string
subFieldTemplate Handlebars helper to render the cube content

Cookbook Examples

When working with views, you may find the follow cookbook examples helpful: