Creating jQuery Mobile Plugins

We encourage developers to create a rich ecosystem of 3rd party plugins to enhance the capabilities of the framework. All the UI widgets in jQuery Mobile are decoupled from the library so they are built just like any 3rd party plugin so review the code for a plugin to see how it all comes together.

Here are a few important things to include:

• Widget factory - all the internal widgets use the jQuery UI widget factory and it provides a clear template for organizing your code and automatically does things like exposing all options as data attributes so they are consistent with the rest of the library.

• Auto initialization - to add your plugin to a jQuery Mobile page, it should be as easy as including the JS plugin file and the structural CSS file to the head of the page and it should "just work". To make auto initialization possible, bind to both pagecreate and create events and call your plugin on markup that matches the markup convention of data-role attribute you're using to enhance the widget by registering the initSelector option.

• Namespacing - all plugins should work with namespaced data attributes. There is a global config option that makes it easy for people to add a namespace to all data- attributes so test to ensure that your plugin will work both with data-role="foo" and data-mynamespace-role="foo"

• Theme framework - follow how our plugins work where they have structural styles that don't ever set bg colors, font colors, etc. so the theme will flow through. Apply the stackable theme framework classes to apply the theme to your widget. In your widget, have it inherit the swatch from the parent if not set as a data attribute. Test your widgets with both the default and custom themes to ensure they are properly themable.

• Semantics - use HTML5 markup for better semantics and native markup-driven ways of setting configuration data. For example, to build a progress bar widget, use the HTML5 progress element. Then your plugin can look for this element on a page and parse out the attributes to configure itself. In this case, you can set the max and current values using native attributes and add data- attributes for the others. In some cases, you may want to hide the original element if it's replaced by a new widget that uses custom markup.

• Accessibility - always test to ensure that the widget incorporates accessibility features like ARIA attributes and is tested on screen readers like VoiceOver on iOS.

• Unit tests - having solid test coverage for all your plugins is essential. We use Qunit for all unit tests and you can see tests in action in the test suite