#
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.
#
action :string
Action name.
The action the field is rendered for. Usually, the action name
equals to View/Field#tplName.
Reference to the collection this component is bound to.
Reference to the context (required).
#
def :Object
Field metadata definition (fieldDefs + viewdefs).
Viewdef are copied over vardef.
#
(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.
#
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.
#
fieldTag :string
#
label :string
Component metadata (optional).
Reference to the model this component is bound to.
#
module :string
#
name :string
#
options :Object
- Deprecated:
- Deprecated since 7.8.0 since this is no longer supported
by Backbone.
#
sfId :number
ID of the field (autogenerated).
#
template :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
Widget type (text, bool, int, etc.).
#
value :string
Reference to the view this field is attached to.
#
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.
Properties
Name |
Type |
Description |
defs |
Object
|
A hash of properties that
will override the field definitions (vardefs). |
Methods
#
(static) _hide()
#
(static) _show()
#
(protected) _dispose()
#
(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.
#
(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.
#
(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:
({
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);
}
});
({
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. |
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. |
#
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.
Parameters:
Name |
Type |
Description |
name |
string
|
The name of the component to find. |
#
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. |
Returns:
The created Backbone.View
.
-
Type
-
Backbone.View
Proxies the parent method on Backbone.View
, but only called after
this view instance initializes.
#
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.
#
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
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:
-
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 the value of this field in the associated model.
If you need to override the formatted value please override
View/Field#format.
Returns:
-
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.
Returns:
false
if the BeforeEvent for hide
fails;
undefined
otherwise.
-
Type
-
boolean
|
undefined
#
initialize(options)
Parameters:
Name |
Type |
Description |
options |
Object
|
The Backbone.View initialization options. |
#
initialize(options)
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.
Returns:
true
if this component is visible on the page;
false
otherwise.
-
Type
-
boolean
#
loadData()
#
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. |
#
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
}
});
Renders this component.
IMPORTANT: Do not override this method.
Instead, override View/Component#_render to provide render logic.
#
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.
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.
#
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.
#
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.
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:
-
Type
-
Array
|
Object
|
string
|
number
|
boolean
#
updateVisibleState(visible)
Parameters:
Name |
Type |
Description |
visible |
boolean
|
Visibility state of this component. |