Coding Philosophy

The code is based on the following principles:

Use Semantic HTML

This code adheres to semantic HTML when coding components. This means taking advantage of the built-in structure of existing HTML elements - rather than using meaningless divs and spans - and using HTML tags the way they were intended, not for their built-in visual style.

  • h1 is used for the main header on the page - there should only be one h1 tag per page
  • h2 is used for section headers (and titlebar header)
  • h3 is used for subsection headers
  • h4 is used for entry titles
  • Lists are used for lists (rather than a series of divs)
  • Lists are nested for organization charts and discussion forums
  • Tables are used for entry data
  • Forms are used for forms
  • Label tags are used to label form elements
  • Input elements are used for form buttons
  • We use home-grown buttons - making use of links and a wrapper span - for our action buttons, which sometimes contain images. We would use the button tag, only there are some real styling challenges for button elements. (HTML buttons are used in forms.)
  • Divs are used as block container elements
  • Spans are used as inline container elements
  • Existing html elements are used whenever possible - when they make sense - instead of divs
  • Code order is paid attention to, so people using screen readers can understand the page

The benefits of working this way:

  • The page is understood by other technologies, such as screen readers, and makes more sense if styles are turned off
  • This creates a skeleton, which is then easier to style

Adhere to Web Standards

The phrase "coding to web standards" refers to a set of best practices for creating web pages. Coding to web standards is a methodology that makes sites easier to maintain and update, and improves performance.

Here are some key principles:

  • Use semantic HTML (see above)
  • Use a proper doc type on your page so browsers do a better job at interpreting your code (we use xhtml/transitional, see below for more detail.)
  • Separate code from style - html defines the structure, css defines the look and feel
  • Use tables for tabular data, not layout - when rendering a page, the content of the table needs to render before the table will render, unless column sizes are fixed. This slows down loading of the page, especially when mutiple and/or nested tables are used for layout. (We have a few exceptions, mostly for dealing with bidirectional issues.)

Minimize CSS

The intention with this CSS is to keep code as streamlined as possible. The less code there is, the better performance is, and the easier code is to maintain and for customers to customize.

Three techniques that help in this area are:

  • using inheritance to keep style names down (e.g .lotusMenu h2)
  • using multiple classes on elements to keep style names down (e.g. <div class="lotusInfoBox lotusHelp">)
  • Use general styles to tweak the layout rather than creating additional variant styles.

In production, you can improve the performance of your website by shrinking your CSS (eliminating comments and extra whitespace) and combining files together (to reduce the number of HTTP requests). While we do try to avoid lots of unnecessary whitespace, our files could be compacted more before being deployed in a production environment. There are many tools on the internet to help with this task. We do not provide compacted files and leave that as an exercise for consumers of our files.

Use Accessibility Coding Techniques

Use coding techniques that make pages accessible to people with vision and mobility issues, as well as cognitive issues (we pay less attention to that one, as it is harder to define). Details on that technique are found on the Accessibility page.

Base Styles

To get rid of some of the browser differences in rendering HTML elements, we redefine a small set of base styles.

Hacks

Our philosophy for hacks is to avoid them whenever possible. You can do things to set hasLayout for IE components by putting zoom:1 in your style declarations. This has no negative impact on other browsers but fixes a lot of IE issues. It does what the holly hack {height:1%} used to do, with less side effects and without needing to be separated out in browser-targeted hack.

There are also some things we do with inline block styles in the same declaration, redefining display in an order that browsers will pick up what they need and ignore what they don't recognize. This fixes most of the rest of the IE issues that you will run into. Here's an example:

.lotusBtnImg{
  display:-moz-inline-box;/*for FF2*/
  display:inline-block;/*for the rest of the browsers*/
}

You still may need to do an occasional tweak of margins or padding in IE, and for that, you can use one of the following classnames to target your hacks (including them near the css that works for most components). These classes are added to the html tag using browser detection code.

.lotusui_ie6 - use for IE6 hacks, in place of * html
.lotusui_ie7 - use for IE7 hacks
.lotusui_ie - use when you need a hack that works for both IE6 and IE7
.lotusui_ie8 - use when you need a hack that works for IE8 in IE8 standards mode (if run in IE7 compatability mode, the lotusui_ie7 styles will apply)

CSS Sprites

The CSS uses sprited graphics to reduce the number of HTTP requests and improve performance.

Custom CSS

If a product takes the code base and needs to make adjustments, but doesn't want to lose the ability to take CSS updates while they are developing, it is recommended to create a product-specific style sheet where any CSS overrides can be placed.

The Doctype

Markup and CSS is authored and tested using the HTML5 strict doctype. This is a change from testing using the XHTML transitional doctype prior to implementing HTML5 support. This does not necessarily mean that you must use the HTML5 strict doctype. The two key requirements in this space are:

  1. The browser must run in standards mode (and not Quirks mode)
  2. Markup should be written such that if it were included in a page that uses an XHTML doctype, it would still work and wouldn't fail.

The second requirement means doing many of the techniques discussed on this page...like using well-formed markup, using lower-case tag names, making sure all attributes have quotes, etc.

It should be the responsibility of each consumer of this markup and CSS to determine which doctype (or multiple doctypes) they will support.

There are some known issues with vertical alignment differences between the two doctypes and we have tried to mitigate those issues in our CSS.