Class Presto .App
The Presto App API.
Constructor Attributes | Constructor Name and Description |
---|---|
Method Attributes | Method Name and Description |
---|---|
findApp(id)
returns an array of zero or more app instances found, inline,
in the current web page.
|
|
Returns a |
|
getContentEl(el)
Returns the element provided by the Presto App Framework that encloses just the App itself, without the title bar or other Framework elements. |
|
Returns the inner height for this App as a string with the measurement or as a number of pixels. |
|
Constructs and returns an absolute URL to a help topic for this App, based on help information in the App Spec. |
|
Returns the URL to the Mashup Server that hosts this App. |
|
getProperties(filterFn)
Returns an Array of the configured properties for this App. |
|
getProperty(aName)
Returns the specified App property as an object. |
|
Returns an object with the list of all properties for the App. |
|
getPropertyValue(aName)
Returns the value of the specified App property as an object. |
|
Returns an object containing App property name/values. |
|
Returns the root element from the containing page that encloses this App. |
|
getScopedName(aName)
Returns a unidue identifier for the object specified by name or ID within this specific App instance. |
|
getSize()
Returns the inner dimensions of this App as an object with |
|
getWidth()
Returns the inner width of this App as a string for a measurement or as a number of pixels. |
|
Displays the message for the specified exception. |
|
Determines if this App has input parameters. |
|
hasTools()
Determines if this App supports tooling. |
|
Hides the information message, if any, shown with #showInfoMessage. |
|
Hides the input form for this App. |
|
Hides the sorting and filtering panel for this App. |
|
load(cfg, config)
Dynamically loads an App either by reference to an App id or by xml spec. |
|
loadByName(connection, appID, el, propValues, cb)
Dynamically loads an App specified by ID.
|
|
loadByUrl(prestoUrl, appUrl, el, cb)
Dynamically loads an App specified in a complete URL.
|
|
loadByXML(prestoUrl, xmlSpec, el, propValues, cb)
Dynamically load an App using the App Spec passed as an XML string.
|
|
onLoad(app)
The callback method for the "load" event for an App.
|
|
Custom Apps should implement this method to handle the refresh event that is fired by the Refresh button found in App title bars. |
|
onResize(width, height)
Custom Apps should implement this method to handle resize events from the App's container element
(root element) or from a workspace that contains this App.
|
|
publish(topic, data)
Publishes the specified message for the specified topic to any Apps that have subscribed to that topic. |
|
receive(topic, msg)
The subscription handler function to receive published messages when using loosely-coupled
communication between Apps wired in Presto Mashboard.
|
|
setHeight(ht)
Sets the inner height for this App as the specified measurement or as a number of pixels. |
|
setPropertyValue(aName, newValue)
Sets the value of the specified App property. |
|
setSize(size)
Sets the inner height and width for this App as the specified measurements or as a number of pixels. |
|
setTitle(title)
Sets the title for this App. |
|
setWidth(ht)
Sets the inner width for this App as the specified measurement or as a number of pixels. |
|
showInfoMessage(msg)
Displays the specified message to the App user. |
|
Displays the default input form for this App, typically when users click the Inputs toolbar button for the App. |
|
Displays the sorting and filtering panel for this App. |
|
subscribe(topic, onData, scope)
Subscribes to the named topic, providing a callback function to receive published messages for this topic. |
|
unsubscribe(topic, onData, scope)
Unsubscribe to a named topic for a given callback, with optional scope. |
- Parameters:
- {String} id
- The idetity of the app to find
- Returns:
- {Array} And array of zero or more app instances.
Returns a Presto.Connection
object to the Presto Mashup Server that hosts
this App. The prestoUrl
property for the App must be set with the URL to
the appropriate Mashup Server. See also
Presto.Connection.
Returns the element provided by the Presto App Framework that encloses just the App itself, without the title bar or other Framework elements.
- Parameters:
- el
Returns the inner height for this App as a string with the measurement or as a number of pixels. The inner height of the App is based only on App content. It does not include the App's root element or title bar.
- Returns:
- {String or Number}
Constructs and returns an absolute URL to a help topic for this App, based on help information in the App Spec. If no help information is defined in the App Spec, this returns undefined.
Help URLs in the App Spec can be absolute or relative. See <help> for more information.
- Returns:
- {String or undefined}
Returns the URL to the Mashup Server that hosts this App.
Returns an Array of the configured properties for this App. If specified, the optional filter funtion is used to filter the list of properties.
- Parameters:
- {Function} filterFn
- An optional function to filter the list of properties to return. This
function must be in the form
function(property, index)
and returns true or false.
- Returns:
- {Array}
Returns the specified App property as an object.
- Parameters:
- {String} aName
- The name of the property to return.
- Returns:
- {Object}
Returns an object with the list of all properties for the App. If no properties are defined, returns an empty array.
Returns the value of the specified App property as an object.
- Parameters:
- {String} aName
- The name of the property to return.
- Returns:
- {Object}
Returns an object containing App property name/values. Only properties that differ from default values are included.
&return {object}Returns the root element from the containing page that encloses this App.
Returns a unidue identifier for the object specified by name or ID within this specific App instance. This prepends the App ID.
- Parameters:
- {String} aName
- The name or ID to apply scoping to.
Returns the inner dimensions of this App as an object with width
and height
properties. Both properties may be valid measurements (string) or a number of pixels (number).
The inner dimensions of the App are based only on App content. They do not include the App's root element or title bar.
- Returns:
- {Object}
Returns the inner width of this App as a string for a measurement or as a number of pixels. The inner width of the App is based only on App content. It does not include the App's root element or title bar.
- Returns:
- {String or Number}
Displays the message for the specified exception. See also #showInfoMessage and #hideInfoMessage.
- Parameters:
- {Object} e
- The exception object which should contain a message property.
Determines if this App has input parameters. See also the showInputs
and
hideInputs
methods.
Custom Apps should implement this method when they custom App has input parameters and it includes an input form for user updates. This method allows Mashboard, workspaces or other App containers to provide access to this input form. If this returns true, Mashboard and workspaces include the default Inputs button in the App title bar.
- Returns:
- {Boolean}
Determines if this App supports tooling. See also the showTools
and
hideTools
methods.
Custom Apps should implement this method when they custom App supports tooling. This method allows Mashboard, workspaces or other App containers to provide access to this tooling. If this returns true, Mashboard and workspaces include the default Tooling button in the App title bar.
- Returns:
- {Boolean}
Hides the information message, if any, shown with #showInfoMessage.
Hides the input form for this App. This can be used when users submit the input form, but it can also be used by Mashboard, workspaces or other App containers to suppress the input form altogether if appropriate. This is useful, for example, when input parameters should be provided from saved user preferences or from published messages from an interaction in a workspace.
Custom Apps should implement this method to allow Mashboard, workspaces or other App containers to control the input
parameter form. See also the hasInputs
and showInputs
methods.
Hides the sorting and filtering panel for this App. This can be used by Mashboard,
workspaces or other App containers to suppress the sorting and filtering panel altogether
if appropriate. See also the showTools
method.
Dynamically loads an App either by reference to an App id or by xml spec. This is a convenience api method to allow an app to be loaded into a page with the minimum of configuration data.
Example usage:
In its most simple form, just speciying the app id:
Presto.App.load("HelloWorld");
chaining a callback handler to detect when app has loaded:
Presto.App.load("HelloWorld").then(function(app){
console.log("app with id " + app.id + "loaded!"
});
Specifying app details in a config object and listening for completion and errors:
Presto.App.load({
id: "HelloWorld",
el: "div.hello",
props: {
greeting: "Saarbruken"
}
}).then(function(app){
console.log("app loaded ! " );
}).fail(function(error){
console.error("failed to load app, ", error);
});
- Parameters:
- {String or Object} cfg
- {Object} config
- A string specifying the app id or a configuration object with these properties:
- {String or Object} config.el
- (optional) Either a DOM Element identifier or reference. If not specified The app will be niserted into the page body.
- {Object} config.props
- A object containing App properties to override any defaults
- {Object} config.conn
- A reference to an existing Presto.Connection.
- Returns:
- {jQuery.Deferred} promise A jQuery.Deferred object instance is returned which the calling party can then register callbacks for completion and or failure.
- Parameters:
- {Object} connection
- The
Presto.Connection
object to use with this App. Use #getConnection to get the default Connection object for an App. - {String} appID
- The ID of this App.
- {String or Object} el
- The ID of the DOM node where the App must be rendered. This can also be the actual DOM node.
- {Object} propValues
- An optional object with additional properties or Presto headers for this App in the form key = property name and value = property value. For more information on Presto headers, see Presto Headers/Parameters.
- {Object} cb
- An optional object with callback functions for this App. This object
can contain properties with functions in the forms:
onSuccess(appInstance)
andonFailure(error)
- Parameters:
- {String} prestoUrl
- The URL to the Mashup Server that hosts this App. Typically this is in the form
/presto
for a local Mashup Server orhttp://app-server:port/presto
for a remote Mashup Server. - {String} appUrl
- The complete URL for this App including all properties and optional Presto headers. This URL must be in the form
/presto/edge/api/rest/AppService/getAppSpec?x-p-anonymous=true&0=app-id
with other properties or Presto headers appended. For more information on Presto headers, see Presto Headers/Parameters. - {String or Object} el
- The ID of the DOM node where the App must be rendered. This can also be the actual DOM node.
- {Object} cb
- An optional object with callback functions for this App. This object
can contain properties with functions in the forms:
onSuccess(appInstance)
andonFailure(error)
- Parameters:
- {String} prestoUrl
- The URL to the Mashup Server that hosts this App. Typically this is in the form
/presto
for a local Mashup Server orhttp://app-server:port/presto
for a remote Mashup Server. - {String} xmlSpec
- The App Spec for this App as an XML string.
- {String or Object} el
- The ID of the DOM node where the App must be rendered. This can also be the actual DOM node.
- {Object} propValues
- An optional object with additional properties or Presto headers for this App in the form key = property name and value = property value. For more information on Presto headers, see Presto Headers/Parameters.
- {Object} cb
- An optional object with callback functions for this App. This object
can contain properties with functions in the forms:
onSuccess(appInstance)
andonFailure(error)
- Parameters:
- {Object} app
- The App object constructed from the App spec.
Custom Apps should implement this method to handle the refresh event that is fired by the Refresh button found in App title bars.
- Parameters:
- {String or Number} width
- The new width for the App as a measurement or a number of pixels.
- {String or Number} height
- The new height for the App as a measurement or a number of pixels.
Publishes the specified message for the specified topic to any Apps that have subscribed to that topic. For example:
app.publish('my.topic', { message: 'Hello World!', date: new Date() });
- Parameters:
- {String} topic
- The name of the topic to publish this message to.
- {Object or Any} data
- The message to publish. The datatype of this message should match the datatype defined for this topic in the App Spec for this App.
- Parameters:
- {String} topic
- An optional parameter specifying the name of the topic this message was published for.
- {Object or Any} msg
- A message being published for any topic that this subscription handler is registered for. This subscription handler is registered for published topics that are loosely-coupled (names and topic properties do not necessarily match) where wiring between publisher and subscriber is done in a workspace using Presto Mashboard.
Sets the inner height for this App as the specified measurement or as a number of pixels. The inner height of the App is based only on App content. It does not include the App's root element or title bar.
- Parameters:
- {String or Number} ht
- The new height for the App as a valid measurement (string) or as a number of pixels (number).
Sets the value of the specified App property.
- Parameters:
- {String} aName
- The name of the property to update.
- {Object} newValue
- The value, of any type, to set for this property.
Sets the inner height and width for this App as the specified measurements or as a number of pixels. The inner dimensions of the App are based only on App content. They do not include the App's root element or title bar.
- Parameters:
- {Object} size
- An object with these properties:
width
andheight
. Both properties may be valid measurements (strings) or a number of pixels (numbers).
Sets the title for this App.
- Parameters:
- {String} title
- The new title for the App.
Sets the inner width for this App as the specified measurement or as a number of pixels. The inner width of the App is based only on App content. It does not include the App's root element or title bar.
- Parameters:
- {String or Number} ht
- The new width for the App as a valid measurement (string) or as a number of pixels (number).
Displays the specified message to the App user.
- Parameters:
- {String} msg
- The message to display.
Displays the default input form for this App, typically when users click the Inputs toolbar button for the App.
Custom Apps should implement this method, and implement an input form, to allow Mashboard, workspaces or other App
containers to open the input form for this App. See also the hasInputs
and hideInputs
methods.
Displays the sorting and filtering panel for this App. See also the hideTools
method.
Subscribes to the named topic, providing a callback function to receive published messages for this topic. This method is used for tightly-coupled communication where both publishing and subscribing Apps use well-known topic names and payloads. Typically, either the topic declarations in both App Specifications match or the subscribing App knows the published topics and the callback function handles any payload wiring.
app.subscribe('my.topic', function(topic, data, other){ console.log('data received:', data); });
See also #receive for more information on callback functions.
- Parameters:
- {String} topic
- The name of topic to subscribe to.
- {Function} onData
- The callback function to receive published messages.
- {Object} scope
- An optional scope for the callback function.
Unsubscribe to a named topic for a given callback, with optional scope.
- Parameters:
- {String} topic
- The name of topic to subscribe to.
- {Function} onData
- The callback function to receive published messages.
- {Object} scope
- An optional scope for the callback function.