Easy Widgets jQuery plugin

What is Easy Widgets?

After I read How to Mimic the iGoogle Interface tutorial, I think that is a very simple way to use Widgets in one of my projects: Gesbit, you can see here a demo. I study the tutorial code and want to put into a jQuery plugin. After some work I finally use this plugin in Gesbit and think that maybe can be useful for other developers.

The plugin as been tested in last version of Firefox, Opera, Internet Explorer, Safari, Konqueror and Chrome browsers. Please try the examples for more details.

I want just the code now!

Is useful for you?

Thanks very much!

Plugin requisites

In order to use this plugin you need the jQuery library and the jQuery UI with sortable and draggable stuff.

Who use this plugin?

You can view an implementation of this plugin in Gesbit, a Weblog Management System writen by me. See the Gesbit demo for details.

Another uses cases

I know that this websites using EasyWidgets plugin. Look diferent cases of use in this websites.

Thanks very much for the people that choose EasyWidgets!

I can view some examples please?

Yes. Here is various examples of use of Easy Widgets plugin:

Amazing! Can you explain more?

Easy Widgets offer you over the control about your Widgets, and this is the very basic usage of the plugin, using the default settings, that we explain bello in this same page.

// When DOM ready

$(function(){

  // Prepare the Widgets

  $.fn.EasyWidgets();

});

The HTML markup of Widgets

The plugin is not obstrusive, and degrade gracefully. You are responsible for print out the HTML markup of the Widgets places and Widgets. I am use a couple of PHP class in Gesbit to do this, but, the fact is that you must write something like this:

In the above example, we print two Widgets places and one Widget, that can be place in one of the places. Take a look at the class identifiers: you can change this from the Easy Widgets settings, but we use here the HTML markup corresponding to the default plugin settings.

You can determine what number of places are availables: no limit here, and no limit about the number of Widgets that can be places in the places. Now we want to explain you how can configure a Widget, using the HTML markup too, in a easy way, just like this:

In the case of the above Widget, this is collapse by default, movable, editable, collapsable, removable and want to confirm when must be close. You can use anyone of the Widget options, a combination of this or no one. In fact, you can determine too the name of the options, because this form part of the Easy Widgets settings.

Here we use "DIV" container to store Widgets, but you can use another container like "LI", simply change a configuration option (the default container is "DIV") and you can print out something like this:

As you can see, the fact is the Widgets need a place to be store, an this place can be a container like "DIV" or "UL" in this case. So, every Widget is added in their own container, that can be "DIV" or "LI", depend of your needed, but using "DIV" per default. As you can see, every Widget contain some subsections: header, editbox and content.

The header contain the title of the Widget and Easy Widgets put in every Widget headers the appropiate menu links to collapse, remove, edit the Widget, etc., depend of the Widget options. The content of the Widgets is the content of the Widget, ok? And the editbox can contain a HTML form to edit the Widget, for example, and can show by the appropiate link in the menu links header.

This is the elements of a Widgets places and for the Widgets: remember that is possible to use any number of places or Widgets. And note that we not use here "identifiers" for the Widgets, that can be useful and maybe needed, for example, if you want to use the Cookies feature of Easy Widgets. In other words maybe is needed (or simply useful) to write something like this, but is optional in any case.

The CSS style of the Widgets

This is a good point, because the Widgets can be stylize with the only limit of your imagination. Here is the default CSS rules, with the selectors names using by default in the plugin (remember that you can change this too).

As you can see some little rules is using. But all that we needed for use the plugin from scratch. You can add more rules, change the style of the exists rules, we said, with the only limit of your imagination.

Plugin internationalization

You can translate the used Easy Widgets strings in a easy way, use the appropiate option in the plugin settings. In fact you can use this options to use images instead text in the Widget header menu links, as you can see in some of the above plugin examples.

As you see, you can determine the language to use in the Widgets plugin with the "i18n" configuration settings, so, if you want to use images instead links, you can put the HTML of a image in the appropiate link text.

Plugin optional cookies

Easy Widgets can be responsible for the position of the Widgets into the places, the collapse state of the Widgets, for example. You can determine to use cookies for this and can determine all about the cookies, take a look at the default "cookies" settings for Easy Widgets:

However, by default the plugin not use cookies, because as you can see bellow, you can determine how the Widgets is showing using the HTML markup, and some server stuff. But, if you want to use cookies, you can use the appropiate option in the "behaviour" settings of the plugin.

Plugin optional behaviour

Easy Widgets have some behaviour settings that you can change for your needs:

Maybe the most relevant option in the behaviour settings is "useCookies". If you use cookies, the plugin can be responsible for store the Widgets positions and collapse and closed states, and of course the maintenence of this cookies, fixed this when a Widget is no more use, for example. In other words, the Widget store in cookies the position for a Widget, for example, and after you not print anymore this Widget: the plugin can detect this situation and clean the appropiate cookie to no store unexisting Widgets.

Plugin optional effects

The plugin can apply certain effects when occurr some events:

The effects is none by default: the plugin hide or show the widget sections only. But you can specify "slide" or "fade" effects, for example, and the plugin apply this when is needed.

Plugin optional callbacks

Easy Widgets allow to handle a lot of task in the Widget via callbacks that you can attach to the appropiate configuration settings, here is all of the available Easy Widgets callbacks:

Plugin public methods

You have this public methods to use in your Widgets. For more information we refer you to the plugin source code. But here is a little descriptions.

Note something: Many of this methods can be supplied if you use jQuery directly. The goal of this mehods is that can be deal with the appropiate cookies. So, if you not use the plugin cookies feature, you can hide all widgets with: $('.widget).hide() code, for example, instead of use the appropiate plugin public method.

EasyWidgets: This is the main method of the plugin. You can use when the DOM are ready to initialize the Widgets.
AddEasyWidget: This method permit you to add new Widgets on demand in a page. Setup the HTML, decide the Widget place and simply use this method.
HideEasyWidget: Hide some visible Widget based in their identifier. This method also apply the appropiate changes in the cookies related, in case that you use this.
HideEasyWidgets: Hide all visible Widgets. This method also apply the appropiate changes in the cookies related, in case that you use this.
ShowEasyWidget: Show some hidden Widget based in their identifier. This method also apply the appropiate changes in the cookies related, in case that you use this.
ShowEasyWidgets: Show all hidden Widgets. This method also apply the appropiate changes in the cookies related, in case that you use this.
EnableEasyWidgets: Enable all Widgets, that is, permit that this can be movable by the user. This method also apply the appropiate changes in the cookies related, in case that you use this.
DisableEasyWidgets: Disable all Widgets, in other words, not permit that this can be movable by the user. This method also apply the appropiate changes in the cookies related, in case that you use this.

Give me all the power!

As you can see, the Easy Widgets plugin can be use without any option, using the default settings, but you can determine all the plugin stuff, between the Widget container, CSS selectors to use, option name, string to use, etc., etc. Here is all the default settings of the plugin, that you change if needed, but can use directly too, or change somethings, whatever you want:

/**
   * Default plugin settings
   *
   * Here we initialize the plugin default settings, that can be overwrite
   * when the user call to plugin public methods. In every case we merge this
   * settings with the user provided, to obtain in any case correct values.
   *
   */
  $.fn.EasyWidgets.defaults = {

// Behaviour of the plugin
    behaviour : {

// Miliseconds delay between mousedown and drag start
      dragDelay : 100,

// Miliseconds delay between mouseup and drag stop
      dragRevert : 100,

// Determinme the opacity of Widget when start drag
      dragOpacity : 0.8,

// Use cookies to store positions and states
      useCookies : false
    },

// Some effects that can be apply sometimes
    effects : {

// Miliseconds for effects duration
      effectDuration : 500,

// Can be none, slide or fade
      widgetShow : 'none',
      widgetHide : 'none',
      widgetClose : 'none',
      widgetExtend : 'none',
      widgetCollapse : 'none',
      widgetOpenEdit : 'none',
      widgetCloseEdit : 'none',
      widgetCancelEdit : 'none'
    },

// Only for the optional cookie feature
    cookies : {

// Cookie path
      path : '',

// Cookie domain
      domain : '',

// Cookie expiration time in days
      expires : 90,

// Store a secure cookie?
      secure : false,

// Cookie name for close Widgets
      closeName : 'ew-close',

// Cookie name for enable/disable Widgets
      disableName : 'ew-disable',

// Cookie name for positined Widgets
      positionName : 'ew-position',

// Cookie name for collapsed Widgets
      collapseName : 'ew-collapse'
    },

// Options name to use in the HTML markup
    options : {

// To recognize a movable Widget
      movable : 'movable',

// To recognize a editable Widget
      editable : 'editable',

// To recognize a collapse Widget
      collapse : 'collapse',

// To recognize a removable Widget
      removable : 'removable',

// To recognize a collapsable Widget
      collapsable : 'collapsable',

// To recognize Widget that require confirmation when remove
      closeConfirm : 'closeconfirm'
    },

// Callbacks functions
    callbacks : {

// When a Widget is added on demand, send the widget object and place ID
      onAdd : null,

// When a editbox is closed, send the link and the widget objects
      onEdit : null,

// When a Widget is show, send the widget object
      onShow : null,

// When a Widget is hide, send the widget object
      onHide : null,

// When a Widget is closed, send the link and the widget objects
      onClose : null,

// When Widgets are enabled using the appropiate public method
      onEnable : null,

// When a Widget is extend, send the link and the widget objects
      onExtend : null,

// When Widgets are disabled using the appropiate public method
      onDisable : null,

// When a editbox is closed, send a ui object, see jQuery::sortable()
      onDragStop : null,

// When a Widget is collapse, send the link and the widget objects
      onCollapse : null,

// When a Widget is try to added, send the widget object and place ID
      onAddQuery : null,

// When a editbox is try to close, send the link and the widget objects
      onEditQuery : null,

// When a Widget is try to show, send the widget object
      onShowQuery : null,

// When a Widget is try to hide, send the widget object
      onHideQuery : null,

// When a Widget is try to close, send the link and the widget objects
      onCloseQuery : null,

// When a editbox is cancel (close), send the link and the widget objects
      onCancelEdit : null,

// When Widgets are enabled using the appropiate public method
      onEnableQuery : null,

// When a Widget is try to expand, send the link and the widget objects
      onExtendQuery : null,

// When Widgets are disabled using the appropiate public method
      onDisableQuery : null,

// When a Widget is try to expand, send the link and the widget objects
      onCollapseQuery : null,

// When a editbox is try to cancel, send the link and the widget objects
      onCancelEditQuery : null,

// When one Widget is repositioned, send the positions serialization
      onChangePositions : null,

// When Widgets need repositioned, get the serialization positions
      onRefreshPositions : null
    },

// Selectors in HTML markup. All can be change by you, but not all is
    // used in the HTML markup. For example, the "editLink" or "closeLink"
    // is prepared by the plugin for every Widget.
    selectors : {

// Container of a Widget (into another element that use as place)
      // The container can be "div" or "li", for example. In the first case
      // use another "div" as place, and a "ul" in the case of "li".
      container : 'div',

// Class identifier for a Widget
      widget : '.widget',

// Class identifier for a Widget place (parents of Widgets)
      places : '.widget-place',

// Class identifier for a Widget header (handle)
      header : '.widget-header',

// Class for the Widget header menu
      widgetMenu : '.widget-menu',

// Class identifier for Widget editboxes
      editbox : '.widget-editbox',

// Class identifier for Widget content
      content : '.widget-content',

// Class identifier for editbox close link or button, for example
      closeEdit : '.widget-close-editbox',

// Class identifier for a Widget edit link
      editLink : '.widget-editlink',

// Class identifier for a Widget close link
      closeLink : '.widget-closelink',

// Class identifier for Widgets placehoders
      placeHolder : 'widget-placeholder',

// Class identifier for a Widget collapse link
      collapseLink : '.widget-collapselink'
    },

// To be translate the plugin into another languages
    // But this variables can be used to show images instead
    // links text, if you preffer. In this case set the HTML
    // of the IMG elements.
    i18n : {

// Widget edit link text
      editText : 'Edit',

// Widget close link text
      closeText : 'Close',

// Widget extend link text
      extendText : 'Extend',

// Widget collapse link text
      collapseText : 'Collapse',

// Widget cancel edit link text
      cancelEditText : 'Cancel',

// Widget edition link title
      editTitle : 'Edit this widget',

// Widget close link title
      closeTitle : 'Close this widget',

// Widget confirmation dialog message
      confirmMsg : 'Remove this widget?',

// Widget cancel edit link title
      cancelEditTitle : 'Cancel edition',

// Widget extend link title
      extendTitle : 'Extend this widget',

// Widget collapse link title
      collapseTitle : 'Collapse this widget'
    }
  };

Now, please, see the plugin examples, enjoy it, test the plugin, change the default options, apply some style to the Widgets, in fact, enjoy Easy Widgets plugin and thanks a lot for your interest!