Sidecar API Reference

Class: App

App

new App( [opts])

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 Argument Description
opts Object <optional>

Configuration options. See full list of options in #init.
Mixes In:
Returns:

Application instance.

Type
App

Members

$contentEl :jQuery

Content element selector.

The application controller loads layouts into the content element.

Type:
  • jQuery

$rootEl :jQuery

Base element to use as the root of the app.

Type:
  • jQuery

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.

Type:
  • Object

appId :string

Unique application ID.

Type:
  • string

Methods

<static> augment(name, obj [, init])

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 Argument 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( [opts])

Initializes the app.

Parameters:
Name Type Argument Description
opts Object <optional>

Initialization options.

Properties
Name Type Argument 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.
Returns:

Application instance

Type
App

<static> isServerCompatible(data)

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( [callback])

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 Argument Description
callback function <optional>

Function called once CSS is loaded.

<static> login(credentials [, info] [, callbacks])

Logs in to the app.

Parameters:
Name Type Argument 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 Argument 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( [callbacks] [, clear] [, options])

Logs out of this app.

Parameters:
Name Type Argument Default Description
callbacks Object <optional>

Object containing the callbacks.

Properties
Name Type Argument 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.
Fires:
  • app:logout
Returns:

XHR request object.

Type
SUGAR.HttpRequest

<static> navigate( [context] [, model] [, action])

Navigates to a new route.

Parameters:
Name Type Argument 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( [config])

Updates the config object based on the new metadata.

Reloads modules that depend on the config.

Parameters:
Name Type Argument 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.

Fires:
  • app:start

<static> sync( [options])

Syncs an app.

The events are not fired if the sync happens for public metadata.

Parameters:
Name Type Argument Description
options Object <optional>

Options. See full list of options you can pass to Core.MetadataManager#sync.

Properties
Name Type Argument 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( [options])

Syncs public metadata.

Parameters:
Name Type Argument Description
options Object <optional>

Options. See full list of options you can pass to Core.MetadataManager#sync.

Properties
Name Type Argument Description
callback function <optional>

Function to be invoked when the sync operation completes.

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.
Mixes In:
Returns:

Instance of this class.

Type
Object

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.
Mixes In:
Returns:

Instance of this class.

Type
Object

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.
Mixes In:
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

  • Fires when logging in.

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.