theming-api.txt

[[UI/Theming|« Back to jQuery UI Theming]]
==The jQuery UI CSS Framework==

jQuery UI includes a robust CSS Framework designed for building custom jQuery widgets. The framework includes classes that cover a wide array of common user interface needs, and can be manipulated using jQuery UI ThemeRoller. By building your UI components using the jQuery UI CSS Framework, you will be adopting shared markup conventions and allowing for ease of code integration across the plugin community at large.

==Framework Classes==

The following CSS classes are split between ui.core.css and ui.theme.css, depending on whether styles are fixed and structural, or themeable (colors, fonts, backgrounds, etc) respectively. These classes are designed to be applied to User Interface elements to achieve visual consistency across an application and allow components to be themeable by jQuery UI ThemeRoller.

===Layout Helpers===
<ul>
    <li><strong>.ui-helper-hidden:</strong> Applies display: none to elements.</li>
    <li><strong>.ui-helper-hidden-accessible:</strong> Applies accessible hiding to elements (via abs positioning off the page)</li>
    <li><strong>.ui-helper-reset:&nbsp;</strong> A basic style reset for UI elements. Resets things such as padding, margins, text-decoration, list-style, etc.</li>
    <li><strong>.ui-helper-clearfix:</strong> Applies float wrapping properties to parent elements</li>
    <li><strong>.ui-helper-zfix:</strong> Applies iframe &quot;fix&quot; css to iframe elements when needed in overlays.</li>
</ul>

===Widget Containers===
<ul>
    <li><strong>.ui-widget:</strong> Class to be applied on outer container of all widgets. Applies font family and font size to widget. Also applies same family and 1em font size to child form elements specifically, to combat inheritance issues in Win browsers.</li>
    <li><strong>.ui-widget-header</strong>: Class to be applied to header containers. Applies header container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-widget-content:</strong> Class to be applied to content containers. Applies content container styles to an element and its child text, links, and icons. (can be applied to parent or sibling of header)</li>
</ul>

===Interaction States===
<ul>
    <li><strong>.ui-state-default:</strong> Class to be applied to clickable button-like elements. Applies &quot;clickable default&quot; container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-state-hover:</strong> Class to be applied on mouseover to clickable button-like elements. Applies &quot;clickable hover&quot; container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-state-focus:</strong> Class to be applied on keyboard focus to clickable button-like elements. Applies &quot;clickable hover&quot; container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-state-active:</strong> Class to be applied on mousedown to clickable button-like elements. Applies &quot;clickable active&quot; container styles to an element and its child text, links, and icons.</li>
</ul>

===Interaction Cues===
<ul>
    <li><strong>.ui-state-highlight:</strong> Class to be applied to highlighted or selected elements. Applies &quot;highlight&quot; container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-state-error:</strong> Class to be applied to error messaging container elements. Applies &quot;error&quot; container styles to an element and its child text, links, and icons.</li>
    <li><strong>.ui-state-error-text:</strong> An additional class that applies just the error text color without background. Can be used on form labels for instance. Also applies error icon color to child icons.</li>
    <li><strong>.ui-state-disabled:</strong> Applies a dimmed opacity to disabled UI elements. Meant to be added in addition to an already-styled element.</li>
    <li><strong>.ui-priority-primary:</strong> Class to be applied to a priority-1 button in situations where button hierarchy is needed. Applies bold text.</li>
    <li><strong>.ui-priority-secondary:</strong> Class to be applied to a priority-2 button in situations where button hierarchy is needed. Applies normal weight text and slight transparency to element.</li>
</ul>

===Icons===
====States and images====
<ul>
    <li>.ui-icon: Base class to be applied to an icon element. Sets dimensions to 16px square block, hides inner text, sets background image to &quot;content&quot; state sprite image. <em><strong>Note:</strong> <span style="font-family: Courier New;">.ui-icon</span> class will be given a different sprite background image depending on its parent container. For example, a <span style="font-family: Courier New;">ui-icon</span> element within a <span style="font-family: Courier New;">ui-state-default</span> container will get colored according to the <span style="font-family: Courier New;">ui-state-default</span>'s icon color.</em></li>
</ul>

====Icon types====

After declaring a ".ui-icon" class, you can follow up with a second class describing the type of icon you'd like. Icon classes generally follow a syntax of .ui-icon-{icon type}-{icon sub description}-{direction}.

For example, a single triangle icon pointing to the right looks like this:
.ui-icon-triangle-1-e

jQuery UI's [http://www.themeroller.com ThemeRoller] provides the full set of CSS framework icons in its preview column. Hover over them to see the class name.

===Misc Visuals===
====Corner Radius helpers====
<ul>
    <li><strong>.ui-corner-tl:</strong> Applies corner-radius to top left corner of element.</li>
    <li><strong>.ui-corner-tr:</strong> Applies corner-radius to top right corner of element.</li>
    <li><strong>.ui-corner-bl:</strong> Applies corner-radius to bottom left corner of element.</li>
    <li><strong>.ui-corner-br:</strong> Applies corner-radius to bottom right corner of element.</li>
    <li><strong>.ui-corner-top:</strong> Applies corner-radius to both top corners of element.</li>
    <li><strong>.ui-corner-bottom:</strong> Applies corner-radius to both bottom corners of element.</li>
    <li><strong>.ui-corner-right:</strong> Applies corner-radius to both right corners of element.</li>
    <li><strong>.ui-corner-left:</strong> Applies corner-radius to both left corners of element.</li>
    <li><strong>.ui-corner-all:</strong> Applies corner-radius to all 4 corners of element.</li>
</ul>

====Overlay &amp; Shadow====
<ul>
    <li><strong>.ui-widget-overlay:</strong> Applies 100% wxh dimensions to an overlay screen, along with background color/texture, and screen opacity.</li>
    <li><strong>.ui-widget-shadow:</strong> Class to be applied to overlay widget shadow elements. Applies background color/texture, custom corner radius, opacity, top/left offsets and shadow &quot;thickness&quot;. Thickness is applied via padding to all sides of a shadow that is set to match the dimensions of the overlay element. Offsets are applied via top and left margins (can be positive or negative).</li>
</ul>

theming-customthemes.txt

[[UI/Theming|« Back to jQuery UI Theming]]

If you'd like to create a custom theme, you can either start by modifying the default ui.theme.css file and the individual stylesheets for each plugin, or create a stylesheet from scratch. We'll walk you through how to create styles from scratch to create a custom look and feel that can't be achieved using the standard framework classes.


== Getting Started ==

To begin, grab a copy of jQuery UI if you haven't already and set up your environment. Create a blank CSS, give it a name, e.g. ui-theme.css, and link it up to your web app. Now open the [http://docs.jquery.com/UI/Theming/API Theming API] in a new browser window for reference.


== Best Practices ==

Themes should be non-intrusive and self encapsulating. To help achieve these goals the following practices are followed:

* All classes begin with the <code>.ui-</code> namespace.
* All styles are specific to the <code>.ui-</code> namespace.
* Inheritance begins with the component namespace. e.g. <pre>.ui-widget-dialog button</pre>
* Do not create global styles.
* Do not use the ID attribute for styling.
* Use hyphens, not underscores, as word separators.
* Always use lower case.

theming-themeroller.txt

<div id="theme-logo">
[[Image:RollerLogo_white.png]]
</div>
<br><br>
==About ThemeRoller==
ThemeRoller is a web app that offers a fun and intuitive interface for designing and downloading custom themes for jQuery UI. You can find ThemeRoller in the "Themes" section of the jQuery UI site, or by following this link: [http://themeroller.com/ jQuery UI ThemeRoller]

<div class="img-block">
[[Image:themeroller_interface_new.png ]]
[[Image:themeroller_gallery_new.png]]
</div>
<br/>

==The ThemeRoller Interface==
The interface for ThemeRoller is categorized into panels for global font and corner radius settings, widget container styles, and interaction states for clickable elements, and various styles for overlays and shadows. These panels allow configuration of various CSS properties such as font size, color, and weight, background color and texture, border color, text color, icon color, corner radius, and more!

==The Theme Gallery: Pre-Rolled Themes==
ThemeRoller themes can be viewed via permalink URLs, and it includes a gallery of pre-designed themes to choose from. The theme gallery is accessible through the tab strip located at the top of the application interface. From the gallery, you can preview and download themes, or even choose to tweak a theme further in the "Roll Your Own" tab.


==Downloading Themes==
When you're done designing a theme, you can download it for use in your projects. ThemeRoller has a "Download Theme" button at the top which will generate a ZIP file containing all of theme assets. Images included in your download will be generated to your specifications and saved as high-quality PNG files. 

Your theme will include images and CSS that make up a customized version of the jQuery UI CSS Framework including images and CSS for all of our plugins.

==Installing downloaded themes into your project==
Once the theme has been downloaded and unzipped, you will see a folder name <strong>jquery-ui-themeroller Folder</strong>. This folder contains a <strong>demo.html</strong> page that contains interactive examples of all the current UI widgets and a folder called <strong>/theme/</strong>. Copy the theme directory into your project and link to the themes/all.css file from your pages.

==Building Custom "ThemeRoller-Ready" Components==
<div class="img-block">
[[Image:Themeroller_ready_black_200px.png]]
[[Image:Themeroller_ready_white_200px.png]]
</div>
<br><br>
ThemeRoller generates a customized version of the jQuery UI CSS Framework for developing your own ThemeRoller-Ready jQuery components. The classes generated by this framework are designed to accommodate common user interface design situations and include states, icons, and various helper classes as well.

For information on developing with the jQuery UI CSS Framework, visit our [[UI/Theming/API|Theming API documentation]].

==ThemeRoller Links==
* [http://www.filamentgroup.com/lab/developer_your_own_jquery_themeroller_ready_components/ Tutorial: Develop Your Own jQuery “ThemeRoller-Ready” Components, Filament Group]
* [http://www.filamentgroup.com/lab/introducing_themeroller_design_download_custom_themes_for_jquery_ui/ Introducing ThemeRoller: Design & Download Custom Themes for jQuery UI, Filament Group]
* [http://www.dizi-izle-film-izle.net Videos about Design & Download Custom Themes for jQuery UI, Filament Group]

==Credits==
ThemeRoller was designed and developed for jQuery UI by [http://www.filamentgroup.com Filament Group, Inc], of Boston, MA.

theming-themerollerready.txt

[[UI/Theming|« Back to jQuery UI Theming]]

As external jQuery plugins and even static site templates start using the new jQuery UI CSS framework classes, we'll add them here.

<ul>
<li>
[http://www.trirand.com/jqgrid35/jqgrid.html jqGrid - jQuery Grid Plugin]
</li>

<li>
[http://www.nicolas.rudas.info/jQuery/Finder/v0.6a/ Apple Finder column style browser] - Nicolas Rudas
</li>

<li>
[http://www.filamentgroup.com/lab/styling_buttons_and_toolbars_with_the_jquery_ui_css_framework/ Tutorial: Styling Buttons and Toolbars with the jQuery UI CSS Framework] - Filament Group
</li>

<li>
[http://www.filamentgroup.com/lab/date_range_picker_using_jquery_ui_16_and_jquery_ui_css_framework Date Range Picker using jQuery UI 1.6 and jQuery UI CSS Framework]  - Filament Group
</li>

<li>
[http://www.filamentgroup.com/lab/update_jquery_ui_slider_from_a_select_element_now_with_aria_support/ jQuery UI 1.7 Slider from a Select Element with ARIA Support]  - Filament Group
</li>

<li>
[http://jqueryplugins.weebly.com jQuery.sheet - a web-based spreadsheet]
</li>

<li>
[http://dowdybrown.com/dbprod/rico3/demo/ Rico 3.0 with ThemeRoller themes]  - Open Rico
</li>

<li>
[http://www.quasipartikel.at/multiselect/ Sortable Multi-Select Plugin]  - Michael Aufreiter
</li>

<li>
[http://www.filamentgroup.com/lab/using_multiple_jquery_ui_themes_on_a_single_page/ Tutorial: Using Multiple jQuery UI Themes on a Single Page] - Filament Group
</li>

<li>
[http://pttimeselect.sourceforge.net/example/index.html jQuery.ptTimeSelect: Time picker Plugin] - Purtuga.com
</li>

<li>
[http://keith-wood.name/themes.html ThemeRoller Theme Picker Plugin] - Keith Wood
</li>

<li>
[http://www.filamentgroup.com/lab/jquery_ipod_style_and_flyout_menus jQuery Menu: Dropdown, iPod Drilldown, and Flyout styles with ARIA Support] - Filament Group
</li>

<li>
[http://static.imexis.net/scripts/jquery-tagwidget/0.9.6/demo/ jQuery.TagWidget Multiple Select Tag List Builder Plugin] - Imexis
</li>

</ul>

theming.txt

== Theming jQuery UI ==

All jQuery UI plugins are designed to allow a developer to seamlessly integrate UI widgets into the look and feel of their site or application. Each plugin is styled with CSS and contains two layers of style information: standard [http://docs.jquery.com/UI/Theming/API jQuery UI CSS Framework] styles and plugin-specific styles. 

The jQuery UI CSS Framework provide semantic presentation classes to indicate the role of an element within a widget such as a header, content area, or clickable region. These are applied consistently across all widgets so a clickable tab, accordian or button will all have the same "ui-state-default" class applied to indicate that it is clickable. When a user mouses over one of these elements, this class is changed to ui-state-hover, then ui-state-active when selected. This level of class consistency makes it easy to ensure that all elements with a similar role or interaction state will look the same across all widgets.

The CSS Framework styles are encapsulated in a single file called ui.theme.css and this is the file modified by the [[UI/Theming/Themeroller|ThemeRoller]] application. Framework styles only include attributes that affect the look and feel (primarily color, background images and icons) so these are 'safe' styles that will not affect functionality of individual plugins. This separation means that a developer can create a custom look and feel by modifying the colors and images in theme.css file and know that as future plugins or bug fixes become available, these should work with the theme without modification.

Since the framework styles only cover look and feel, plugin specific stylesheets are included that contain all the additional structural style rules required to make the widget functional, such as dimensions, padding, margins, positioning and floats. Stylesheets for each plugin are located in the themes/base folder of the download and are named to match the plugin such as "jquery.ui.accordion.css". These styles must be carefully edited because they work in conjunction with the scripting and provide overrides of framework styles as needed. 

We encourage all developers creating jQuery plugins to leverage the jQuery UI CSS Framework because it will make it much easier for end users to theme and use your plugin.

== Getting started ==

There are three general approaches to theming jQuery UI plugins:

<ul>
  <li>'''Download a ThemeRoller theme''': The easiest way to build a theme is to use the [http://docs.jquery.com/UI/Theming/Themeroller ThemeRoller] to generate and download a theme. This app will create a new ui.theme.css file and and images directory containing all necessary background images and icon sprites which can simply be dropped into your project. This approach will be the easiest to create and maintain but limits customization to the options provided in ThemeRoller.</li>
  <li>'''Modify the CSS files''': To get a bit more control over the look and feel, you may choose to start with the default theme (Smoothness) or a ThemeRoller-generated theme and then adjust the ui.theme.css file or any of the individual plugin stylesheets. For example, you could easily tweak the corner radius for all buttons to be different than the rest of the UI components or change the path for the icon sprite to use a custom set.  With a bit of style scoping, you can even use multiple themes together in a single UI. To keep maintenance simple, restricting changes to just the ui.theme.css file and images is recommended.</li>
  <li>'''Write completely custom CSS''': For the greatest amount of control, the CSS for each plugin can be written from scratch without using the framework classes or plugin-specific stylesheet. This may be necessary if the desired look and feel can't be achieved by modifying the CSS or if highly customized markup is used. This approach requires deep expertise in CSS and will require manual updates for future plugins.</li>
</ul>

== Using ThemeRoller and Themes ==

<ul>
  <li>[http://themeroller.com ThemeRoller application ] </li>
  <li>[[UI/Theming/Themeroller|ThemeRoller documentation]] - How to use the ThemeRoller application</li>
  <li>[http://jqueryui.com/themeroller/developertool/ ThemeRoller Firefox Developer Bookmarklet] - Pull ThemeRoller into any webpage!</li>
  <li>[[UI/Theming/ThemeSwitcher|Theme switcher widget]] - add a widget to quickly switch between the gallery themes to your site</li>
  <li>[[UI/Theming/ThemeRollerReady|List of plugins and sites that use the new jQuery UI CSS Framework and are ThemeRoller-ready]] </li>
</ul>

== jQuery UI CSS Framework & Custom themes ==

<ul>
  <li>[http://docs.jquery.com/UI/Theming/API jQuery UI CSS Framework documentation] - Explore the full class API and icon set</li>
  <li>[[UI/Theming/CustomThemes|How to create custom themes]] - Tutorial for creating a theme from scratch</li>
</ul>