objx puts JavaScript on steroids. It wraps normal JavaScript objects and enhances them via a suite of plugins. objx is Object Oriented which means that you can write high quality fully testable code utilising the latest programming paradigms.

For example:

var normalArray = [1, 2, 3];

var enhancedArray = objx(normalArray);

The enhancedArray object can now have a wide range of actions run against it - such as each() and group().

How do you use `objx`?

objx lets you enhance normal JavaScript objects and work on them in an unobtrusive way without adversely affecting the original objects.

To create a new objx object you simply wrap a JavaScript object with the objx() method:

var arrayObj = [1, 2, 3];
var arrayObjx = objx(arrayObj);

In the code snippet above, arrayObjx is actually an objx object that contains the original array which plugins can reference and do work on.

What gets returned?

Most objx plugins will return the objx object itself, which allows chaining, but sometimes this doesn't make sense. For example, the size() method needs to return a Number and therefore does not support chaining.

If the plugin has affected or modified the original object, then the same objx object should be returned. If the plugin method has created a new object then a new objx object will be created and returned leaving the original objx object (and in fact the object being enhanced) in tact. The plugin documentation should clearly describe the behaviour of the plugins.

Setting up your first page

objx runs in the browser so all you need to start writing objx code is:

a text editor (we recommend TextMate for Mac or notepad++ for Windows)
a web browser (we recommend Safari for Mac or Chrome for Windows)

Create `test.htm` page

Create a new text file called test.htm and copy and paste the following page template:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 2.0//EN" "http://www.w3.org/MarkUp/DTD/xhtml2.dtd">
<html xmlns="http://www.w3.org/2002/06/xhtml2/" xml:lang="en">
  <head>
    <title>My first objx page</title>
  </head>
  <body>
  </body>
</html>

Add the objx core file

We need to include the core objx file in the page by adding the following script tag to the head of the page:

<script type="text/javascript" src="http://objx.googlecode.com/svn/trunk/src/objx.js"></script>

Did you know - http://objx.googlecode.com/svn/trunk/src/objx.js is a direct link to our source repository, and points to the latest bleeding edge version of objx.js which is not recommended. Instead, we recommend you visit the Downloads section and download an actual release. It also makes sense to have your own local copies of the files.

Add any plugins

Next we need to include the plugins we want to use in our page. Since each plugin is in a different file, we will need to have one script tag per plugin. NOTE: In the real world, we will need to optimise this by combining all of our objx files into one.

In this case we are going to make use of the each plugin, so include the following script tag underneath the objx.js one:

<script type="text/javascript" src="http://objx-plugins.googlecode.com/svn/trunk/src/plugins/each/objx.each.js"></script>

Did you know - If you get the order of the script tags mixed up, the plugin won't have anything to plug into.

Too many `script` tags?

You may have spotted the biggest problem with the cherry picking approach which is that using too many script tags in your pages will drastically slow down the performance of your pages. We have described how to solve this problem on our optimisation page.

Comment by msdav...@freenet.co.uk, Jun 23, 2009

I had to also cherry-pick the plugins is, append and reveach to get this example to work.

Comment by matr...@mac.com, Aug 06, 2009

Thanks for that - well spotted. I have made the necessary changes to the tutorial.

New to `objx`?

Other topics

Getting Started

What is `objx`?