Calls a 3rd-party Web service. This requires the 3rd-party service to implement one of the cross-domain mechanisms supported by Flash, such as a crossdomain.xml policy file. For examples of crossdomain.xml policies, see Flickr or Digg.

Sample Use:

This code sample comes from the "Hello World" sample application.

...
<script>
var diggURL = "http://services.digg.com/stories/diggs";
function loadDiggStuff() {
openmail.Application.callWebService( { url: diggURL , method: "GET",
parameters: {appkey:"http://apidoc.digg.com"} }, function(args) {
alert(["got data: ", args.data].join('')); 

});  

} 

</script>
...
<button onclick='loadDiggStuff()'>Load some Digg API stuff</button><br>
...

Parameters:

service < Object > An object describing the Web service to call

handler < function > A callback function

service may include the following:
url: String Target URL
method: String "GET" or "POST"
parameters: Object A map of key/value pairs to use as the query string or the POST body

Returns: int

An error code.

Callback: response < Object >

On success: response.data contains the HTTP body returned by the Web service.
On failure: response.error contains an error message describing the failure.

Closes a currently opened view. To close the view initiating the call, pass null for view.

Sample Use:

Open another tab with different content:

...
<button onclick='openmail.Application.openView({
id:"otherTab", view:"full", target:"tab", title:"Y! Groups"

})'>
Open Tab

</button>

Open a dialog:

<button onclick='openmail.Application.openView({
id:"otherDialog", view:"full", target:"dialog", title:"Bunny!"

})'>
Open Dialog

</button>
...
<button onclick='openmail.Application.closeView({ id: "otherTab" })'>
Close the tab

</button>
<button onclick='openmail.Application.closeView({ id: "otherDialog" })'>
Close the Dialog

</button><br>
...

Parameters:

view < Object | null >

If view is not null, it must be an object that includes the following:
id: String The application-defined id passed to the openView() call (Required)

Returns: int

An error code.

Constructs and returns an object to interact with a service requiring authorization.

Sample Use:

Here is how getAuthService() is used to get an object to a profile "oauth" (which was created together with the application configuration in the development tool):

<script>
...
var oauth = openmail.Application.getAuthService({profile:'oauth'});
...
</script>

Parameters:

conf < Object > An object containing the configuration of the authorization service requested.

The object has the following members:

profile: The name of the stored profile
url: Url of the target service - only needed if service is used with http proxy
proxy: Url of the proxy - only needed if service is used with http

Returns: Object

An authorization object to interact with the Web service specified in the profile.

Retrieves stored data by key from the per-app-per-user persistent store.

Sample Use:

Here is how this version of getData() might be used in the "Saved Searches" example application to retrieve the user's stored searches.

<script>
...
var state = [
{label:"Sample 1", query:"test"},
{label:"Sample 2", query:"openmail"}

];
openmail.Application.getParameters(function(args){
openmail.Application.getData({ keys: ["state"] }, function(result){
var stateKeyStr = result.data["state"];
var stateKey=null;
try { stateKey = YAHOO.lang.JSON.parse(stateKeyStr); }
catch(e) { alert("Failed to convert stored data to JSON");}
state = stateKey||state;
if (args.context == "load") {
loadHandler();

} else {
render();

}

});

});
...

</script>

Here is another example of using the wildcard "*" as the key name:

<script>
function getAllData() {
openmail.Application.getData({ keys: [ "*" ] },
function( result ) {
var s = "";
for ( var keyName in result.data) {
s += keyName + "=" + result.data[keyName] = "\n";

}
alert( s );

}

);

}

</script>

Parameters:

keys < Object > The key names of the data to retrieve. This object must have a single data member named keys; this is an array of key names to retrieve. The wildcards "*" (any arbitrary string) and "?" (any single character) are supported.

handler < function > A callback function

Returns: int

An error code.

Callback: response < Object >

An object containing the requested data.

The object has the following members:

data: Object The data requested. Member names are the keys requested, values are the stored data.
version: Object Version number of application instance. Members names are the keys requested, values are version numbers.
totalCount: Number The number of items in the returned data set.

Retrieves properties associated with the view that invoked the function. These properties include the user, the reason the view was launched, application-defined view context, and action-dependent data. If the view was opened by a call to openView(), the data property is the same as the parameters argument passed to openView(). For example, in the "Hello World" example application, if an email message is dragged and dropped onto the application, then the data is the JSON representation of the email message.

Sample Use:

Code for this view includes a button that opens another instance of itself, with application-defined context and additional parameters. The view's load handler uses getParameters() to retrieve the context and parameters arguments originally passed to openView().

<body>
...
<button onclick='openmail.Application.openView({
id:"otherDialog", view:"full", target:"dialog", title:"Bunny!",
context:"button-launched view",
parameters:{ my: 1; custom: "JSON"; stuff:null }

})'>
Open Dialog

</button>
</body>
<script>
...
//load handler
function refresh() {
openmail.Application.getParameters(function(args){
// if view opened by button above:
//    args.context is "button-launched view"
//    args.data is { my: 1; custom: "JSON"; stuff:null }
var ta = document.createElement("textarea");
ta.value = YAHOO.lang.JSON.stringify(args);
ta.style.width="100%";
ta.style.height="100px";
document.getElementById("params").appendChild(ta);

});

}
...

</script>

Parameters:

handler < function > The callback function that receives the response.

Returns: int

An error code.

Callback: response < Object >

response.user is the user object. The user object has three members:

guid unique user identifier as string, not human-friendly.
intl internationalization domain (e.g. "us")
language user's language (e.g. "eng-us")

The remaining response members depend on the user action.

For a message drag-and-drop action, they are:

response.context: the value of the context node in the configuration XML of the application
response.data: message JSON object
response.reason: "data/message"

For click action:

response.context: the value of the context node in the configuration XML of the application
response.data: null
response.reason: "events/launch"

For openView() call:

response.context: the value passed to context argument of openView()
response.data: the value passed to parameters argument of openView()
response.reason: "api/openView"

This method opens a new view for the current application.

Sample Use:

As used in the "Hello World" sample application.

Open another tab with different content:

...
<button onclick='openmail.Application.openView({
id:"otherTab", view:"full", target:"tab", title:"Y! Groups"

})'>
Open Tab

</button>

Open a dialog:

<button onclick='openmail.Application.openView({
id:"otherDialog", view:"full", target:"dialog", title:"Bunny!"

})'>
Open Dialog

</button>
...

Parameters:

view < Object >

view may include the following:

id: String An application-defined id used to reference the view in other API calls
view: String The name of a view to load (e.g. "full" ) as created in the Application Editor.
target: String A valid target for the view to load that supports the following views: "tab", "dialog", and "hidden".
parameters: Object A map of values available to the loaded view through the getParameters() API call.
context: Object A value specifying the context of the opened view that can be retrieved through the getParameters() API call.
width: Number "Dialog" view only. The default width of the dialog view is 400 px.
height: Number "Dialog" view only. The default height of the dialog view is 400 px.
ttl: Number "Hidden" view only. The "time to live" of the view in seconds. The view will be forcibly closed afterward. A ttl of zero means the view will never be forcibly closed. The default value for ttl is 60 seconds.
title: String "Tab" and "dialog" only. The title is shown in the tab or dialog header area.

Returns: int

An error code.

Saves key/value set in a per-application-per-user persistent store.

Sample Use:

This is how the "Saved Searches" example could use setData() to store the user's saved searches.

<script>
...
function buttonClick(btn) {
var a = btn.id.split("_");
var action=a[0], index=a[1];
switch (action) {
...
case "save":
state[index].label = $("labelinput_"+index).value;
state[index].query = $("queryinput_"+index).value;
stateStr = YAHOO.lang.JSON.stringify(state);
openmail.Application.setData({ keys: { state: stateStr } });
render();
updateFolders();

...
case "delete":
if(confirm("Are you sure you want to delete this saved search?")) {
state.splice(index,1);
stateStr = YAHOO.lang.JSON.stringify(state);
openmail.Application.setData({ keys: { state: stateStr } });
render();
updateFolders();

}
break;

case "create":
state.push({label:"New Search", query:"from:bob"});
stateStr = YAHOO.lang.JSON.stringify(state);
openmail.Application.setData({ keys: { state: stateStr} });
render();
updateFolders();
break;

}

}

</script>
...

Parameters:

data < Object > An object describing the data to set.

handler < function > A callback function

data can include the following:

keys: Object The key/value pairs to store (Required)
ttl: Object key/ttl pairs. Member names should match the keys in keys. The value is the time-to-live of that data.

Returns: int

An error code.

Callback: response < Object >

An object containing the requested data.

The object has the following members:

data: Object The data requested. Member names are the keys requested, values are the stored data.
version: Object Version number of application instance. Members names are the keys requested, values are version numbers.
totalCount: Number The number of items in the returned data set.

This method allows you to customize the appearance of an application's folder, including changing its tooltip, count and subfolders, or extending its label. The root label provided in this configuration is appended to the default label. The default label is the application's name. The subfolder labels are defined in the config object.

Short of giving a full specification of the JSON format accepted for config, here's an example:

{
label: " - Beta",
tooltip: "click me",
subFolders: [{
label: "eden_people",
tooltip: "sub1 tt",

},
{
label: "flexcoders",
tooltip: "sub2 tt",

},
{
label: "shoop da woop",
tooltip: "blah"

}]

}

Sample Use:

In this excerpt from the "Saved Searches" sample application, each saved search is set up as a separate subfolder.

...
<script>
var state = [
{label:"Sample 1", query:"test"},
{label:"Sample 2", query:"openmail"}

];
...
function updateFolders(){
var obj = {
subFolders:[]

}
for (var i=0;i<state.length;i++) {
var s = state[i];
obj.subFolders.push(s);

}
openmail.Application.setFolderConfig(obj);

}

</script>
...

Parameters:

config < Object > An object that describes the folder configuration.

config can include the following:

label: String Text to be appended to the application's folder
tooltip: String Tooltip to display for the application
subFolders: Array of Objects An array of objects.

Each object in the subFolders array can include the following:

label: String Name of the subfolder (Required)
tooltip: String Tooltip for the subfolder

Returns: int

An error code.

Registers an event handler for a particular event. Only one handler will be called for a given application event.

Note: Setting a handler for an event will override any previous handlers for that event.

Sample Use:

The "Saved Searches" example application uses setListener() to run a search for a subfolder.

<script>
var state = [
{label:"Sample 1", query:"test"},
{label:"Sample 2", query:"openmail"}

];
...
function loadHandler() {
updateFolders();
openmail.Application.setListener("subfolder.click", function(args) {
openmail.Mail.search(state[args.index].query);

});

}
...

</script>

Parameters:

event < Object >

event should include the following:

event: String The name of the event to listen for. Currently, we only support "subfolder.click".

handler < function > A callback function

Returns: int

An error code.

Callback: response < Object >

When a subfolder is clicked on, an object will be passed to the callback.

index: Number The index of the subfolder that was clicked on.