jQuery.ui.ThemeSwitcher
sam@rbe.homeip.net
by Skaman Sam Tylerbased 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[]
anddisableThemes[]
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()
, andonSelect()
now pass in a reference to the ThemeSwitcher widget. - enhancement #4868. Added the
cookieOptions
option. This will allow you to pass options directly to thejQuery.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 firingonSelect()
at initialization - feature #4196. Added the
isThemeable
option to allow theming of the widget itself.
TODO
- Implement
refresh()
to refresh the list. PossiblyaddTheme()
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 usebind()
(already usestrigger()
)
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.