• Plugin can be customised using options
• Setters/Getters for options
• Private and public methods
• Callback hooks
• Plugin instances can be destroyed

The boilerplate

Here is the bare bones, uncommented boilerplate source code:

/**
 * A jQuery plugin boilerplate.
 * Author: Jonathan Nicol @f6design
 */
;(function($) {
  var pluginName = 'demoplugin';

  function Plugin(element, options) {
    var el = element;
    var $el = $(element);

    options = $.extend({}, $.fn[pluginName].defaults, options);

    function init() {
      // Add any initialization logic here...

      hook('onInit');
    }

    function fooPublic() {
      // Code goes here...
    }

    function option (key, val) {
      if (val) {
        options[key] = val;
      } else {
        return options[key];
      }
    }

    function destroy() {
      $el.each(function() {
        var el = this;
        var $el = $(this);

        // Add code to restore the element to its original state...

        hook('onDestroy');
        $el.removeData('plugin_' + pluginName);
      });
    }

    function hook(hookName) {
      if (options[hookName] !== undefined) {
        options[hookName].call(el);
      }
    }

    init();

    return {
      option: option,
      destroy: destroy,
      fooPublic: fooPublic
    };
  }

  $.fn[pluginName] = function(options) {
    if (typeof arguments[0] === 'string') {
      var methodName = arguments[0];
      var args = Array.prototype.slice.call(arguments, 1);
      var returnVal;
      this.each(function() {
        if ($.data(this, 'plugin_' + pluginName) && typeof $.data(this, 'plugin_' + pluginName)[methodName] === 'function') {
          returnVal = $.data(this, 'plugin_' + pluginName)[methodName].apply(this, args);
        } else {
          throw new Error('Method ' +  methodName + ' does not exist on jQuery.' + pluginName);
        }
      });
      if (returnVal !== undefined){
        return returnVal;
      } else {
        return this;
      }
    } else if (typeof options === "object" || !options) {
      return this.each(function() {
        if (!$.data(this, 'plugin_' + pluginName)) {
          $.data(this, 'plugin_' + pluginName, new Plugin(this, options));
        }
      });
    }
  };

  $.fn[pluginName].defaults = {
    onInit: function() {},
    onDestroy: function() {}
  };

})(jQuery);

…and with liberal comments:

/**
 * A jQuery plugin boilerplate.
 * Author: Jonathan Nicol @f6design
 */
;(function($) {
  // Change this to your plugin name.
  var pluginName = 'demoplugin';

  /**
   * Plugin object constructor.
   * Implements the Revealing Module Pattern.
   */
  function Plugin(element, options) {
    // References to DOM and jQuery versions of element.
    var el = element;
    var $el = $(element);

    // Extend default options with those supplied by user.
    options = $.extend({}, $.fn[pluginName].defaults, options);

    /**
     * Initialize plugin.
     */
    function init() {
      // Add any initialization logic here...

      hook('onInit');
    }

    /**
     * Example Public Method
     */
    function fooPublic() {
      // Code goes here...
    }

    /**
     * Get/set a plugin option.
     * Get usage: $('#el').demoplugin('option', 'key');
     * Set usage: $('#el').demoplugin('option', 'key', value);
     */
    function option (key, val) {
      if (val) {
        options[key] = val;
      } else {
        return options[key];
      }
    }

    /**
     * Destroy plugin.
     * Usage: $('#el').demoplugin('destroy');
     */
    function destroy() {
      // Iterate over each matching element.
      $el.each(function() {
        var el = this;
        var $el = $(this);

        // Add code to restore the element to its original state...

        hook('onDestroy');
        // Remove Plugin instance from the element.
        $el.removeData('plugin_' + pluginName);
      });
    }

    /**
     * Callback hooks.
     * Usage: In the defaults object specify a callback function:
     * hookName: function() {}
     * Then somewhere in the plugin trigger the callback:
     * hook('hookName');
     */
    function hook(hookName) {
      if (options[hookName] !== undefined) {
        // Call the user defined function.
        // Scope is set to the jQuery element we are operating on.
        options[hookName].call(el);
      }
    }

    // Initialize the plugin instance.
    init();

    // Expose methods of Plugin we wish to be public.
    return {
      option: option,
      destroy: destroy,
      fooPublic: fooPublic
    };
  }

  /**
   * Plugin definition.
   */
  $.fn[pluginName] = function(options) {
    // If the first parameter is a string, treat this as a call to
    // a public method.
    if (typeof arguments[0] === 'string') {
      var methodName = arguments[0];
      var args = Array.prototype.slice.call(arguments, 1);
      var returnVal;
      this.each(function() {
        // Check that the element has a plugin instance, and that
        // the requested public method exists.
        if ($.data(this, 'plugin_' + pluginName) && typeof $.data(this, 'plugin_' + pluginName)[methodName] === 'function') {
          // Call the method of the Plugin instance, and Pass it
          // the supplied arguments.
          returnVal = $.data(this, 'plugin_' + pluginName)[methodName].apply(this, args);
        } else {
          throw new Error('Method ' +  methodName + ' does not exist on jQuery.' + pluginName);
        }
      });
      if (returnVal !== undefined){
        // If the method returned a value, return the value.
        return returnVal;
      } else {
        // Otherwise, returning 'this' preserves chainability.
        return this;
      }
    // If the first parameter is an object (options), or was omitted,
    // instantiate a new instance of the plugin.
    } else if (typeof options === "object" || !options) {
      return this.each(function() {
        // Only allow the plugin to be instantiated once.
        if (!$.data(this, 'plugin_' + pluginName)) {
          // Pass options to Plugin constructor, and store Plugin
          // instance in the elements jQuery data object.
          $.data(this, 'plugin_' + pluginName, new Plugin(this, options));
        }
      });
    }
  };

  // Default plugin options.
  // Options can be overwritten when initializing plugin, by
  // passing an object literal, or after initialization:
  // $('#el').demoplugin('option', 'key', value);
  $.fn[pluginName].defaults = {
    onInit: function() {},
    onDestroy: function() {}
  };

})(jQuery);

Usage

The first thing you’ll need to do is change the name of the plugin, which is hardcoded as ‘demoplugin’, to something a little more descriptive. After that you should be able to follow the comments in the source code to customise the plugin.

Here are examples of how an end-user would interact with the plugin:

// Initialize plugin with default options.
$('#element').demoplugin();

// Initialize plugin with user defined options.
$('#element').demoplugin({
  option1: 2000,
  option2: 'value',
  callback1: function () { ... }
});

// Call a public method, no arguments.
$('#element').demoplugin('publicFunctionName');

// Call a public method with arguments.
$('#element').demoplugin('publicFunctionName', 'arg1', 'arg2');

// Get a plugin option.
$('#element').demoplugin('option', 'key');

// Set a plugin option after plugin initialization.
$('#element').demoplugin('option', 'key', value);

// Destroy plugin.
$('#element').demoplugin('destroy');

Setup options

It is very useful to be able to customise jQuery plugins on a per instance basis. The boilerplate implements default settings which can be overwritten when the plugin is initialized:

// Default plugin options.
$.fn[pluginName].defaults = {
  color: '#ff0000',
  height: 200
};

$('#element').demoplugin({
  color: '#0000ff',
  height: 400
});

Options can also be overwritten after the plugin is initialized, using the option method:

$('#element').demoplugin('option', 'color', '#00ff00');

An option value can be fetched using the same method by simply omitting the third parameter:

var color = $('#element').demoplugin('option', 'color');

Public and private methods

Private functions reduce the chance of your users inadvertently calling the plugin’s utility methods. I’m a fan of the Revealing Module pattern, so that’s how I chose to implement private/public functionality in my boilerplate.

function Plugin(element, options) {
  // This method is public.
  function fooPublic(param1, param2) {
    // ...
  }

  // This method is private.
  function fooPrivate() {
    // ...
  }

  // Expose methods of Plugin we wish to be public.
  return {
    fooPublic: fooPublic
  };
}

Public functions can be called by your users like so:

$('#element').demoplugin('fooPublic', 'val1', 'val2');

Callback hooks

Callback hooks are incredibly powerful. They allow your users to listen for events in your plugin’s behaviour and respond accordingly. Hooks are implemented as functions in the default options object:

$.fn[pluginName].defaults = {
  onSlideshowFinished: function() {}
};

Each function is empty to begin with, since the callback’s behaviour will be defined by the user. This is done by overwriting the callback function when setting the plugin’s options. The scope of the callback is the DOM element the plugin is attached to, so in the following example the DOM element would be hidden.

$('#element').demoplugin({
  onSlideshowFinished: function() {
    $(this).hide();
  }
});

To trigger a hook, call the plugin’s hook method:

hook('onSlideshowFinished');

There are two callbacks implemented by default in the boilerplate: onInit and onDestroy.

Destroying a plugin instance

Your users can remove an instance of the plugin by calling its destroy method:

$('#element').demoplugin('destroy');

The plugin stores all its functionality in its DOM element’s data object. By default the destroy method simply removes the stored data values. You will probably need to customise destroy to restore the DOM element to its original state and remove any event handlers your plugin has created.

Credit

My boilerplate takes inspiration from a number of sources, most notably the jQuery plugin authoring guidelines, Stefan Gabos’ boilerplate, and Zeno Rocha and Addy Osmani’s jQuery Boilerplate.

• Better handling of checkbox results in the emailResults method.
• A custom form submit URL can be passed to the FormBuilder constructor. Useful when using FormBuilder in an environment that is performing URL rewriting.
• Replaced deprecated ergei functions with preg_match.
• Checkbox field types are correctly processed when field is not mandatory, and the user didn’t check any of the available options.
• Added new field type: file (for file uploads). Note that files are currently not emailed when using the emailResults method. Any handling of the uploaded files should be accomplished manually by accessing PHP’s $_Files array.
• The textbox and textarea field types now accept an optional defaultvalue parameter.
• Fixed a bug that meant checkboxes had a CSS class of ‘fbheckbox’ instead of ‘fbcheckbox’.

If you encounter any problems with the new version please let me know.

PHP example:

HTML example:

CSS example:

JavaScript example:

I’m not sure who designed the Monokai theme originally, but it has cropped up in Textmate, Notepad++, Sublime – where it is the default colour scheme – and no doubt a bunch of other editors as well.

My version of Monokai is based on a Notepad++ theme, but I have standardised the color of variables (green) and symbols (white) across all the languages.

I don’t actually use phpDesigner much these days – I’ve jumped ship for Aptana Studio 3 – but I still think it is a great code editor, and hopefully someone out there will get some use from my theme.

Download

Download Monokai theme for phpDesigner

Installation and uninstallation instructions are included with the theme. The theme has syntax highlighting colors for the four languages I work with: HTML, CSS, JavaScript and PHP.

Important

There is currently a bug in phpDesigner that sometimes causes the ‘separator’ colors to revert to their defaults (e.g. the color of tags reverts to black). The only sure-fire way to get things back to normal is to open the phpDesigner preferences dialog, and click ‘OK’.

Apparently this bug will be fixed in the next release of phpDesigner (yay!).

When I switched back to phpDesigner, the default blue-on-white color scheme seemed a tad boring, so I decided it was time to pimp my IDE! Unfortunately user created themes for phpDesigner are thin on the ground, which left me no option but to make my own.

PHP example:

HTML example:

CSS example:

JavaScript example:

I’ve named my theme Sunset, and it is inspired by the Midnight theme for SyntaxHighlighter. If any phpDesigner fans are looking for a light-on-dark color scheme to spruce up their code editor, perhaps Sunset will fit the bill.

Download

Download Sunset theme for phpDesigner

Installation and uninstallation instructions are included with the theme. Currently the theme has syntax highlighting colors for the four languages I work with: HTML, CSS, JavaScript and PHP.

Important

There is currently a bug in phpDesigner that sometimes causes the ‘separator’ colors to revert to their defaults (e.g. the color of <?php ?> tags reverts to black). The only sure-fire way to get things back to normal is to open the phpDesigner preferences dialog, and click ‘OK’. You might also try closing all your open documents and restarting the application. Hopefully this bug will be fixed in a future version of phpDesigner.

If you work with Flash at all, by now you will have heard of Papervision 3D, the open source project that has turned the Flash world on its head by introducing a 3rd dimension. I had a quick play with Papervision 3D a few months ago and found it surprising easy to pick up. It is now in public beta so I decided to dust off my old project and rewrite it in Actionscript 3.

3D image gallery demo

Inspired by Antti Kupila’s stunning 3D interface for last.fm, I created a simple gallery of album covers using Papervision 3D. For the reflections of the album covers I have used Pixelfumes’ Reflection class.

View demo

View my 3D image gallery

Download source

If you’re curious to see how I put this demo together, take a look at my Flash source files.

Using Papervision 3D

The biggest challenge for me was porting my code to Actionscript 3, as it was the first time I had written AS3 code. But as far as Papervision 3D itself, it really is a piece of cake to get your head around. The documentation that comes with Papervision 3D is a bit hard to follow, but if you download the zipped version of Papervision 3D from Google Code it contains a bunch of great examples which help to introduce the basic concepts.

The cool thing about Papervision is how it can be adapted to all kinds of 3D applications. My main interest is in the possibilities for creating 3D application interfaces, but people have also created 3D games, models and animations. Expect to see a lot more 3D Flash in the next couple of years!

Download

Download Photoshop CS2 file

How to use it

Here is some simple CSS styling you can use to turn an ordinary link into a spiffy looking file download button.

The HTML:

<p class="fileDownload">
    <a href="myfile.pdf">Download Annual Report (PDF 120Kb)</a>
</p>

The CSS:

.fileDownload {
    background: transparent url(file_icon.gif) no-repeat left top;
    display: block;
    height: 35px;
    padding-left: 36px;
}

The final result:

Download Annual Report (PDF 120Kb)

Next up I will be adding functionality so that the submitted form variables can be emailed to any address. Stay tuned…

FormBuilder features

FormBuilder is designed to do make building forms simple. It can do pretty much everything you might want to achieve with a typical HTML form:

• Create HTML forms by entering a few PHP values
• Generates XHTML 1.0 Strict compliant markup
• Fully skinnable via CSS
• Rigorous and flexible form validation on a per-field basis
• Displays easy to understand error messages to the user
• Highlights required fields and fields that are in error
• Automatically send form results to any email address
• Displays a ‘thanks’ message once form is successfully processed
• Hide or show HTML content based on whether the form was successfully submitted
• Ability to add your own custom form validation after FormBuilder has completed its own validation pass
• Protect against PHP header injection

Demo and download

I put together a demo page that shows FormBuilder in action. Try filling out the form incorrectly to see examples of FormBuilder’s error messaging.

View FormBuilder demo
Demonstrates default FormBuilder setup.

View FormBuilder ‘pretty’ demo
Demonstrates the showDividers and usePseudoLegends options. These make your forms easier to style but less semantic.

Download FormBuilder (current version is v1.5)

Important: FormBuilder is a work in progress, so I can’t promise it’s completely bug free. Feedback, suggestions and bug reports are welcomed: leave a comment below.

How the heck do I use this thing?

You should be able to get a pretty good idea how FormBuilder works just by looking at the source code of index.php in the download package. If you want to dig a little deeper I included a text file with the package that documents all aspects of the class and how to use it. And if you’re still scratching your head feel free to post a comment below.

Requirements

FormBuilder must be run on a web server with PHP 4+ running (I’ve tested under both PHP4 and PHP5). A basic understanding of PHP is helpful, but if you follow the examples provided in the documentation you might be able to make do without. CSS knowledge is required if you want to change the appearance of the form.

AJAX validation

Over at roScripts there is a nice tutorial explaining how to modify FormBuilder so that validation is performed unobtrusively using AJAX.

Changelog

Version 1.5

• Better handling of checkbox results in the emailResults method.
• A custom form submit URL can be passed to the FormBuilder constructor. Useful when using FormBuilder in an environment that is performing URL rewriting.
• Replaced deprecated ergei functions with preg_match.
• Checkbox field types are correctly processed when field is not mandatory, and the user didn’t check any of the available options.
• Added new field type: file (for file uploads). Note that files are currently not emailed when using the emailResults method. Any handling of the uploaded files should be accomplished manually by accessing PHP’s $_Files array.
• The textbox and textarea field types now accept an optional defaultvalue parameter.
• Fixed a bug that meant checkboxes had a CSS class of ‘fbheckbox’ instead of ‘fbcheckbox’.

Version 1.4

• Added emailResults function, which automatically emails the form variables to any email address

Version 1.3

• Added new field type: password
• Added new field type: hidden

Version 1.2

• By default there is no longer an empty dd after each form field, which makes FormBuilder’s markup more semantic. The empty dd's provide a handy element for styling visual dividers between fields, so you can still reveal them using the new showDividers parameter in the FormBuilder constructor.
• Introduced usePseudoLegends parameter. If set to true, legend will be replaced with h3. The HTML legend element is notoriously difficult to style consistently, and this parameter provides a workable alternative.
• Cleaned up the demo CSS styles, including getting dividers displaying properly in Safari.

Version 1.1

• Checkboxes and radio buttons are now correctly marked up inside label tags
• Labels are now associated with the relevant form field via the for attribute

Credit where credit is due

FormBuilder uses validaForms by Erick Vavretchek for form validation. Please see the validaForms PHP Classes package if you wish to learn more about this excellent from validator.