The power of objx lies in the ability to easily extend the library with your own plugins. This functionality is borrowed from jQuery and follows a very similar pattern.

Before you start

Research other plugins: Check to make sure your plugin hasn't already been created

Have you thought of something new?
Can you do better?

Hosting: Figure out where you want to host your plugin

Can we encourage you to go open source?
Does Google Code work for you?
Would you like to host them on the official objx plugins website?

Concepts: Are you familiar with the objx pattern?

Make sure you know the difference between static and instance methods

The "Hello World" of `objx` plugins

A static method

objx.hello = function() {
  alert("Hello World");
};

The above code is a complete objx plugin. The static method will alert "Hello World" when called. In fact, there is nothing special about this code at all - it is simply creating a new method called hello in the objx namespace.

You can test this code by calling it:

objx.hello();

You will see the expected "Hello World" alert box.

Writing instance methods: Adding context to your plugin

Now let's try something a little more difficult (and by 'little' I mean 'little'):

objx.fn.hello = function() {
  alert("Hello World");
};

Did you notice the addition of .fn? This tells objx that the hello method is a function that should be considered an instance method. So, it will be available when we wrap an object in the objx keyword like this:

objx("Mat").hello();

Of course our hello method doesn't need to be an instance method at all, since it totally ignores the "Mat" string in our previous code snippet. So let's add some context:

objx.fn.hello = function() {
  alert("Hello " + this.obj());
};

The this.obj() call will get the object that is being enhanced, in our case the "Mat" string.

objx("Mat").hello();

This will alert a box saying "Hello Mat". So we have used the context of the objx keyword in our 'instance' method.

Now we can use it to say hello to anybody:

objx("Omari").hello();  // alerts "Hello Omari"
objx("Simon").hello();  // alerts "Hello Simon"

Getting the enhanced object

To get the object that is being enhanced you should use the obj method:

this.obj()

Internally inside objx the object is stored in a local property called _obj. In the early days of objx, the plugins make direct calls to this._obj instead of going via the obj() method. However when the library gets minified _obj becomes something else and it not predictable (it varies depending on what you use to minify objx) so you must use the this.obj() method.

Ensure chaining is supported

Since our hello method doesn't need to return a particular value (at the moment, nothing is returned) it is an ideal candidate for chaining.

Consider this code snippet:

objx("Mat").hello().reverse().hello();

We are telling objx that we want to say hello first, then reverse the string, then say hello again (to this reversed string). Our hello method will not currently support this, because hello() returns nothing - and reverse() is not a function of null.

To add chaining we return this from the instance method:

objx.fn.hello = function() {
  alert("Hello " + this.obj());
  return this;
};

return this; ensures that the instance that the call was made on will be returned ready for other calls to be made afterwards.

objx("Mat").hello().reverse().hello();

// alerts "Mat"
// then   "taM"

Requiring and providing

See also requiring and providing for information about how objx lets you easily describe which plugins you require, and the one you are providing.

Supporting `objx.debug` property

The objx.debug property is a boolean value indicating whether additional debugging should take place to help developers while they are first using your plugin. For production, the value will be set to false and most of the errors and checks that are done by your plugin can stop - because by this point, the developer is confident that she has got everything right.

You should use objx.debug wherever you have developer time checks, such as ensuring the correct arguments were passed to a method, or that an object follows a particular format etc.

if (objx.debug) {
   if (arguments.length === 0 || !objx(arguments[0]).is("something")) {
      objx.error("my-plugin", "You must provide at least one argument to this method");
   }
}

The above check will be removed if objx.debug is set to false and your code will perform better.

Writing plugins that add behaviour to the existing objx methods

Some plugins (such as objx.type) add additional functionality to the underlying objx.type method. So if you call objx.type while passing an argument, it will convert the object to that type.

Calling objx.type() performs the exact same function as it originally did, the plugin simply adds more functionaltiy.

Plugin developers must be very careful when interfering with core objx methods, because there is a danger of breaking the whole framework.

The general rules around these kinds of plugins are:

Including the plugin should not change the behaviour of the original method,
The objx test suite (and all plugin tests) should all be green with your plugin included - this is a great way to ensure you haven't broken anything
The signature of the method call should be what indicates whether the original objx functionality is used, or if your new plugins functionality is used

Saving the old before overwriting it with the new

It is good practice to save a reference to the old plugin method:

objx.fn.oldMethod = objx.fn.method;

before coding your new method:

objx.fn.method = function() {

};

This way, you can actually use the original function from within yours:

objx.fn.method = function() {
   return this.oldMethod.apply(this, arguments);
};

New to `objx`?

Other topics

Rolling your own `objx` plugins