Skip to content

Home

Jump to bottom Edit New page
ntoll edited this page Aug 4, 2011 · 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.

delete(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.delete(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.

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.

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": "I like sandworms"
    },
    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": "I like sandworms"
    },
    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": "I like sandworms"
    },
    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 abstract things for users of the library they ultimately sit upon Fluidinfo's REST API. The following methods relate directly to the HTTP verbs they represent.

api.delete(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.delete(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",
    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 you 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)[http://fluidinfo.com/developers/] page. There's also the (Fluidinfo cookbook)[http://fluidinfo.com/cookbook] that contains many useful recipes, hints, tips and suggestions.
Add a custom footer
Add a custom sidebar
Clone this wiki locally