This sample demonstrates the conventions used when data is returned from a BrowserPlus service. The PStore Service is the tool we use to explore return values.

01
02
03
04
05
06
07
08
09
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

<html>
<head>
  <title>Errors and Return Values.</title>
  <style type="text/css" media="screen">
    #outputArea { width: 80%; padding: 10px; height:150px;
      border: 1px solid #999; }
  </style>
</head>

<body>
<a href="#" id="runValidCall"> run successful BrowserPlus call</a>
<br>
<a href="#" id="runInvalidCall"> run invalid BrowserPlus call</a>
<pre id="outputArea">
</div>

<script src="/js/browserplus.js"></script>  
<script src="/js/json2.js"></script>
<script>
var requiredServices = [
  { 
    service: "PStore"
  }
];

function dumpOutput(res) {
  var jsonText = JSON.stringify(res, null, "  ");
  var outputArea = document.getElementById("outputArea");
  while (outputArea.firstChild) {
    outputArea.removeChild(outputArea.firstChild);
  }
  outputArea.appendChild(document.createTextNode(jsonText));
}

function bpLoaded(res) {
  if (res.success) {
    BrowserPlus.PStore.set({key: 'foo', value: [1,2,3,'bar'] },
      function(){});

    // set up our links 
    document.getElementById("runValidCall").onclick = function() {
      BrowserPlus.PStore.get({key: 'foo'}, dumpOutput);
      return false;
    }

    document.getElementById("runInvalidCall").onclick = function() {
      BrowserPlus.PStore.get({key: 'foo', bogus: 'no such param'},
        dumpOutput);
      return false;
    }
  }
}

BrowserPlus.init(function(res) {
  if (res.success) {
    BrowserPlus.require({services: requiredServices}, bpLoaded);
  } else {
    alert("BrowserPlus required!");
  }
});
</script>
</body>
</html>
Run Example

In the previous sample we covered the asynchronous nature of service invocation, in this sample we'll go a little further into the structure of information that's returned. Here we can see that BrowserPlus.PStore.get() is invoked with two arguments: the first is an object holding named arguments, the second is a function which will be invoked when the call completes. This function accepts a single argument which holds the status of the call and returned data. This two argument calling convention is common to all functions on all services.

What we haven't covered yet is how information and errors are returned inside the argument to the callback function. Result callbacks will always be invoked with an object. That object will always have a success property. When success is true, the value property will contain the return value of the function. Here is a JSON depiction of a return object resulting from a successful service invocation:

{
    "success": true,
     "value": [ 1, 2, 3, "bar"]
}

When there are errors in the invocation, the success property holds boolean false, and an error member is present which includes a textual error code. Optionally, a verboseError property may also be present which holds a developer readable english string describing what went wrong:

{
    "error": "PStore.invalidArguments",
    "success": false,
    "verboseError": "argument 'bogus' not supported by function 'get'"
}

With this last bit of foundation laid, we're ready to jump in and start building web applications on BrowserPlus. Next we'll look at a key BrowserPlus feature, which allows javascript to get at drag and drop from the desktop...