View/Field

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

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.

Inherited From:

# context :Core/Context

Reference to the context (required).

Type:
Inherited From:

# def :Object

Field metadata definition (fieldDefs + viewdefs).

Viewdef are copied over vardef.

Type:
  • Object
Deprecated:
  • Yes

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

# model :Data/Bean

Reference to the model this component is bound to.

Type:
Inherited From:

# module :string

Module name (optional).

Type:
  • string
Inherited From:

# name :string

Field name.

Type:
  • string

# options :Object

Backbone view options.

Type:
  • Object
Inherited From:
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:

# 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.

# (protected) _getFallbackTemplate(viewName) → {string}

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:

# (protected) _render() → {View/Field}

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.

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:

# (protected) _super(method, argsopt) → {*}

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 Attributes 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.

# before(name, callback, contextopt) → {Object}

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

# 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) → {View/Component}

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.

Returns:

The component or undefined if not found.

Type
View/Component

# constructor(options) → {Backbone.View}

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() → {View/Component}

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

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:

# equals(other) → {boolean}

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) → {Array|Object|string|number|boolean}

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() → {Object}

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() → {Array|Object|string|number|boolean}

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() → {Handlebars.SafeString}

Gets the HTML placeholder for a field.

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() → {boolean}

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() → {boolean|undefined}

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 view.

Parameters:
Name Type Description
options Object

The Backbone.View initialization options.

# initialize(options)

Initializes this view.

Parameters:
Name Type Description
options Object

Backbone view options.

# isDisabled() → {boolean}

Checks if this field is disabled.

Returns:

true if this field is disabled, false otherwise.

Type
boolean

# isVisible() → {boolean}

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()

Fetches data for layout's model or collection.

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

Inherited From:

# offBefore(nameopt, callbackopt, contextopt) → {Object}

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 Attributes 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:
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() → {View/Component}

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

# setDisabled(disable, optionsopt)

Disables edit mode by switching the element as detail mode.

Parameters:
Name Type Attributes Default Description
disable boolean

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

options Object <optional>
{}

A hash of options.

Properties
Name Type Attributes 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.

# setViewName(view)

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

Parameters:
Name Type Description
view string

View name.

# show() → {boolean|undefined}

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() → {string}

Gets a string representation of this field.

Returns:

String representation of this field.

Type
string

# triggerBefore(name) → {boolean}

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.

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:

# 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) → {Array|Object|string|number|boolean}

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.