Sidecar API Reference Class: View/Field

new View/Field()

SugarField widget. A field widget is a low level field widget. Some examples of fields are text boxes, date pickers, drop down menus.

Creating a SugarField

SugarCRM allows for customized "fields" which are visual representations of a type of data (e.g. url would be displayed as a hyperlink).

Anatomy of a SugarField

Field files reside in the sugarcrm/clients/base/fields/{field_type} folder.

Inside the {field_type} directory is a set of files that define templates for different views and field controller. A typical directory structure will look like the following:

clients
|- base
   |- bool
      |- bool.js
      |- detail.hbs
      |- edit.hbs
      |- list.hbs
   |- int
      ...
   |- text
      ...
|- portal
   |- portal specific overrides
|- mobile
   |- mobile specific overrides

[sugarFieldType].js files are optional. Sometimes a SugarField needs to do more than just display a simple input element, other times input elements need additional data such as drop down menu choices. To support advanced functionality, just add your additional controller logic to [sugarFieldType].js javascript file where sugarFieldType is the type of the SugarField. Example for bool.js controller:

const ViewManager = require('view/view-manager');
({
   events: {
        handler: function() {
            // Actions
        }
   },

   initialize: function(options) {
      ViewManager.Field.prototype.initialize(options);
      // Your constructor code here follows...
   },

   unformat: function(value) {
       value = this.el.children[0].children[1].checked ? '1' : '0';
       return value;
   },

   format: function(value) {
       value = (value == '1') ? true : false;
       return value;
   }
})

.hbs files contain your templates corresponding to the type of View/View the field is to be displayed on. Sugar uses Handlebars.js as its client side template of choice. At this time no other templating engines are supported. Sample:

<span name="{{name}}">{{value}}</span>

These files will be used by the metadata manager to generate metadata for your SugarFields and pass them onto the Sugar JavaScript client.

Extends

View/Component

Members

<static> viewFallbackMap :Object

Defines fallback rules for ACL checking.

For example, if a user doesn't have edit permission for the given field the template falls back to detail view template.

Type:

Object

action :string

Action name.

The action the field is rendered for. Usually, the action name equals to View/Field#tplName.

Type:

string

collection :Data/BeanCollection

Reference to the collection this component is bound to.

Type:

Data/BeanCollection

Inherited From:

View/Component#collection

context :Core/Context

Reference to the context (required).

Type:

Core/Context

Inherited From:

View/Component#context

def :Object

Field metadata definition (fieldDefs + viewdefs).

Viewdef are copied over vardef.

Type:

Object

Deprecated:

<readonly> dir :string|undefined

The direction of the field. The default value undefined means that the field would use the inherited direction from the DOM.

Do not override this property directly; override View/Field#direction instead.

Type:

string | undefined

direction :function|string|undefined

Override this property with a specific direction string if the field has a set direction that it always follows.

Override this property with a function if logic is needed to determine the direction of the field. The function should return either a string indicating the direction of the field or undefined. This function is only called after the value is set so that we can base the direction on the value.

The default value undefined means that the field would use the inherited direction from the DOM.

Example using a function:

direction: function() {
    return this.isRTL ? 'rtl' : 'ltr';
}

Type:

function | string | undefined

fieldDefs :Object

Field definitions (vardefs).

Field definitions are properties that define the field and its internal behavior.

Type:

Object

fieldTag :string

HTML tag of the field.

Type:

string

label :string

i18n-ed field label.

Type:

string

meta :Object

Component metadata (optional).

Type:

Object

Inherited From:

View/Component#meta

model :Data/Bean

Reference to the model this component is bound to.

Type:

Data/Bean

Inherited From:

View/Component#model

module :string

Module name (optional).

Type:

string

Inherited From:

View/Component#module

name :string

Field name.

Type:

string

options :Object

Backbone view options.

Type:

Object

Inherited From:

View/Component#options

Deprecated:

Deprecated since 7.8.0 since this is no longer supported by Backbone.

sfId :number

ID of the field (autogenerated).

Type:

number

template :function

Compiled template.

Type:

function

tplName :string

Template (view) name.

The view name can be different from the one the field belongs to. The template is selected based on ACLs. It may also be overridden by field's metadata definition.

Type:

string

type :string

Widget type (text, bool, int, etc.).

Type:

string

value :string

Model property value.

Type:

string

view :View/View

Reference to the view this field is attached to.

Type:

View/View

viewDefs :Object

View definitions for the field (doesn't include vardefs).

The view definitions are the properties used for field rendering. Example: A link property can specify if the field should be displayed as a link.

Type:

Object

Properties:

Name	Type	Description
`defs`	Object	A hash of properties that will override the field definitions (vardefs).

Methods

<static> _hide()

<static> _show()

<protected> _dispose()

Disposes a field.

Calls View/Field#unbindDom and View/Component#_dispose method of the base class.

Overrides:

View/Component#_dispose

<protected> _getFallbackTemplate(viewName)

Gets the fallback template for this field's view.

Parameters:

Name	Type	Description
`viewName`	string	Name of the view.

Returns:

If disabled and viewName is 'disabled', then 'edit'. If not, then either this.view.fallbackFieldTemplate or 'detail'.

Type: string

<protected> _hide()

Override this method to provide custom show logic.

Inherited From:

View/Component#_hide

<protected> _render()

Renders a field widget.

This method checks ACLs to choose the correct template. Once the template is rendered, DOM changes are bound to the model.

Overrides:

View/Component#_render

Returns:

The instance of this field.

Type: View/Field

<protected> _resetAction()

Sets this field's action to undefined.

<protected> _show()

Override this method to provide custom show logic.

Inherited From:

View/Component#_show

<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:

View/Component#_super

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:

View/Component#_wrapInitialize

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:

View/Component#before

Mixes In:

Core/BeforeEvent.before

Returns:

Instance of this class.

Type: Object

bindDataChange()

Binds model changes to this field.

The default implementation makes sure this field gets re-rendered whenever the corresponding model attribute changes.

Overrides:

View/Component#bindDataChange

bindDomChange()

Binds DOM changes to a model.

The default implementation of this method binds value changes of View/Field#fieldTag element to model's Backbone.Model#set method. Override this method if you need custom binding.

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:

View/Component#closestComponent

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:

View/Component#constructor

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:

View/Component#delegateEvents

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:

View/Component#dispose

equals(other)

Compares formatted values for equality.

Parameters:

Name	Type	Description
`other`	View/Field	Other field component.

Returns:

It returns true for equal value.

Type: boolean

format(value)

Formats the value to be used in handlebars template and displayed on screen.

The default implementation returns value without modifying it. Override this method to provide custom formatting in field controller ([type].js file).

Parameters:

Name	Type	Description
`value`	Array \| Object \| string \| number \| boolean	The value to format.

Returns:

Formatted value.

Type: Array | Object | string | number | boolean

getFieldElement()

Gets the corresponding field DOM element.

This method will return the placeholder element. Override this method in the subclass to point the specified field element.

Returns:

DOM Element

Type: Object

getFormattedValue()

Returns the value of this field in the associated model.

If you need to override the formatted value please override View/Field#format.

Returns:

The formatted data as provided by View/Field#format.

Type: Array | Object | string | number | boolean

getPlaceholder()

Gets the HTML placeholder for a field.

Overrides:

View/Component#getPlaceholder

Returns:

HTML placeholder for the field as Handlebars safe string.

Type: Handlebars.SafeString

handleAclChange()

Handler for when an ACL changes at the field-level.

handleValidationError(errors)

Handles validation errors.

The default implementation does nothing. Override this method to provide custom display logic.

ViewManager.Field = ViewManager.Field.extend({
    handleValidationError: function(errors) {
        // Your custom logic goes here
    }
});

Parameters:

Name	Type	Description
`errors`	Object	hash of validation errors

hasChanged()

Checks to see if the field's value has been changed from the saved model This is not the same as Backbone.Model#hasChanged which checks if the model has changed from the last time it was set whereas this function checks if what is currently in the input field is the same as what is synced on the model

Returns:

true if the value is different, false if field is synced with the saved model

Type: boolean

hide()

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

Inherited From:

View/Component#hide

Returns:

false if the BeforeEvent for hide fails; undefined otherwise.

Type: boolean | undefined

initialize(options)

Initializes this view.

Parameters:

Name	Type	Description
`options`	Object	The `Backbone.View` initialization options.

Overrides:

View/Component#initialize

initialize(options)

Initializes this view.

Parameters:

Name	Type	Description
`options`	Object	Backbone view options.

Overrides:

View/Component#initialize

isDisabled()

Checks if this field is disabled.

Returns:

true if this field is disabled, false otherwise.

Type: boolean

isVisible()

Checks if this component is visible on the page.

Inherited From:

View/Component#isVisible

Returns:

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

Type: boolean

loadData()

Fetches data for layout's model or collection.

The default implementation does nothing. See View/Layout#loadData and View/View#loadData methods.

Inherited From:

View/Component#loadData

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:

View/Component#offBefore

Mixes In:

Core/BeforeEvent.offBefore

Returns:

Instance of this class.

Type: Object

removeValidationErrors()

Removes the validation error properties on the field that were set by #handleValidationError.

The default implementation does nothing.

Override this method to provide custom logic:

ViewManager.Field = ViewManager.Field.extend({
    removeValidationErrors: function(errors) {
        // Your custom logic goes here
    }
});

render()

Renders this component.

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

Inherited From:

View/Component#render

Returns:

Instance of this component.

Type: View/Component

setDisabled(disable [, options])

Disables edit mode by switching the element as detail mode.

Parameters:

Name Type Argument Default Description

disable

boolean

true or undefined to disable the edit mode otherwise, it will restore back to the previous mode.

options

Object

{}

A hash of options.

Properties

Name	Type	Argument	Description
`trigger`	boolean	<optional>	`true` to trigger the `field:disabled` event in the context. The event passes 2 arguments: the field name and the `disable` boolean.

setMode(name)

Set action name of this field. This switches action name as well as the template reference.

Parameters:

Name	Type	Description
`name`	string	Action name.

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:

View/Component#setTemplateOption

setViewName(view)

Set view name of this field. This only switches the template reference.

Parameters:

Name	Type	Description
`view`	string	View name.

show()

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

Inherited From:

View/Component#show

Returns:

false if the BeforeEvent for show fails; undefined otherwise.

Type: boolean | undefined

toString()

Gets a string representation of this field.

Overrides:

View/Component#toString

Returns:

String representation of this field.

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:

View/Component#triggerBefore

Mixes In:

Core/BeforeEvent.triggerBefore

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:

View/Component#unbind

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:

View/Component#unbindData

unbindDom()

Unbinds DOM changes from this field's element.

This method performs the opposite of what View/Field#bindDomChange method does. Override this method if you need custom logic.

unformat(value)

Unformats the value for storing in a model. This should do the inverse of #format.

The default implementation returns value without modifying it. Override this method to provide custom unformatting in field controller ([type].js file).

Parameters:

Name	Type	Description
`value`	string	The value to unformat.

Returns:

Unformatted value.

Type: Array | Object | string | number | boolean

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:

View/Component#updateVisibleState