#
new App(optsopt) → {App}
Constructor class for the main framework app.
SUGAR.App
contains the core instance of the app. All related modules
can be found within the SUGAR
namespace.
An uninitialized instance will exist on page load but you will need to
call App#init to initialize your instance.
By default, the app uses body
element and div#content
as root element
and content element respectively.
var app = SUGAR.App.init({
el: '#root',
contentEl: '#content'
});
If you want to initialize an app without initializing its modules,
var app = SUGAR.App.init({el: '#root', silent: true});
Parameters:
Name |
Type |
Attributes |
Description |
opts |
Object
|
<optional>
|
Configuration options. See full list of options
in #init. |
Members
#
$contentEl :jQuery
Content element selector.
The application controller loads layouts
into the content element.
#
$rootEl :jQuery
Base element to use as the root of the app.
#
additionalComponents :Object
Additional components.
These components are created and rendered only once, when the
application starts.
Application specific code is needed for managing the components
after they have been put into DOM by the framework.
#
appId :string
Methods
#
(static) augment(name, obj, initopt)
Augments the application with a module.
Module should be an object with an optional init(app)
function.
The init function is passed the current instance of
the application when app's App#init method gets called.
Use the init
function to perform custom initialization logic during
app initialization.
Parameters:
Name |
Type |
Attributes |
Default |
Description |
name |
string
|
|
|
Name of the module. |
obj |
Object
|
|
|
Module to augment the app with. |
init |
boolean
|
<optional>
|
false
|
Flag indicating if the module should be
initialized immediately. |
#
(static) destroy()
Destroys the instance of the current app.
#
(static) init(optsopt) → {App}
Parameters:
Name |
Type |
Attributes |
Description |
opts |
Object
|
<optional>
|
Initialization options.
Properties
Name |
Type |
Attributes |
Default |
Description |
el |
string
|
<optional>
|
'body'
|
The selector for the
base element to use as the root of the app. |
contentEl |
string
|
<optional>
|
'#content'
|
The selector for the
content element. |
silent |
boolean
|
<optional>
|
false
|
Flag to indicate if modules
should be initialized during application init process. |
defaultErrorHandler |
function
|
<optional>
|
|
Allows you to define a
custom error handler. Defaults to
Core.Error#handleHttpError. |
|
Fires:
- app:init if `opts.event:silent` is not `false`.
- app:sync:error if the public metadata could not be synced.
#
(static) isServerCompatible(data) → {boolean|Object}
Checks if the server version and flavor are compatible.
Parameters:
Name |
Type |
Description |
data |
Object
|
Server information. |
Returns:
true
if server is compatible and an error
object if not.
-
Type
-
boolean
|
Object
#
(static) loadCss(callbackopt)
Loads application CSS.
Will make an HTTP request and retrieve either a list of CSS files to
load, or directly plain text css.
Parameters:
Name |
Type |
Attributes |
Description |
callback |
function
|
<optional>
|
Function called once CSS is loaded. |
#
(static) login(credentials, infoopt, callbacksopt)
Parameters:
Name |
Type |
Attributes |
Description |
credentials |
Object
|
|
User credentials.
Properties
Name |
Type |
Description |
username |
Object
|
User name. |
password |
Object
|
User password. |
|
info |
Object
|
<optional>
|
Extra data to be passed in login request such
as client user agent, etc. |
callbacks |
Object
|
<optional>
|
Object containing the callbacks.
Properties
Name |
Type |
Attributes |
Description |
success |
function
|
<optional>
|
The success callback. |
error |
function
|
<optional>
|
The error callback. |
complete |
function
|
<optional>
|
The complete callback. |
|
Fires:
- app:login:success on successful login.
#
(static) logout(callbacksopt, clearopt, optionsopt) → {SUGAR.HttpRequest}
Parameters:
Name |
Type |
Attributes |
Default |
Description |
callbacks |
Object
|
<optional>
|
|
Object containing the callbacks.
Properties
Name |
Type |
Attributes |
Description |
success |
function
|
<optional>
|
The success callback. |
error |
function
|
<optional>
|
The error callback. |
complete |
function
|
<optional>
|
The complete callback. |
|
clear |
boolean
|
<optional>
|
false
|
Flag indicating if user information
must be deleted from cache. |
options |
Object
|
<optional>
|
{}
|
jQuery/Zepto request options. |
Returns:
-
Type
-
SUGAR.HttpRequest
#
(static) navigate(contextopt, modelopt, actionopt)
Navigates to a new route.
Parameters:
Name |
Type |
Attributes |
Description |
context |
Core/Context
|
<optional>
|
Context object to extract the module
from. |
model |
Data/Bean
|
<optional>
|
Model object to route with. |
action |
string
|
<optional>
|
Action name. |
#
(static) setConfig(configopt)
Updates the config object based on the new metadata.
Reloads modules that depend on the config.
Parameters:
Name |
Type |
Attributes |
Description |
config |
Object
|
<optional>
|
The config object. If not passed, we'll grab
it using Core/MetadataManager#getConfig. |
#
(static) start()
Starts the main execution phase of the application.
#
(static) sync(optionsopt)
Syncs an app.
The events are not fired if the sync happens for public metadata.
Parameters:
Name |
Type |
Attributes |
Description |
options |
Object
|
<optional>
|
Options. See full list of options
you can pass to Core.MetadataManager#sync.
Properties
Name |
Type |
Attributes |
Default |
Description |
callback |
function
|
<optional>
|
|
Function to be invoked when the
sync operation completes. |
getPublic |
boolean
|
<optional>
|
false
|
Flag indicating if only
public metadata should be synced. |
|
Fires:
- app:sync when the synchronization process begins.
- app:sync:complete when the series of synchronization
operations have finished.event:
- app:sync:error if synchronization fails.
#
(static) syncPublic(optionsopt)
Parameters:
Name |
Type |
Attributes |
Description |
options |
Object
|
<optional>
|
Options. See full list of options
you can pass to Core.MetadataManager#sync.
Properties
Name |
Type |
Attributes |
Description |
callback |
function
|
<optional>
|
Function to be invoked when the
sync operation completes. |
|
#
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. |
#
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. |
#
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
Events
#
app:init
Fires when the app object is initialized. Modules bound to
this event will initialize.
#
app:locale:change
Fires when client application's user changes the locale, thus
indicating that the application should "re-render" itself.
#
app:login
#
app:login:success
Fires when login succeeds.
#
app:logout
Fires when the app logs out.
#
app:start
Fires when the application has
finished loading its dependencies and should initialize
everything.
#
app:sync
Fires when the app is beginning to sync data / metadata from
the server.
#
app:sync:complete
Fires when the app has finished its syncing process and is
ready to proceed.
#
app:sync:error
Fires when a sync process failed.
#
app:sync:public:error
Fires when a sync process failed during initialization of
the app.
#
app:view:change
Fires when route changes a new view has been loaded.
#
lang:direction:change
Fires when the language display direction changes.
Possible language display directions are RTL
and LTR
.