The Google Sidewiki Data API allows client applications to view Google Sidewiki content in the form of Google Data API feeds.
Your client application can use the Google Sidewiki Data API to request a list of Sidewiki entries and query for Sidewiki entries that match particular criteria.
In addition to providing some background on the capabilities of the Google Sidewiki Data API, this document provides examples of basic Data API interactions using the JavaScript client library. If you're interested in understanding more about the underlying protocol that the library uses, see the Protocol section of this developer's guide.
This document is intended for programmers who want to write JavaScript client applications that can interact with Google Sidewiki. It provides a series of examples of basic Data API interactions using the JavaScript client library.
For Google Sidewiki Data API reference information, see the Protocol reference guide. This document assumes that you understand the general ideas behind the Google Data APIs protocol and the data model and control flow used by the JavaScript client library. It also assumes that you know how to program in JavaScript.
For reference information about the classes and methods provided by the client library, see the JavaScript client library API reference.
This document is designed to be read in order; each example builds on earlier examples.
You agree to abide by the Google JavaScript Client Library Terms of Use when using the JavaScript client library.
Before you can write a JavaScript client application, you need to do some setup, including obtaining a Data API key and acquiring the library.
You may want to sign up for a Google Sidewiki account for testing purposes. Google Sidewiki uses Google Accounts, so if you already have a Google account, you're all set.
Currently, we only support JavaScript client applications that run in a web page in a browser. Currently supported browsers are Firefox 1.5 and higher, and Internet Explorer 6.0 and higher.
The JavaScript client library handles all communication with the service's server. If you're an experienced JS developer, you may be thinking, "But what about the same origin policy?" The JavaScript client library allows your client to send Google Data API requests from any domain while remaining compliant with the browser security model.
To acquire the JavaScript client library, you need a developer key. To obtain one, go to the Google Data API key signup page, read the terms of service, and enter your website's URL. The signup page provides you with a key, which is an alphanumeric string that your client uses to identify itself to Google when the client requests the client library.
A key is associated with a website. If you want to use the JavaScript client library on another site, you should obtain another key for that site. More specifically, a key is associated with the URL that you enter on the signup page; the key applies to all URLs under the domain or directory that you specify.
Before your client can use the client library, the client has to request the client library code from the server.
Start by using a <script> tag in the <head> section of your
HTML document to fetch the Google AJAX API loader:
<script type="text/javascript" src="http://www.google.com/jsapi?key=developer_key"> </script>
Where developer_key is the key you obtained from the signup page.
To acquire the Google Data API client library after fetching the loader, use the following line
in your JavaScript setup code, which must be called from the <head> section of
your HTML document (or from a JavaScript file that's included using a <script>
tag in the <head> section of your HTML document):
google.load("gdata", "2.x");
The second parameter to google.load() is the requested version number of the
JavaScript client library. Here are the possible version numbers and what they mean:
"2""2.x""2.s""2.0", "2.1", etcAfter you've called google.load(), you have to tell the loader to wait until the
page finishes loading and then call your code:
google.setOnLoadCallback(getEntriesForWebpageFeed);
Where getEntriesForWebpageFeed() is a function that we'll define in a later section
of this document. Use this approach instead of having an onload handler attached to
the <body> element.
Currently all Google Sidewiki feeds are public and do not require authentication. However, if you want to access your private Sidewiki entries, then your client needs to authenticate before requesting private data.
The JavaScript client library uses the AuthSub authentication system. For more information about authentication with Google Data APIs in general, see the authentication documentation.
AuthSub proxy authentication is used by web applications that need to authenticate their users to Google Accounts. The website operator and the client code don't have access to the username and password for the Google Sidewiki user; instead, the client obtains special AuthSub tokens that allow the client to act on a particular user's behalf.
Here's a brief overview of what happens during the authentication process for a web-based JavaScript client:
google.accounts.user.login() method provided by
the client library, passing it a "scope" value that indicates which Google service to
use. For Google Sidewiki, the scope is
"http://www.google.com/sidewiki/feeds/".google.accounts.user.login().Note: For the JavaScript client library to make authenticated
Google Sidewiki requests in a web browser, your page must contain an image that's hosted at the
same domain as your page. It can be any image, even a single-pixel transparent image, but there
must be an image on the page. If you want the image to not appear on your page, you can use the
style attribute of the <img> tag to position the image outside the
rendering area. For example: style="position:absolute; top: -1000px;"
Here's the client-application code that handles logging in. We'll call the
setupMyService() function from other code later.
function logMeIn() {
scope = "http://www.google.com/sidewiki/feeds/";
var token = google.accounts.user.login(scope);
}
function setupMyService() {
var myService = new google.gdata.sidewiki.SidewikiService('exampleCo-exampleApp-1');
logMeIn();
return myService;
}
Tip: We strongly recommend that you provide a login button or other
user input mechanism to prompt the user to start the login process manually. If, instead, you call
google.accounts.user.login() immediately after loading, without waiting for user
interaction, then the first thing the user sees on arrival at your page is a Google login page.
If the user decides not to log in, then Google does not direct them back to your page; so from the
user's point of view, they tried to visit your page but were sent away and never sent back. This
scenario may be confusing and frustrating to users. In the example code in this document, we'll be
calling google.accounts.user.login() immediately after loading, to keep the example
simple, but we don't recommend this approach for real-world client applications.
Note that you don't have to do anything with the variable named token; the client
library keeps track of the token, so you don't have to.
Note: When you create a new SidewikiService object, the client
library calls a method named google.gdata.client.init(), which checks that the
browser the client is running in is supported, and validates the developer key. If there's an
error, then the client library displays an error message to the user. If you want to handle this
sort of error yourself, then you can explicitly call
google.gdata.client.init(handleInitError) before you create the service, where
handleInitError() is your function. If an init error occurs, then your function
receives a standard Error object; you can do whatever you want with that object.
The token remains valid until you revoke it by calling
google.accounts.user.logout():
function logMeOut() {
google.accounts.user.logout();
}
If you don't call logout(), then the cookie that stores the token lasts for two
years, unless the user deletes it. The cookie is retained across browser sessions, so the user can
close their browser and then reopen it and come back to your client and they'll still be logged
in.
However, there are certain unusual circumstances in which a token can become invalid during a
session. If Google Sidewiki rejects a token, your client should handle the error condition by
calling logout() to remove the cookie containing the current token, and then calling
login() again to acquire a new, valid token.
There are two other AuthSub methods that you may find useful in various contexts:
google.accounts.user.checkLogin(scope) tells you whether or not the browser
currently has an authentication token for the given scope.google.accounts.user.getInfo() provides detailed information about the current
token, for debugging use.For details about using JavaScript to interact with AuthSub, including information on token
management and on checkLogin() and getInfo(), see the
Using "AuthSub" Authentication with the JavaScript
Client Library document.
The Google Sidewiki Data API provides a feed that lists the Sidewiki entries for a particular web page.
The following sample code is called by the Google AJAX API loader when the client library finishes loading, as specified earlier. This code sets up an authenticated service, then retrieves the feed and displays the title, author and content of the first Sidewiki entry in the list.
function getEntriesForWebpageFeed() {
var myService = setupMyService();
var webpage_encoded = "http%3A%2F%2Fwww.google.com%2F";
var webpageFeedUri = "http://www.google.com/sidewiki/feeds/entries/webpage/" + webpage_encoded + "/full";
myService.getSidewikiEntryFeed(webpageFeedUri, handleSidewikiEntryFeed, handleError);
}
function handleSidewikiEntryFeed(myResultsFeedRoot) {
firstEntry = myResultsFeedRoot.feed.getEntries()[0];
showEntryInfo(firstEntry);
}
We're specifying the feed URL in a global variable so that it can be used in later functions.
showEntryInfo is a function that shows alert dialog with basic info of given
Sidewiki entry: author name, entry title and content:
function showEntryInfo(entry) {
var info = "Sidewiki Entry titled \"" + entry.getTitle().getText()
+ "\" written by "
+ entry.getAuthors()[0].getName().getValue() + ": \""
+ entry.getContent().getText() + "\".";
alert(info);
}
Note that we're making myService a global variable, for ease of use in later
functions.
The webpage_encoded variable is encoded according to section 2 of the
RFC 2396 standard. Note that
http://www.google.com/ and http://www.google.com web pages (the latter
is without the trailing slash) are treated as different web pages by Google Sidewiki. Web pages
should be specified as they appear in browser's address bar.
After setting up the service, getEntriesForWebpageFeed() calls the client library's
getSidewikiEntryFeed() method to request the Sidewiki entry feed.
Note: By default, only high-quality entries are returned in the feed. Use
includeLessUseful
query parameter to fetch less useful entries.
In the call to getSidewikiEntryFeed(), the second argument is
handleSidewikiEntryFeed, which is a callback function. Google Sidewiki processes the
request and then, if the request was successful, passes a "feed root" object containing
the requested feed to the callback. A feed root is a container object that contains a feed.
The third argument to getSidewikiEntryFeed() is an optional error-handling function;
if the client library encounters an error, it calls the specified error handler instead of the
success callback function. The object that the client library passes as the argument to the error
handler is an instance of the
JavaScript Error object, with an additional cause property.
Here's a simple version of the error handler:
function handleError(e) {
alert("There was an error!");
alert(e.cause ? e.cause.statusText : e.message);
}
We're handling errors by simply displaying them to the user; your client's error handler should
probably be more sophisticated. In some contexts, there may be no cause specified, so in those
cases our example error handler falls back to displaying the standard message
property.
Retrieving Sidewiki entries written for all web pages of a particular domain is similar to retrieving
entries written for a web page, just change webpageUriEncoded path parameter to
domainPathEncoded and use the following feed URI to retrieve, for example, all Sidewiki entries
written for all web pages under www.google.com/ domain:
http://www.google.com/sidewiki/feeds/entries/domainpath/domainPathEncoded/full
domainPathEncoded is encoded according to section 2 of the
RFC 2396 standard
(In our example, it will be www.google.com%2F).
Note that www.google.com/ and www.google.com domains
(the latter is without the trailing slash) are treated as different domains by Google Sidewiki,
you should always specify domain with a trailing slash and without URI scheme.
Domain path parameter may include subdomains or path elements. For example, Sidewiki entry that is
written for web page at http://www.mydomain.com/path1/path2/webpage.html may be
retrieved by specifying the following domain paths:
mydomain.com/www.mydomain.com/www.mydomain.com/path1/www.mydomain.com/path1/path2/The entry won't be retrieved if the following domain paths are specified:
mydomain.com/path1/path2/ (subdomains missing)http://www.mydomain.com/ (should not contain URI scheme)www.mydomain.com (has no trailing slash)Note: Arbitrary regular expressions or wildcards are currently not supported, only path-like values ending with trailing slash and containing no URI scheme.
To retrieve a feed of a specific Sidewiki author, continue execution from the previous example
by modifying the end of the handleSidewikiEntryFeed() function to call a new function,
getSidewikiEntryFeed():
function handleSidewikiEntryFeed(myResultsFeedRoot) {
var firstEntry = myResultsFeedRoot.feed.getEntries()[0];
showEntryInfo(firstEntry);
var authorId = firstEntry.getAuthors()[0].getResourceId().getValue();
var authorFeedUri = "http://www.google.com/sidewiki/feeds/entries/author/"
+ authorId + "/full";
myService.getSidewikiEntryFeed(authorFeedUri, handleEntriesByAuthorFeed, handleError);
}
Here the feed URL looks like:
http://www.google.com/sidewiki/feeds/entries/author/authorId/full
Where authorId is the author profile ID which can be retrieved from Sidewiki entries.
authorId is the string that appears at the end of the user's profile URL
(http://www.google.com/profiles/userID). Typically it is a string of digits, but if
user has a GMail account and checked an option to display their GMail username in their profile URL,
then authorId may be their GMail username.
(Learn more about
Google profiles.)
The first parameter to getSidewikiEntryFeed()is the feed URI of the
Sidewiki entries written by the author of the first entry retrieved for
http://www.google.com/ web page; the second is another callback function:
function handleEntriesByAuthorFeed(myResultsFeedRoot) {
var firstEntry = myResultsFeedRoot.feed.getEntries()[0];
showEntryInfo(firstEntry);
}
To retrieve Sidewiki entries written by currently authenticated user use special keyword
me instead of authorId, so the feed URL looks like:
http://www.google.com/sidewiki/feeds/entries/author/me/full
This feed returns a list of Sidewiki entries written by the currently authenticated user.
The following code lets you request a specific entry, given the entry's URI. In this context, we already have the entry; we're just requesting it again for demonstration purposes.
function requestMySpecificEntry(entryUri) {
myService.getSidewikiEntry(entryUri, handleMySpecificEntry, handleError);
}
function handleMySpecificEntry(retrievedEntryRoot) {
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}
This example is essentially the same as the getEntriesForWebpageFeed() example,
except that we're calling the service's getSidewikiEntry() method to get a specific
entry, and the URI is a little different — it has an entry ID at the end of it.
Also, we need to be able to use the retrieved entry later, so we're copying it into a global variable.
The Google Data API lets you request a set of entries that match specified criteria, such as
limiting number of retrieved entries. To do this you create a SidewikiEntryQuery object
and pass it to the getSidewikiEntryFeed() method. For example, to limit number of
retrieved entries, use the setMaxResults method of the SidewikiEntryQuery
object.
To perform a query with query parameters using the sample code, first modify the
handleMySpecificEntry() function to call a new query function:
function handleMySpecificEntry(retrievedEntryRoot) {
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
queryWebpageFeed();
}
The following code prints the title of each Sidewiki entry.
function queryWebpageFeed() {
var myQuery = new google.gdata.sidewiki.SidewikiEntryQuery(webpageFeedUri);
myQuery.setMaxResults(5);
myService.getSidewikiEntryFeed(myQuery, handleMyQueryResults, handleError);
}
function handleMyQueryResults(myResultsFeedRoot) {
var myFeed = myResultsFeedRoot.feed;
alert(myFeed.getTitle().getText() + " - 5 recent Sidewiki entries");
for (var i = 0; i < myFeed.getEntries().length; i++) {
var thisEntry = myFeed.getEntries()[i];
alert(thisEntry.getTitle().getText());
}
}
For more information about query parameters and full list of supported query parameters, see the Google Sidewiki Data API Reference Guide and the Google Data APIs Reference Guide.