#
new View/Layout()
The Layout Object is a definition of views and their placement on a certain
'page'.
Use Sidecar/View/ViewManager to
create instances of layouts.
A Quick Guide for Creating a Layout Definition
Creating Layouts is easy. All it takes is adding the appropriate metadata
file. Let's create a layout called SampleLayout
.
The Layout File and Directory Structure
Layouts are located in the modules/MODULE/metadata/layouts
folder. Add
a file called SampleLayout.php
in the folder and it should be picked
up in the next metadata sync call.
The Metadata
$viewdefs['MODULE']['PLATFORM (portal / mobile / base)']['layout']['samplelayout'] = array(
'type' => 'columns',
'components' => array(
0 => array(
'layout' => array(
'type' => 'column',
'components' => array(
array(
'view' => 'list',
),
array(
'view' => 'list',
'context' => array(
'module' => 'Leads',
),
),
),
),
),
);
As you can see we are defining a column style layout with two subcomponents: A normal list view
of the MODULE, and also a list view of Leads.
Accessing the New Layout
The last step is to add a route in the Router to display the new layout. // TODO: Custom routes?
Extends
Members
Holds the components metadata in case if it is a lazy loaded
layout. This property should be used to to initialize
components manually.
Reference to the collection this component is bound to.
Reference to the context (required).
#
label :string
Reference to the parent layout instance.
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.
Methods
#
(protected) _addComponentsFromDef(componentsopt, contextopt, moduleopt)
Parameters:
Name |
Type |
Attributes |
Default |
Description |
components |
Array
|
<optional>
|
[]
|
The components to be created. |
context |
Object
|
<optional>
|
|
Context to pass to the new components. |
module |
string
|
<optional>
|
|
Module to create the components from. |
#
(protected) _dispose()
Disposes a layout.
Disposes each of this layout's components and calls the
View/Component#_dispose method of the base class.
#
(protected) _hide()
Override this method to provide custom show logic.
#
(protected) _placeComponent(component)
Places layout component in the DOM.
Default implementation just appends all the components to itself.
Override this method to support custom placement of components.
#
(protected) _render() → {View/Layout}
Renders all the components.
#
(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. |
#
addComponent(component, def)
Adds a component to this layout.
Parameters:
Name |
Type |
Description |
component |
View/Layout
|
View/View
|
Component (view or layout) to add. |
def |
Object
|
Metadata definition. |
#
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. |
#
(abstract) bindDataChange()
Binds data changes to this component.
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
#
createComponentFromDef(def, context, module) → {View/Layout|View/View}
Creates a component based on the given metadata, context and module.
Parameters:
Name |
Type |
Description |
def |
Object
|
Metadata defining this component. |
context |
Core/Context
|
Default context to pass to the new
component. (Will be overridden by the context in 'def' param, if
defined). |
module |
string
|
The module to pass to the component.
(Will be overridden by the context's module in 'def' param, if
defined). |
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.
Gets a component by name.
Parameters:
Name |
Type |
Description |
name |
string
|
Component name. |
#
getFieldNames(moduleopt) → {Array}
Gets a list of all fields used on this layout and its sub layouts/views.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
module |
string
|
<optional>
|
this.module
|
Module name. |
Returns:
The list of fields used by this layout.
-
Type
-
Array
#
getFields(moduleopt) → {Object}
Gets a hash of fields that are currently displayed on this layout.
The hash has field names as keys and field definitions as values.
Parameters:
Name |
Type |
Attributes |
Description |
module |
string
|
<optional>
|
Module name. |
Returns:
The currently displayed fields.
-
Type
-
Object
#
getPlaceholder() → {Handlebars.SafeString}
Gets the HTML placeholder for this component.
Returns:
HTML placeholder to be used in a
Handlebars template.
-
Type
-
Handlebars.SafeString
#
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
#
initComponents(componentsopt, contextopt, moduleopt) → {Array}
Creates subcomponents in the layout and appends them to the layout's
#_components. It recursively initializes all components
within the specified subcomponents.
Calls View/Layout#_addComponentsFromDef to help add components.
Triggers init
on this layout once all subcomponent initializes.
Immediate subcomponent will default to the passed in context and
module.
Subsequent subcomponents will default to their parents' context and
module.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
components |
Array
|
<optional>
|
this.meta.components
|
The definitions of
the subcomponents. |
context |
Object
|
<optional>
|
|
Context to pass to the new components. |
module |
string
|
<optional>
|
|
Module to create the components from. |
#
initialize(options)
Initializes this component.
Parameters:
Name |
Type |
Description |
options |
Object
|
The Backbone.View initialization options.
Properties
Name |
Type |
Attributes |
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. |
|
#
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(optionsopt)
Fetches data for layout's model or collection.
The default implementation first calls the Core/Context#loadData
method for the layout's context and then iterates through the components
and calls their View/Component#loadData method, setting their
contexts' fields
property beforehand.
Override this method to provide a custom fetch algorithm.
Parameters:
Name |
Type |
Attributes |
Description |
options |
Object
|
<optional>
|
Options that are passed to
collection/model's fetch method. |
#
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. |
#
placeComponentsFromTemplate()
Move components created in templates to their appropriate placeholders.
#
removeComponent(component)
Removes a component from this layout.
Parameters:
Name |
Type |
Description |
component |
View/Layout
|
View/View
|
number
|
The layout or view to
remove. If given as a number, remove the component at that index. |
Renders this component.
IMPORTANT: Do not override this method.
Instead, override View/Component#_render to provide render logic.
#
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. |
#
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 layout.
Returns:
String representation of this layout.
-
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.
#
updateVisibleState(visible)
Parameters:
Name |
Type |
Description |
visible |
boolean
|
Visibility state of this component. |