This page lists lots of random notes about our CSS classes (and template design). Someday this info should be cleaned up and put in the book/etc.

baseClass

Every form widget has a baseClass attribute which is actually (as of May 2008, post 1.1) a list of class names. The class names are combined with the widget's state and set on Widget.domNode (the outermost node of the widget). So a focused spinner will get .dijitSpinnerFocused class. See FormWidget.setStateClass for details:

//	... [sets] the css classes on this.domNode
//  (or this.stateNode if defined) by combining this.baseClass with
//	various suffixes that represent the current widget state(s).
//
//	In the case where a widget has multiple
//	states, it sets the class based on all possible
//  combinations.  For example, an invalid form widget that is being hovered
//	will be "dijitInput dijitInputInvalid dijitInputHover dijitInputInvalidHover".
//
//	For complex widgets with multiple regions, there can be various hover/active states,
//	such as "Hover" or "CloseButtonHover" (for tab buttons).
//	This is controlled by a stateModifier="CloseButton" attribute on the close button node.
//
//	The widget may have one or more of the following states, determined
//	by this.state, this.checked, this.valid, and this.selected:
//		Error - ValidationTextBox sets this.state to "Error" if the current input value is invalid
//		Checked - ex: a checkmark or a ToggleButton in a checked state, will have this.checked==true
//		Selected - ex: currently selected tab will have this.selected==true
//
//	In addition, it may have one or more of the following states,
//	based on this.disabled and flags set in _onMouse (this._active, this._hovering, this._focused):
//		Disabled	- if the widget is disabled
//		Active		- if the mouse (or space/enter key?) is being pressed down
//		Focused		- if the widget has focus
//		Hover		- if the mouse is over the widget

Q: Why don't we use :hover, :focus, etc?

A There are two reasons for this:

1. IE6 and IE7 don't support :hover etc. on <span> and <div>divs, and we decided not to use <a> tags in the code except for actual anchors, so screen readers etc. don't get confused, plus for philosophical reasons. But it's bloated our code some so that could be revisited at some point. We can use waiRole to indicate that an anchor isn't really an anchor, just like a table isn't always really for tabular data.
2. Affecting grandparent: if focus is on a <button> node we may want to affect (for example) the border on a <div> surrounding the <button> because the template for the widget is something like <div><button></button></div>

icons and sprites

For faster loading we put multiple icons into one image file (gif/png), and specify them as CSS background-image. Will typically be a class like this as applied to an inline-block element (with the dijitInline class on it):

.myIcon {
   background: url("images/myIcons.gif") -50 0;
   width: 7px;
   height: 4px;
}

Png is preferred for the gradient transparency but we don't use it on IE6 because it requires a filter() clause in the CSS with a path name relative to the document (index.html) root, rather than relative to the CSS file location, and we don't know where that document root is.

There are also problems with fading in/out nodes that contain png images on IE7 (they look strange during the fade in / fade out) which is why we use a gif for the tooltip connector even on IE7.

I18N considerations

CSS purists will tell you to use float: left and similar constructs rather than <table> in code, but the problem is that when such a page is displayed on an RTL system (ie, in hebrew or an arabic script), the letters need to go from right to left, and the float:left will mess that up. Should look like:

Label:

If you use a table or other inline HTML it flows correctly automatically. So we tend to avoid floats. We do have some in the code, which is why you will see Button.css vs Button_rtl.css files

relative sizing

We don't use px or pt for font sizes in the code because it prevents Ctrl-+/Ctrl-- from changing the font size, which is bad for accessibility reasons. Fonts are specified in em, typically.

This is more complicated then it sounds because it means that we don't know how tall, for example, tab labels will be. Besides varying by theme, they will vary based on the end-user's browser settings for font-size. See next section.

race conditions

When layout widgets initialize they need to ask the browser how big certain nodes are. For example, for a TabContainer with style="height: 500px", if the tabs themselves are 20px tall, it will allocate 480px for the content. Since the height of the tab labels is affected by the theme CSS, there's a race condition if the tabs start to initialize before that CSS has finished loading / taken effect.

Problem seems not to occur as long as you put the @import statements for your theme as the first thing in your code, before even including dojo.js.

sniff

Due to unfortunate browser quirks we need to write browser-specific CSS rules. Merely by including dijit into a page, the <html> tag will get a bunch of CSS class names based on the browser type/abilities. Currently:

• dj_ie: IE6 or 7 (or 8?)
• dj_ie6
• dj_ie7
• dj_iequirks: look up quirks mode in wikipedia or quirksmode.org if this isn't clear
• dj_opera: opera isn't supported by dijit but we still have flags for it
• dj_khtml
• dj_safari
• dj_gecko: any of the firefox versions
• dj_ff2: firefox 2
• dj_ff3: firefox 3
• dj_contentBox/dj_borderBox: dj_borderBox is set for IE in quirks mode.

Theme class

CSS rules are split up into dijit.css (rules that apply to all themes) and theme-specific files like tundra.css. In theory you can have multiple themes coexist on a page (this doesn't work so well with popups though), which is why each section of the page displaying a particular theme should have class="tundra" or similar. Typically that is put on <body> but doesn't need to be.

high contrast mode

Widgets need to be usable on displays in high-contrast mode, where background-images don't show up. In this case a .dijit_a11y class name is added to which triggers certain CSS rules to display text instead of images, and also to affect other things.

You'll notice that templates have both nodes for icons, plus nodes that contain character equivalents for those icons, like +/- signs. We tend not to use arrow characters for high-contrast mode because they would need to vary based on RTL vs. LTR mode (see above).

Q: why do we use real button nodes in the templates instead of just <div>?

1. to make safari tabIndex work
2. enable the button value to submit in forms when type=submit and if-and-only-if the button was clicked
3. space bar and enter key work automatically for clicking w/out having to setup onDijitClick handler
4. wai roles setup automatically (i.e. screen readers will announce that it's a button

The first is optional but important. The second is mandatory since it tells the server which submit button was pressed in the case of several submit buttons present in the same form (eg. install and update). The WAI stuff was just gravy. There may be clever ways of doing the same thing but they weren't obvious to me at the time.

onDijitClick

The problem w/onClick handlers in browsers is that an onClick handler on a div etc. won't handle keypresses, so it's insufficient for keyboard users that click using space key or enter key. onClick on a button, in contrast, does handle keyboard. So we setup a special onDijitClick event that can be used from dojoAttachPoint or Widget.connect() that will handle both mouse and keyboard "clicks".

It's actually somewhat complicated because enter and space key on a button are handled on keydown and keyup (respectively, or reversed, I forget which). We need to do the same thing for onDijitClick, or otherwise a click event that shifts focus might cause two clicks, one on the newly focused item and one on the previously focused item.