-
Notifications
You must be signed in to change notification settings - Fork 0
Javascript API
The Mulberry JavaScript framework provides a number of useful methods that you can use when creating a custom application using the Mulberry toolkit.
Note that the mulberry “namespace” is just an alias to the toura namespace;
all mulberry.* methods can be accessed as toura.* as well, and they are
generally defined in the framework code as toura.*.
Defined in: app/toura/components/_Component.js.
Creates and returns a constructor for a
component with the provided name using the provided prototye. The created
component can be used as part of a template definition as
custom.ComponentName or programmatically as
client.components.ComponentName. See Creating Custom Components for more
details.
Here is an example of a component defined with mulberry.component:
mulberry.component('WidgetA', {
componentTemplate : dojo.cache('client.components', 'WidgetA/WidgetA.haml'),
prep : function() {
var images = this.baseObj.images;
},
init : function() {
this.connect(this.domNode, 'click', '_wiggle');
},
_wiggle : function(e) {
e.preventDefault();
// ... code to do the wiggling ...
this.onWiggle();
},
onWiggle : function() {
// method for capability connection
}
});
Defined in: app/toura/capabilities/_Capability.js
Creates a capability, which can be added to a template definition to describe
the interaction between components on a page. A capability created using
mulberry.capability can be referred to in a template definition as
CapabilityName. See Capabilities for more details.
Here is an example of a capability that describes how WidgetB should behave
when WidgetA's onWiggle method is called:
mulberry.capability('WidgetA_WidgetB', {
requirements : {
widgetA : 'custom.WidgetA',
widgetB : 'custom.WidgetB'
},
connects : [
[ 'widgetA', 'onWiggle', 'handleWiggle' ]
],
handleWiggle : function() {
widgetB.jiggle();
}
});
Defined in: app/toura/Utilities.js
Creats a datasource using the provided name and prototype. The datasource can
be instantiated for application-wide use at application start by subscribing to
the /app/started topic, or it can be instantiated as needed in individual
capabilities or components. In either case, the datasource is availalbe at
client.data.DatsourceName.
mulberry.datasource('Google', {
search : function(term) {
return mulberry.jsonp('http://www.google.com?q=' + term + '&format=json');
}
});
var s = dojo.subscribe('/app/started', function() {
client.data.Google = new client.data.Google();
dojo.unsubscribe(s);
});
Defined in app/toura/app/Router.js.
Defines a custom route for the application. The route argument can be a string
or a regular expression; for examples, see
app/toura/app/Routes.js. The handler argument is a
function to be used to handle the route. It receives two arguments: a params
object containing parameters contained in the URL, and an augmented route
object with information about the route being run. The isDefault argument is
optional; if true, the route will be used as the default (home) route for the
application.
Defines a set of custom routes for the application using an array of routes
objects. Each object must have a route and a handler property; each
object may optionally include an isDefault property. These properties work
just like the arguments to mulberry.route.
A shorthand method for defining a route. The provided page object will be mixed
in with any params from the route, and will then be used to create and display
a page. The pageObject argument must be an object, and must include a
pageDef property that indicates the page definition to be used.
Directs the application to go to the specified hash.
Directs the application to go to the home/default route.
Directs the application to go back one page.
Defined in app/toura/app/PageFactory
Directs the application to construct a page based on the provided pageData
object. The object should include a pageDef property to indicate which
pre-defined template to use; if one is not provided, the Default template will
be used. The entire pageData object will be available to all components on
the page via their baseObj property. For usage examples, see
app/toura/app/Routes.js.
Defined in app/toura/app/UI.js
Places the provided page object in the user interface, and transitions from the old page to the new page.
An object containing information about the dimensions of the viewport.
An object containing information about the current page.
Defined in app/toura/app/PhoneGap.js
Creates an entry in the mulberry.app.PhoneGap namespace with the provided
name, exposing the module that is returned when the moduleFunction is executed.
The moduleFunction receives two arguments: a boolean indicating whether
PhoneGap is present in the current environment, and an object containing
information about the current device.
Here is an example:
mulberry.app.PhoneGap.registerAPI('custom', function(phonegap, device) {
return {
logDeviceType : function() {
console.log(device.type);
if (phonegap) {
console.log('Phonegap is available, too!');
}
}
}
});
mulberry.app.PhoneGap.custom.logDeviceType();
Defined in app/toura/app/PhoneGap/network.js
-
isReachable()Returns a promise that will resolve true if a network is available; the promise resolves false otherwise.
Defined in app/toura/app/PhoneGap/notification.js
-
alert()Displays an alert notification.
Defined in app/toura/app/PhoneGap/browser.js
-
url(url)Opens a ChildBrowser at the specified URL. -
getBrowser()Returns the ChildBrowser instance.
Defined in app/toura/app/Config.js
Returns the value of the specified configuration key. Information about an app,
for example, is available via mulberry.app.Config.get('app');
Sets the value of the specified configuration key to the provided value.
Gets the value of the specified key from device storage.
Stores the value of the specified key in device storage.
Clears all device storage, including SQLite and local storage.
Defined in app/toura/Utilities.js.
Returns a string based on substituting placeholders in the provided string with
values from the provided dataObject. This is an alias for
dojo.string.substitute.
For more details, see this article from Daniel Eric Lee.
Given a Haml template, returns a function that can be passed a data object. The returned function will use the data object to populate the template, and return a string.
var templateFn = mulberry.haml(".foo= bar");
templateFn({ bar : 'baz' }); // <div class="foo">baz</div>
The toura.jsonp method returns a promise. It can take one or two arguments.
- In the two-argument case, it should be passed a URL as the first argument, and a config object as the second argument. The config argument can have the standard Dojo XHR config properties.
- In the one-argument case, the sole argument can be:
- A string URL, in which case the callback param name will default to "callback"
- A config object, in which case the config object must specify a
urlproperty
So, for example, the following are valid:
toura.jsonp('http://search.twitter.com/search.json?q=toura');
toura.jsonp('http://search.twitter.com/search.json?q=toura', {
load : function() {
console.log('success');
},
error : function() {
console.log('error');
}
});
toura.jsonp({
url : 'http://search.twitter.com/search.json?q=toura'
});
The JavaScript framework publishes several useful "topics" at key points in the
application's lifecycle. You can add a subscription to any of these topics via
dojo.subscribe in order to trigger certain actions at certain times:
dojo.subscribe('/app/started', function() {
// things to do when the app is started
});
Note that the dojo.subscribe method returns a "handle" that can be passed to
dojo.unsubscribe if the subscription is no longer needed.
Subscriptions to this topic will run as soon as the device is ready. In a
PhoneGap environment, this topic is triggered when the deviceready event
fires; in a browser environment, this topic is triggered when the body
element's onload event fires. This is intended for internal use only, but it
may prove useful to you. Triggered in app/toura/base.js.
Subscriptions to this topic will run as soon as the data for the application
has been bootstrapped, but before the DOM has been populated. This topic is
also intended for internal use only, but it may prove useful to you.
Triggered in app/toura/app/Bootstrapper.js.
Subscriptions to this topic will run once the initial view of the application
has been displayed. Triggered in app/toura/base.js.
Subscriptions to this topic will run once a change in the URL's hash has been
handled; note that the new content may not yet be displayed at this time.
Triggered in app/toura/app/Router.js.
Subscriptions to this topic will run when any page specified via markdown is
viewed; subscribers to this topic will receive an argument containing the URL
of the page that was viewed. Triggered in
app/toura/app/Routes.js.
Subscriptions to this topic will run whenever the window is resized. Triggered
in app/toura/app/UI.js.
Subscriptions to this topic will run whenever a device's menu button is
pressed. Triggered in app/toura/app/UI.js.
Subscriptions to this topic will run when the application is finished
transitioning to a new page. Triggered in
app/toura/containers/Pages.js