Skip to content

Setup Guide

Jump to bottom Edit New page
Adam McArthur edited this page Jun 24, 2014 · 7 revisions

instance.js is written in pure Javascript - it requires no additional scripts or dependancies to run. To get started, add the script to your application. It is recommended that you use the minified version, especially in production environments...

<head>
  <title>Creating My First Instance Model</title>
  <script type="text/javascript" src="./instance.min.js"></script>
</head>

Now that the script has been loaded in our HTML document, we are ready to setup our first Instance Model. Instance models are usually defined inside a variable, like so...

var Comment = new Instance();

Saving the Instance inside a variable means that we can do cool stuff with it later. Pick a name that's relevant to your model, and make sure it's capitalised for optimum code presentation. In the example above, you can see that I've called my Instance Model Comment.

Settings

Now we're ready to pass in some settings to our new instance. Let's rewrite the above code, this time specifying some settings for the instance.js script to use. Listed below are all the allowed settings:

Name: Instead of sending your parameters "flat" (eg - { :name => "Adam }), you can give your Instance Model an internal name so that parameters are sent in two-dimensional format (eg - {:comment => { :name => "Adam" }}). Read more here.

var Comment = new Instance({
   name: "comment"
});

URL: The default URL the the Instance sends the parameters to. Default - "./"

var Comment = new Instance({
   url: "/comments/new"
});

Method: The default HTTP request method to submit the Instance with. Default - "post"

var Comment = new Instance({
   method: "put"
});

Defaults: These default parameters will ship out of the box with the Instance, and won't need to be added again. They can be modified later if need be.

var Comment = new Instance({
   defaults: {
      subscribe_to_thread: false,
      last_page: "http://github.com/adammcarth/indent.js" 
   }
});

Headers: Specify custom HTTP headers to be sent with the AJAX request.

var Comment = new Instance({
   headers: {
      "My-Custom-Header": "value"
   }
});

Success: Define a callback function to be executed if the request is 200 OK.

var Comment = new Instance({
   success: function(response) {
      alert("Wooh! The request went through. Server response: " + response);
   }
});

Error: Define a callback function to be executed if the request fails (eg - Error 404 or 500)

var Comment = new Instance({
   error: function(status, response) {
      alert("Oops. There was an Error " + status + ". Server response: " + response);
   }
});

All Together

That's it for settings! Now let's combine everything we've learned into one super-duper Instance Model, and we're then ready to move on to other cool stuff.

<head>
  <title>Creating My First Instance Model</title>
  <script type="text/javascript" src="./instance.min.js"></script>
</head>

<body>
  <h1>Add a new comment</h1>

  <script type="text/javascript">
     var Comment = new Instance({
        name: "comment",
        url: "/comments/new",
        method: "get",
        defaults: {
           subscribe_to_thread: false,
           last_page: "http://github.com/adammcarth/instance.js"
        },
        headers: {
           "My-Custom-Header": "value"
        },
        success: function(response) {
           alert("Yay, we did it!");
        },
        error: function(status, response) {
           alert("Darn it! It failed.");
        }
     });
  </script>
</body>

Did you find this page helpful? Shoot me an email...

Want to contribute to instance.js? Find out how.

Clone this wiki locally