Sidecar API Reference

Class: View/View

View/View

new View/View()

Base View class. Use View.ViewManager to create instances of views.

Extends

Members

action :string

Name of the action (optional).

Used in acl checks for user permissions. By default, set to the view name.

Type:
  • string

collection :Data/BeanCollection

Reference to the collection this component is bound to.

Type:
Inherited From:

context :Core/Context

Reference to the context (required).

Type:
Inherited From:

dataView :string

The view name that contains the list of fields to use when fetching the model/collection from the server.

List, record or detail views might have too many fields defined in the metadata. This property avoids having to list all these fields in the request params.

Type:
  • string

fallbackFieldTemplate :string

A template to use for view fields if a field does not have a template defined for its parent view. Defaults to "default".

For example, if you have a subview and don't want to define subview template for all field types, you may choose to use existing templates like detail if your subview is in fact a detail view.

Type:
  • string

fields :Object

Dictionary of field widgets.

  • keys: field IDs (sfuuid)
  • values: instances of View/Field
Type:
  • Object

layout :View/Layout

Reference to the parent layout instance.

Type:

meta :Object

Component metadata (optional).

Type:
  • Object
Inherited From:

model :Data/Bean

Reference to the model this component is bound to.

Type:
Inherited From:

module :string

Module name (optional).

Type:
  • string
Inherited From:

modulePlural :string

Pluralized i18n-ed module name.

Type:
  • string

moduleSingular :string

Singular i18n-ed module name.

Type:
  • string

name :string

Name of the view.

Type:
  • string

nestedFields :Object

Fields part of this view that are already managed by another lifecycle handler.

Type:
  • Object

options :Object

Backbone view options.

Type:
  • Object
Inherited From:
Deprecated:
  • Deprecated since 7.8.0 since this is no longer supported by Backbone.

primary :boolean

Flag indicating whether a view is primary or not.

If the primary view is not rendered due to the access control, a warning message will be displayed.

Type:
  • boolean

template :function

The template for this view.

Type:
  • function

tplName :string|null

The name of the template that is loaded. This is a public read-only property. This property should not be modified directly.

Type:
  • string | null

type :string

View type.

Type:
  • string

Methods

<static> _hide()

<static> _show()

<static> closestComponent()

<protected> _dispose()

Disposes a view.

This method disposes view fields and calls the View/Component#_dispose method of the base class.

Overrides:

<protected> _disposeFields()

Disposes all the fields.

<protected> _hide()

Override this method to provide custom show logic.

Inherited From:

<protected> _render()

Renders a view onto the page.

The method first renders this view by calling View/View#_renderHtml and then for each field invokes View/View#_renderField.

NOTE: Do not override this method, otherwise you will lose ACL check. Consider overriding View/View#_renderHtml instead.

Overrides:
Returns:

The instance of this view.

Type
View/View

<protected> _renderField(field, $fieldEl)

Sets field's view element and invokes render on the given field.

Parameters:
Name Type Description
field View/Field

The field to render.
$fieldEl jQuery

The field placeholder.

<protected> _renderFields()

Renders all the fields.

<protected> _renderHtml( [ctx] [, options])

Renders a view onto the page.

This method uses ctx parameter as the context for the view's Handlebars View/View#template and view's options.templateOptions property as template options.

If no ctx parameter is specified, this is passed as the context for the template. If no options parameter is specified, this.options.templateOptions is used.

You can override this method if you have custom rendering logic and don't use Handlebars templating or if you need to pass a different context object for the template.

Note the following use of ViewManager.View.extend is deprecated in favor of putting these controllers in the sugarcrm/clients/ directory. Using that idiom, the metadata manager will declare these components and take care of namespacing by platform for you (so MyCustomView will be stored internally as MyappMyCustomView). If you do choose to use the following idiom please be forewarned that you will lose any namespacing benefits and possibly encounter naming collisions!

Example:

// Note that using the following technique of defining custom views
// directly on the ViewManager.views object can result in naming
// collisions unless you ensure your name is unique. See note above.
ViewManager.views.CustomView = ViewManager.View.extend({
   _renderHtml: function() {
      var ctx = {
        // Your custom context for this view template
      };
      ViewManager.View.prototype._renderHtml.call(this, ctx);
   }
});

// Or totally different logic that doesn't use this.template
ViewManager.views.AnotherCustomView = ViewManager.View.extend({
   _renderHtml: function() {
      // Never do this :)
      return "<div>Hello, world!</div>";
   }
});

This method uses this view's View/View#template property to render itself.

Parameters:
Name Type Argument Description
ctx Core/Context <optional>

Template context.
options Object <optional>

Template options.

{
   helpers: helpers,
   partials: partials,
   data: data
}
// See Handlebars.js documentation for details.

<protected> _show()

Override this method to provide custom show logic.

Inherited From:

<protected> _super(method [, args])

Retrieves and invokes parent prototype functions.

Requires a method parameter to function. The method called should be named the same as the function being called from.

Examples:

  • Good:
({
    initialize: function(options) {
        // extend the base meta with some custom meta
        options.meta = _.extend({}, myMeta, options.meta || {});
        // Only call parent initialize from initialize
        this._super('initialize', [options]);
        this.buildFoo(options);
    }
});
  • Bad:
({
    initialize: function(options) {
        // extend the base meta with some custom meta
        options.meta = _.extend({}, myMeta, options.meta || {});
        // Calling a function like buildFoo from initialize is incorrect. Should call directly on this
        this._super('buildFoo',[options]);
    }
});
Parameters:
Name Type Argument Description
method string

The name of the method to call (e.g. initialize, _renderHtml).
args Array <optional>

Arguments to pass to the parent method.
Inherited From:
Returns:

The result of invoking the parent method.

Type
*

<protected> _wrapInitialize(options)

Wraps the initialize method to delegate the events on the element, after it initializes.

Parameters:
Name Type Description
options Object

The Backbone.View initialization options.
Inherited From:

before(name, callback [, context])

Adds a callback/hook to be fired before an action is taken. If that callback returns false, the action should not be taken.

The following example binds a callback function and passes the scope from the view component to use in that callback:

model.before('save', this.doSomethingBeforeSave, this);

Multiple space-separated event names can be bound to a single callback:

view.before('save dispose', this.callback, this);

This method also supports an event map syntax, as an alternative to positional arguments:

this.before({
    render: this.doSomethingBeforeRender,
    dispose: this.doSomethingBeforeDispose,
});
Parameters:
Name Type Argument Description
name string | Object

Event(s) to trigger before. Accepts multiple space-separated event names or an event map.
callback function

Function to be called.
context Object <optional>

Value to be assigned to this when the callback is fired.
Inherited From:
Mixes In:
Returns:

Instance of this class.

Type
Object

<abstract> bindDataChange()

Binds data changes to this component.

Inherited From:

closestComponent(name)

Traverses upwards from the current component to find the first component that matches the name.

The default implementation does nothing. See View/Layout#closestComponent, View/View#closestComponent and View/Field#closestComponent methods.

Parameters:
Name Type Description
name string

The name of the component to find.
Inherited From:
Returns:

The component or undefined if not found.

Type
View/Component

constructor(options)

Constructor for sidecar components, currently used to define the order of event delegation on this component's events, after Backbone changed the order in which events are delegated from 0.9.10 to 1.2.0. Also temporarily defines #options on the component, as Backbone no longer does this by default.

Parameters:
Name Type Description
options Object

The Backbone.View initialization options.
Inherited From:
Returns:

The created Backbone.View.

Type
Backbone.View

delegateEvents()

Proxies the parent method on Backbone.View, but only called after this view instance initializes.

Inherited From:
Returns:

Instance of this component.

Type
View/Component

dispose()

Disposes a component.

Once the component gets disposed it can not be rendered. Do not override this method. Instead override View/Component#_dispose method if you need custom disposal logic.

Inherited From:

getField(name [, model])

Returns a field by name.

Parameters:
Name Type Argument Description
name string

Field name.
model Data/Bean <optional>

Model to find the field for.
Returns:

Instance of the field widget.

Type
View/Field

getFieldMeta(field [, includeChild])

Gets a field's metadata.

Parameters:
Name Type Argument Default Description
field string

Field name.
includeChild boolean <optional>
 false

If true, check if this is a child field.
Returns:

Field metadata.

Type
Object

getFieldNames( [module])

Extracts the field names from the metadata for directly related views/panels.

Parameters:
Name Type Argument Description
module string <optional>

Module name. Defaults to the Context module.
Returns:

List of fields used on this view.

Type
Array

getFields( [module] [, model])

Gets a hash of fields that are currently displayed on this view.

The hash has field names as keys and field definitions as values.

Parameters:
Name Type Argument Description
module string <optional>

Module name.
model Data/Bean <optional>

Model to match fields against. Only fields that correspond with the given model will be returned.
Returns:

The currently displayed fields.

Type
Object

getPlaceholder()

Gets the HTML placeholder for this component.

Inherited From:
Returns:

HTML placeholder to be used in a Handlebars template.

Type
Handlebars.SafeString

hide()

Pass through function to jQuery's hide to hide view.

Inherited From:
Returns:

false if the BeforeEvent for hide fails; undefined otherwise.

Type
boolean | undefined

initialize(options)

Initializes this component.

Parameters:
Name Type Description
options Object

The Backbone.View initialization options.

Properties
Name Type Argument Description
context Core/Context

Reference to the context.
meta Object <optional>

Component metadata.
module string <optional>

Module name.
model Data/Bean <optional>

Reference to the model this component is bound to.
collection Data/BeanCollection <optional>

Reference to the collection this component is bound to.
Inherited From:

isVisible()

Checks if this component is visible on the page.

Inherited From:
Returns:

true if this component is visible on the page; false otherwise.

Type
boolean

loadData( [options])

Fetches data for view's model or collection.

This method calls view's context Core/Context#loadData method.

Override this method to provide custom fetch algorithm.

Parameters:
Name Type Argument Description
options Object <optional>

Options that are passed to collection/model's fetch method.
Overrides:

offBefore( [name] [, callback] [, context])

Removes a previously-bound callback function from a before event.

If no context is given, all of the versions of the callback with different contexts will be removed:

this.offBefore('render', this.onRenderBefore);

If no callback is given, all callbacks for the before event will be removed:

this.offBefore('render');

If no event is specified, all callbacks for all before events will be removed from the object:

this.offBefore();
Parameters:
Name Type Argument Description
name string <optional>

Event(s) to remove the listeners for.
callback function <optional>

Callback to remove specifically for a given event.
context Object <optional>

Context to use when determining which callback to remove.
Inherited From:
Mixes In:
Returns:

Instance of this class.

Type
Object

render()

Renders this component.

IMPORTANT: Do not override this method. Instead, override View/Component#_render to provide render logic.

Inherited From:
Returns:

Instance of this component.

Type
View/Component

setFieldMeta(field, meta)

Sets a field's metadata.

Parameters:
Name Type Description
field string

Field name.
meta Object

Field metadata

setTemplateOption(key, option)

Sets template option.

If the given option already exists it is augmented by the value of the given option parameter.

See the Handlebars.js documentation for details.

Parameters:
Name Type Description
key string

Option key.
option Object

Option value.
Inherited From:

show()

Pass through function to jQuery's show to show view.

Inherited From:
Returns:

false if the BeforeEvent for show fails; undefined otherwise.

Type
boolean | undefined

toString()

Gets a string representation of this view.

Overrides:
Returns:

String representation of this view.

Type
string

triggerBefore(name)

Triggers the before callback for the given event name or list of events.

The following example triggers the callback bound to the before save event given:

this.triggerBefore('save');

Multiple events can be triggered as well:

this.triggerBefore('save render dispose');

Custom arguments (e.g. a, b, c) can be passed to the callback:

this.triggerBefore('save', a, b, c);
Parameters:
Name Type Description
name string

The before event(s) to trigger.
Inherited From:
Mixes In:
Returns:

Returns true if the event should be triggered, false otherwise.

Type
boolean

unbind()

Removes all event callbacks registered within this component and undelegates Backbone events.

Override this method to provide custom logic.

Inherited From:

unbindData()

Removes this component's event handlers from model and collection.

Performs the opposite of what View/Component#bindDataChange method does.

Override this method to provide custom logic.

Inherited From:

updateVisibleState(visible)

Updates this component's visibility state.

Note: This does not show/hide the component. Please use View/Component#show and View/Component#hide to do this.

Parameters:
Name Type Description
visible boolean

Visibility state of this component.
Inherited From: