Instance.js is a lightweight Javascript library that let's you store and manipulate data before sending it off as parameters to the server.
Instance was coded from the ground up using pure Javascript (no dependencies or plugins required), and draws on similar concepts from existing frameworks like Backbone.
The library operates purely on the front end level. It won't save or sync your models, but it provides you with a solid interface to create robust user experiences and get data from the user's web browser to your server efficiently. It goes perfectly with an MVC framework such as Rails or Symfony, find out why...
The first thing to do is define your first Instance Model. An Instance Model is essentially a collection of parameters that are usually obtained from html input fields, such as a comment. You'll also need to include the latest version of instance.js in your document.
<head>
<title>instance.js Demo</title>
<script type="text/javascript" src="instance.min.js"></script>
</head>var Comment = new Instance({
name: "comment",
url: "/comments/new",
success: function() {
alert("Your comment has been saved!");
}
});Once we have our Instance Model defined, we're free to start playing around with it. Since we're creating a new comment, we'll setup the instance to include the latest values from a form:
<input type="text" name="name">
<input type="text" name="email">
<textarea name="message"></textarea>Comment.addField([
"name",
"email",
"message"
]);We now have direct access to the values of those fields under the Comment namespace. Let's remind our commentee what their name is.
var name = Comment.get("name");
alert("Your name is " + name );If there's no message for the comment, Instance won't send it...
var Comment = new Instance({
validations: {
message: { // name of the attribute/field
presence: { // built in validation rule
value: true,
fail: function() {
alert("Please enter your message!");
}
}
}
}
});Check out the Instance Validations Wiki page for a complete list of all the validation rules available. You can even use your own!
With parameters assigned to our new Instance Model, we can now perform an AJAX request to send them to any route on your server. We used jQuery to handle the click event.
$("#submit").click(function() {
// Fire it off!
Comment.send();
});You might recall that before we specified a name: of "comment" when setting up the Comment instance. As a result, parameters will be sent in a two dimensional hash, that is:
{ :comment => { :name => "", :email => "", :message => "" } }There's plenty more functionality to show off, including default values for parameters, a plethora of settings for .send(), removing of parameters and clearing Instances, adding parameters manually or from html elements, and checking out all of the built-in client side validation rules.