/jquery-ui-themeswitcher

Rewrite of jquery ThemeSwitcher. Now a ui.widget!

Primary LanguageJavaScript

jQuery.ui.ThemeSwitcher

by Skaman Sam Tyler sam@rbe.homeip.net

based on themeswitchertool by Jason Lau

ThemeSwitcher is a jQuery UI widget which displays a list of UI themes with previews. It is a rewrite of the jQuery themeswitchertool found at http://jqueryui.com/docs/Theming/ThemeSwitcher.

Features / Changes

  • Uses the jQuery UI widget factory. This makes the tool an actual widget, instead of just a jQuery plugin.
  • Removed a few unnecessary elements that were generated by the original script
  • Now uses a stylesheet instead of inline styles
  • Auto-detects current theme. Disable feature using autDetect:false option
  • Enable/Disable certain themes. See enableThemes[] and disableThemes[] options
  • Enabled custom theme support.
  • Addresses all the issues listed on the jQuery Trac which relate to the themeswitchertool (see Bugs Fixed)
  • Tested in Chrome 10+, Opera 10+, Firefox 3.6+

Bugs Fixed

  • bug #6991. Since the tool is now a widget, it should be more friendly with other libraries that use the $ function. However, this has not been tested yet.
  • bug #5548. Added the ability to specify themes not listed on the jQuery UI gallery (i.e. your own custom theme)
  • enhancement #5306. Handlers for onClose(), onOpen(), and onSelect() now pass in a reference to the ThemeSwitcher widget.
  • enhancement #4868. Added the cookieOptions option. This will allow you to pass options directly to the jQuery.cookie plugin. The options are: expires, path, domain, secure
  • enhancement #4713. Added the useCookie option.
  • enhancement #4715. Added the useStandard option to specify whether to use the Gallery themes
  • enhancement #4715. Added the disableTheme option to specify which Gallery themes to disable.
  • enhancement #4714. Added the selectOnStart option to dis/enable firing onSelect() at initialization
  • feature #4196. Added the isThemeable option to allow theming of the widget itself.

TODO

  • Implement refresh() to refresh the list. Possibly addTheme() to append to list without refreshing the whole list
  • Implement option sort:true to sort list of themes by name
  • Test in IE6+ and on non-Linux machines
  • Figure out why onSelect, onClose, onOpen cannot use bind() (already uses trigger())

Examples

Basic Usage: $('#theme-switcher').themeswitcher({ imageLocation:"css/images/" }); Make the Theme Switcher use the current jQuery UI Theme $('#theme-switcher').themeswitcher({ imageLocation:"css/images/", isThemable:true }); Add A Custom Theme $('#theme-switcher').themeswitcher({ themes:{ 'My Theme':{ icon:'css/mytheme/mytheme.png', css:'css/mytheme/jquery-ui-1.8.9.custom.css' } }, imageLocation:"css/images/" }); Add ONLY A Custom Theme $('#theme-switcher').themeswitcher({ themes:{ 'My Theme':{ icon:'css/mytheme/mytheme.png', css:'css/mytheme/jquery-ui-1.8.9.custom.css' } }, useStandard:true, imageLocation:"css/images/" }); Add A Custom Theme and ignore several Gallery Themes $('#theme-switcher').themeswitcher({ themes:{ 'My Theme':{ icon:'css/mytheme/mytheme.png', css:'css/mytheme/jquery-ui-1.8.9.custom.css' } }, imageLocation:"css/images/", disableThemes:['ui-lightness','base','le-frog'] }); Add A Custom Theme and use ONLY several Gallery Themes $('#theme-switcher').themeswitcher({ themes:{ 'My Theme':{ icon:'css/mytheme/mytheme.png', css:'css/mytheme/jquery-ui-1.8.9.custom.css' } }, imageLocation:"css/images/", enableThemes:['My Theme','ui-lightness','base','le-frog'] });

Add Custom callbacks $('#theme-switcher').themeswitcher({ imageLocation:"css/images/", onSelect:function(obj){$('#eventLog').append('<br/>onSelect() fired: '+obj.themeName)}, onOpen:function(obj){$('#eventLog').append('<br/>onOpen() fired: '+obj.themeName)}, onClose:function(obj){$('#eventLog').append('<br/>onClose() fired: '+obj.themeName)} }); eventLog: <div id="eventLog"></div>

Options

loadTheme: null The theme name to select when starting up

initialText: 'Switch Theme' The initial text of the button

height: null, width:null` The width and height of the button

pHeight: null, pWidth:null The width and height of the panel

buttonPreText: 'Theme: ' The button text that comes before the theme name when the theme is applied

closeOnSelect: true Whether to close the chooser when an itme is selected.

cookieName: 'jquery-ui-theme' The name of the cookie when using cookies

onOpen: function(event,obj) {}, onClose: function(event,obj) {} The function to call when the selector is open/closed. The themeswitcher object is passed to it.

onSelect: function(event,obj) {} The function to call when a theme is selected. The themeswitcher object is passed to it.

useStandard: true Whether to use the standard Gallery listed on the jQuery site. The theme hash is located in the getStandard() method, so you can obtain the list and modify it at runtime.

cssPrefix: "http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.10/themes/", cssSuffix: "/jquery-ui.css" Used for locating the standard themes. The full path is evaluated as cssPrefix + themeName + cssSuffix

imgPrefix: "http://static.jquery.com/ui/themeroller/images/themeGallery/theme_90_", imgSuffix: ".png" How to locate the icons for each theme. The pattern is imgPrefix + themeName + imgSuffix

imageLocation:"/javascripts/jquery/themeswitcher/" Where the images are that are part of the button. This probably needs to be part of the CSS file.

themes:{} A list of themes you want to add to the list. The hash is in the form: 'themeName':{icon:'path/to/icon.png',css:'path/to/css/file.css'} If either option is not given, the location of the icon is: imgPrefix+themeName+imgSuffix, and the location of the css file is cssPrefix+themeName+cssSuffix

useCookie: true Set to false to disable the saving of state

cookieFunction:function(themeName){} Use this function instead of the default cookie function. Using this, you can save/restore from a server instead of a cookie.

cookieOptions: {} Pass in these options to the cookie. Options are: path,domain,secure,expires

disableThemes: [] List of themes to disable. Warning:giving the name of your custom theme will make it not show up in the list.

enableThemes: [] List of themes to enable. This is the opposite of disableThemes[]. Warning:giving NOT the name of your custom theme will make it not show up in the list.

selectOnStart: true Whether or not to call the onSelect() method during the widget's initialization.

isThemable: false Whether or not to use jQuery UI themes for the switcher. If enabled, it will look like a ui.button.

autoDetect: true Whether to auto-detect which theme is currently active. Only used during initialization and if loadTheme is not set.