Skip to content

Home

Jump to bottom Edit New page
gridaphobe edited this page Jan 22, 2012 · 13 revisions

Welcome to the fluidinfo.js wiki!

Fluidwhat..?

Fluidinfo has been variously described as "a Wikipedia for data", "a platform for open data", "a social network for your data" and "stonkingly cool". It's basically a hosted storage solution that allows companies and individuals to create, search, organise and share data.

Fluidinfo also provides instant online APIs for those who use it for storage.

Finally, Fluidinfo provides simple yet powerful mechanisms for users to control their data. Nevertheless, it is organised in such a way that it remains openly writeable (so anyone can contribute).

Why not read our introduction to Fluidinfo..?

Fluidinfo.js

In case you hadn't guessed fluidinfo.js is a small library for using Fluidinfo's REST API with Javascript. It is currently aimed at client side development although plans are afoot to make it work server-side (with frameworks such as node.js). Fluidinfo supports CORS (Cross Origin Resource Sharing) so fluidinfo.js opens up the potential of sharing, using and annotating open, linked data with Fluidinfo within your own websites and projects.

Show me some code!

  var fi = fluidinfo({username: "username", password: "password"});
  var onSuccess = function(result) {
    // A callback to do something with the result
  };
  var onError = function(result) {
    // A callback to handle when things go wrong
  };
  fi.query({select: ["fluiddb/about", "ntoll/rating", "terrycojones/comment"], 
    where: 'oreilly.com/title matches "Javascript"', onSuccess: onSuccess, onError: onError});

Using Fluidinfo.js

To get started you should instantiate a fluidinfo object and optionally pass in three arguments contained in an options object:

  var options = {
    username: "fred", // your fluidinfo username
    password: "secret", // your fluidinfo password
    instance: "main" // either "main", "sandbox" or "http://somthing.else/"
  };
  var fi = fluidinfo(options);

Note: Passing no options assumes you're connecting as the anonymous user to the main instance. If you don't include an instance argument the library will default to the main instance. (The sandbox is used for testing and is regularly cleaned/restarted. Passing in a URL is a convenience for Fluidinfo developers running a development instance locally.)

The library is organised into two levels:

  1. Utility functions for common tasks.
  2. API functions for accessing Fluidinfo's REST API.

Utility Functions

These functions make it easy to perform the most common types of interactions with Fluidinfo. They follow a common pattern:

  • Pass in arguments via an options object.
  • Handle two types of callback: onSuccess and onError.
  • Both callbacks are passed a result object that contains the following attributes:
    • status the HTTP status code for the result from Fluidinfo (e.g. 200, 404)
    • statusText a description of the status of the result from Fluidinfo (e.g. "OK", "Not found")
    • headers an object representing the headers and associated values returned from Fluidinfo (e.g. { "Content-Type": "application/json"})
    • rawData if appropriate, a string representation of the raw data payload returned from Fluidinfo (e.g. the following JSON string: 
      '{ "id": "9c8e4b12-4b7d-40d2-865b-d5b1945350b1", 
"URL": "http://fluiddb.fluidinfo.com/objects/9c8e4b12-4b7d-40d2-865b-d5b1945350b1"}'
    • data if appropriate, a processed and de-serialized representation of the data payload returned from Fluidinfo (e.g. the following Javascript object related to the JSON string above: 
      { id: "9c8e4b12-4b7d-40d2-865b-d5b1945350b1", 
URL: "http://fluiddb.fluidinfo.com/objects/9c8e4b12-4b7d-40d2-865b-d5b1945350b1"}
  • The content of result.data will often be post-processed and/or cleaned up in some useful way.

createObject(options)

Allows a logged-in user to easily create/re-use an object in Fluidinfo.

  var options = {
    about: "my new object",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.createObject(options);

The about value is used to indicate what the new object represents. If an object "about" this value already exists then details of the existing object will be returned. It's possible to create so-called anonymous object that don't have an associated "about" value by leaving the about attribute out of the options.

del(options)

Removes a collection of tags (and associated values) from objects that match the query in the where argument.

  var options = {
    tags: ["ntoll/rating", "ntoll/description"],
    where: 'fluiddb/about="my object"',
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.del(options);

The example above will remove the ntoll/rating and ntoll/description tags from the object whose "about" value is "my object". Of course, the tags will be removed from all matching objects.

getObject(options)

Returns an object with specified tags/values.

The object can be referenced in two ways:

1 Using an "about" value:

  var options = {
    about: "my object",
    select: ["ntoll/rating", "ntoll/description"],
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.getObject(options);

2 Using an object's unique ID:

  var options = {
    id: "9c8e4b12-4b7d-40d2-865b-d5b1945350b1",
    select: ["ntoll/rating", "ntoll/description"],
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.getObject(options);

A successful response will have a single Javascript object stored in the result.data attribute. This object will have attributes with the same name as the tags specified in the select clause. It'll also have a the object's globally unique id stored in the id attribute:

  var obj = result.data;
  var id = obj.id;
  var ntollRating = obj["ntoll/rating"];
  // ... etc ...

If a value is "primitive" (it's a number, boolean, string etc...) referencing the tag on the object (as shown above) will return the raw result. However, if the value is "opaque" (i.e. it's a binary value such as an image, audio or pdf for example) then the result of referencing the tag on the object will be another object with three attributes:

  • value-type - the MIME type associated with the value (e.g. image/png)
  • size - obviously, the size of the binary file
  • url - the URL to directly reference the binary value. This is useful if the value references an image and you need to work out what to set the src attribute of an image element to be in order to display it on a web-page.

query(options)

Returns a list of objects and specified tags that match a query.

  var options = {
    select: ["ntoll/rating", "ntoll/description"],
    where: 'terrycojones/rating > 6',
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.query(options);

This example returns a list of Javascript objects that represent objects in Fluidinfo that match the search criteria specified in the where clause. Each object will have its globally unique id stored in the id attribute and contain attributes with names that match the tags specified in the select clause exactly as described in the results part of the getObject section above.

tag(options)

Allows users to tag values to specified objects.

The object can be referenced in two ways:

1 Using an "about" value:

  var options = {
    values: {
      "ntoll/rating": 7,
      "ntoll/comment": "It's fantastic!"
    },
    about: "my object",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.tag(options);

2 Using an object's unique ID:

  var options = {
    values: {
      "ntoll/rating": 7,
      "ntoll/comment": "It's fantastic"
    },
    id: "9c8e4b12-4b7d-40d2-865b-d5b1945350b1",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.tag(options);

update(options)

Updates all the specified tags on objects that match a query.

  var options = {
    values: {
      "ntoll/rating": 7,
      "ntoll/comment": "It's fantastic"
    },
    where: 'terrycojones/rating > 6',
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.update(options);

The example above sets the tag/values specified in the values object to all the object that match the query specified in the where clause.

REST API Functions

Whereas the utility functions asynchronously abstract things for users of the library they ultimately sit upon Fluidinfo's REST API.

The api related calls have the additional "feature" of allowing blocking synchronous calls to the API. You should not use this feature unless you know exactly what you're doing since such a call will block the browser thread thus degrading the usability and responsiveness of your application.

In any case, to use this "feature" simply pass in an async flag as false in the options object. A blocking synchronous call to any of these functions will return a result object. There is no need to specify onSuccess or onError callbacks as one does when calling them asynchronously. The caller is expected to handle any errors by inspecting the result of the call (hint: check the result's status attribute).

Here's an example:

  var fi = fluidinfo({username: "username", password: "password"});
  var options = {
    path: "namespaces/ntoll",
    args: {
      returnDescription: true,
      returnTags: true
    },
    async: false
  };
  var result = fi.api.get(options); // blocking call to API
  // check the result object
  // do something with the result

To re-iterate, making blocking synchronous calls is not encouraged, far better to use the default behaviour described below. You have been warned!

The following methods relate directly to the HTTP verbs they represent.

api.del(options)

Makes an HTTP DELETE call to the Fluidinfo API.

  var options = {
    path: "about/myobject/namespace/tag",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.api.del(options)

api.get(options)

Makes an HTTP GET to Fluidinfo's API.

  var options = {
    path: "namespaces/ntoll",
    args: {
      returnDescription: true,
      returnTags: true
    },
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.api.get(options)

The args object specifies the URL arguments to append to the end of the path like this:

  http://fluiddb.fluidinfo.com/namespaces/ntoll?returnDescription=true&returnTags=true

api.head(options)

Makes an HTTP HEAD request to Fluidinfo's API.

  var options = {
    path: "about/avatar/ntoll/films/rating",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.api.head(options)

Obviously, the interesting thing about the result of a HEAD call are its headers: result.headers

api.post(options)

Makes an HTTP POST request to Fluidinfo's API.

  var options = {
    path: "namespaces/ntoll",
    data: {name: "films", description: "Contains tags about films"},
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.api.post(options)

Note how the data is passed in as a Javascript object that will be automatically serialized.

api.put(options)

Makes an HTTP PUT request to Fluidinfo's API.

  var options = {
    path: "about/avatar/ntoll/films/comment",
    data: "I thought it was ok but the Smurfs did the blue humanoid thing better",
    onSuccess: function(result) { /* do something useful */ },
    onError: function(result) { /* handle any problems */ }
  };
  fi.api.put(options)

Note how the data is passed in as a Javascript value that will be automatically serialized into JSON.

FAQ

  • I've found a bug. What should I do? Submit a ticket in our issue tracker (click where it says "Issues" at the top of this page). Make sure you describe the problem thoroughly: What were you expecting? What actually happened? What steps reliably reproduce this problem? Remember to label the issue as a bug.
  • I want feature X dammit! Use the issue tracker to submit a description of the new feature and why we need it. If you can, submit a patch or pull request with a working and tested solution. Also, remember to label the issue as a feature request.
  • The library doesn't seem to work Hmm... we can assure you that it does ;-) Remember it relies on your browser implementing the CORS specification. Most modern browsers do, but not all browsers implement it fully. Another reason might be that you've pointed your browser to a file:///path/to/my/file.html. Browsers won't allow a CORS request from a page served from the local filesystem. Instead you should make your file available via a local web-server and point your browser instead to http://localhost/path/to/my/file.html.
  • I want to find out more about Fluidinfo If you're a developer then there are lots of useful resources on the Fluidinfo Developers page. There's also the Fluidinfo cookbook that contains many useful recipes, hints, tips and suggestions.
Add a custom footer
Add a custom sidebar
Clone this wiki locally