If you want access to information in Frog, you will need to talk to the Frog API from within your widget. The widget javascript helper library makes this reasonably simple, and to work out what information you can retrieve and actions you can initiate you should refer to the API Reference section.
There are two aspects to retrieving data from Frog
- defining the permissions (known in Frog as roles) that your widget needs.
- making the required Ajax calls in javascript to retrieve or update the required data.
Defining the Roles Your Widget Requires
Firstly you need to define in your widget the roles you will require. The role requirements of various API calls are detailed in the API reference section. When a user installs your widget it will prompt them to approve the roles you have requested (if indeed they themselves possess those roles). This works in much the same way as installing an app on your phone, or logging in to another website using your facebook or twitter login where the 3rd party requests certain roles that need to be approved by the user using the service.
To define the roles you require, you need to add the Frog namespace to your <html> element declaration:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:frog="http://fdp.frogtrade.com/ns/">
Once you have defined the Frog namespace you can safely declare a <frog:roles> element in the head of your XHTML document within which you will declare a <role> element for each role that you require. We will build an example widget where we retrieve a list of all the defined groups in Frog from the API, using the groups.getAll method. This requires the roles api.groups.getall and group.view.all so the required role declaration in our HTML is:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:frog="http://fdp.frogtrade.com/ns/">
<head>
<title>Groups List</title>
<meta name="frogLib" content="1.0" />
<frog:roles>
<role name="group.view.all" />
<role name="api.groups.getall" />
</frog:roles>
</head>
The <role> element has one require parameter, name, which is the role alias. There are an addition two optional parameters: description and status. The description parameter allows you to add some freeform text that will be displayed to the user when the roles are prompted for to explain why your widget requires this role. The status parameter defaults to required which indicates that this role is required for your widget to execute successfully. If your widget can operate without a particular role but it's inclusion would be advantageous, you can specify this role as status="optional".
Making the API Call
You will make the API call itself in the widget javascript as an Ajax request using the Frog.API helper object. This has two methods:
| Method | Description |
|---|---|
Frog.API.get(method,opts) |
makes a request to retrieve data using the API |
Frog.API.post(method,opts) |
makes a request to update data using the API |
Both methods have the same argument signature: the first argument (method) is the API method you will be calling: in our case this will be 'groups.getAll'. The second argument is the options for the request as a javascript object. This object has the following elements:
| Key | Description |
|---|---|
onSuccess |
callback on success |
onError |
callback on failure |
params |
object containing the request parameters (as detailed in the API reference) |
So the code to make an API call to retrieve the list of all Frog groups available would be:
var displayGroups = function(data){ /* ... snip ... */ };
var handleError = function(err){ widget.log(err.message); }
Frog.API.get('groups.getAll',{ onSuccess: displayGroups,
onError: handleError,
params: {}
});
Notice that in this case we don't need to pass any parameters to the groups.getAll method so we could leave out the params key but it is included for clarity.
Example List Groups Widget
Bringing these two aspects together a widget that listed all available Frog groups could be written like:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:frog="http://fdp.frogtrade.com/ns/">
<head>
<title>Groups List</title>
<meta name="frogLib" content="1.0" />
<frog:roles>
<role name="group.view.all" />
<role name="api.groups.getall" />
</frog:roles>
<script>
//<![CDATA[
var displayGroups = function(data){
var ul = widget.createElement('ul');
for (var i=0;i<data.length;i++) {
ul.appendChild(widget.createElement('li').setText(data[i].name));
}
widget.setBody(ul);
};
var handleError = function(err){
widget.setBody('<p>Sorry, an error occurred.</p>');
widget.log(err.message);
}
Frog.API.get('groups.getAll',{ onSuccess: displayGroups,
onError: handleError });
//]]>
</script>
</head>
<body>
<p>Loading...</p>
</body>
</html>
More examples of widgets that interact with the API are available if you browse through the Tutorial list.
2 Comments
101-499 points
6-50 points