Migration Guide

If you are still on version 2.0, see these instructions for what was necessary to migrate to version 2.1.

Required Changes

The following are the minimum changes necessary for proper styling of markup:

Special note to users of the 3.0.2 version

The "Add a comment" markup in the flyout needs updated to match the "Add a comment" markup in the activity stream posts.

Remove the HTML comment "put class='lotusSelected' on the li element of the selected tab" from the condensed tab markup because that comment breaks a first-child pseudo-selector in IE7.

Special note to users of the 3.0.1 version

The page layout was changed from fluid-width to fixed-width in version 3.0.1. This has been updated to a minimum and maximum-width layout in version 3.0.2 with additional support for fluid-width and fixed-width layouts. See Markers and Namespaces for additional info.

Special note to users of the 3.0.0 version

Version 3.0.0 contained defects related to use of special pages (lotusAbout, lotusLogin2, lotusHome, lotusMetrics, lotusError, and lotusStream) as well as lotusui30_layout on these pages. The migration instructions below and example pages have been corrected in the 3.0.1 version. In particular:

  • All special page classes (lotusAbout, lotusLogin2, lotusHome, lotusMetrics, lotusError, and lotusStream) must only go on the <body> tag.
  • lotusui30_layout must only go on the top level <div> surrounding the page content... either on the same <div> as the lotusFrame class... or in a new top-level <div> where a lotusFrame would have been used if such a <div> were used on the page.

Version 3.0.1 also adds back in support for the lotusui30 class on the <body> tag. (This was removed in the 3.0.0 version.) The migration instructions as well as other Developer Guide pages have been updated to reflect this.

The Dojo namespace and theme name have been changed in this release from oneui30 to lotusui30dojo. Teams using the Dojo theme shipped with version 3.0.0 will need to change "oneui30" to "lotusui30dojo" on their <body> tag, install the new Dojo theme in their Dojo build, and change links loading oneui30.css to loading lotusui30dojo.css.

Replace the share something link and user picture with utility icons and a CompanyName logo in the right of the banner.

Revert the title bar lotusGlobalSearch back to the lotusSearch markup. Remove the span that contains the search scope text and update accessibility to account for that removed text. Change lotusRightCorner to lotusWrapper in the title bar. Move action buttons from the title bar to links in lotusTitleBarExt, the area below the title bar.

Title bar tab markup was updated to support the new visual design. See the title bar component for more details.

Update the browser detection script

Add a test for Internet Explorer 8 and Internet Explorer 9 into your detection script. The general lotusui_ie class only targets IE6 and IE7 because those browsers often share adjustments. Use lotusui_ie8 for any additional IE8 adjustments and lotusui_ie9 for any additional IE9 adjustments.

 <!--[if IE 6]>
  <script type="">
     document.getElementsByTagName("html")[0].className+=" lotusui_ie lotusui_ie6";
  </script>
 <![endif]--> 
 <!--[if IE 7]>
  <script type="">
     document.getElementsByTagName("html")[0].className+=" lotusui_ie lotusui_ie7";
  </script>
  <![endif]--> 
  <!--[if IE 8]>
   <script type="">
     document.getElementsByTagName("html")[0].className+=" lotusui_ie8";
   </script>
 <![endif]--> 
 <!--[if IE 9]>
   <script type="">
     document.getElementsByTagName("html")[0].className+=" lotusui_ie9";
   </script>
 <![endif]-->

Add top-level marker classes to existing DOM nodes

  • add lotusui30_body to <body>
  • add lotusui30_fonts to <body> (should come after lotusui30_body)
  • change lotusui to lotusui30 (if on <body>, should come after lotusui30_fonts and before special page classes like lotusAbout. NOTE: High Contrast mode is not supported in IE 6 when lotusui30 is used on the <body> tag. See Markers and Namespaces for additional info.)
  • add lotusui30_layout to the top-level <div> with the lotusFrame class. (should come after lotusFrame)

These new classes are to support multiple integration scenarios. See Markers and Namespaces for additional info.

Add a new top-level wrapper <div> to pages that do not have a <div class="lotusFrame">

For all pages that currently do not have a <div class="lotusFrame"> and will use ICS UI to style the page layout, add in a new <div class="lotusui30_layout"> wrapper where <div class="lotusFrame"> would normally be.

Most ICS UI pages have a top level <div class="lotusFrame">. However, the special lotusError and lotusLogin2 pages do not have one because the page background styling was different than all other pages in a prior release. Support for the new integration scenarios requires scoping all special layout styling to lotusui30_layout and since all styling for special pages is handled through the page layout, this new <div> is required. A <div> that has lotusui30_layout should not have any other ICS UI classes besides the optional lotusFrame.

This change is to support multiple integration scenarios. See Markers and Namespaces for additional info.

Move special page classes "lotusMetrics" and "lotusWelcome" to <body>

In prior releases, the "lotusMetrics" and "lotusWelcome" special page classes could be used on a <div>. To support the new integration scenarios, these classes are now namespaced with the lotusui30_layout class (like all other special pages such as lotusAbout, lotusLogin2, lotusError, etc.) and will only function on the <body> tag.

This change is to support multiple integration scenarios. See Markers and Namespaces for additional info.

Potential updates for popups

ICS UI no longer makes assumptions regarding how dynamic logic should handle popup components such as popup menus and business cards. In the past, these popup items were styled such that they were positioned off-screen, but visible by default. This styling interfered with some JavaScript libraries such as Dojo. As such, all styling related to visibility of popups is removed in version 3.0 and it is up to the JavaScript library or the developer wiring the markup to the JavaScript library to determine if popup components should initially be positioned off-screen, or display:none, or visibility:hidden, etc.

Potential updates for dialogs

Non-Dojo dialogs have received styling changes that remove min and max widths so the dialog "shrinkwraps" the content. If you have a dialog that displays long, user-defined content, it is recommended that a width of some sort be applied if your JavaScript library does not properly handle the text length causing the dialog to expand beyond the page width. It is recommended that Dojo dialogs be used when the Dojo toolkit is available because ICS UI dialogs:

  • have arbitrary fixed dimensions in right-to-left languages to avoid browser bugs
  • have arbitrary fixed dimensions in IE 6 to avoid browser bugs
  • require extra styling because of how IE 6 and IE 7 handle relatively positioned elements inside a scrolled parent

Dojo dialogs do not have any of these issues.

Changes for Accessibility

The following changes are recommended to properly support accessibility in your product. Some changes, while not necessarily required for proper styling, may be required for you to complete your accessibility compliance checklist. In some cases, there may be more than one way to meet the accessibility requirements. When more than one way to meet the requirements is possible, we have chosen to implement the "best practice" solution.

Use classes on all heading tags

Add lotusHeading, lotusHeading2, and lotusTitle classes to the HTML heading elements (h1-h4). Generic (reset) styling of <h#> tags has been removed to fix improper styling defects. Specific component styling by <h#> tag (listed below) remains, but is deprecated and will be removed in a future release. Markup using aria-level to re-define the heading level (telling a screen reader that an <h3> is really an <h2>) should continue to work with the deprecated styles however, this is not best practice. It is best practice for a heading level to represent the number that is coded into the tag name combined with proper use of classes to apply styles independent of the level.

lotusHeading:

  • lotusDialog h1 tag
  • lotusForm2 h1 tag
  • lotusHeader h1 tag
  • lotusHelp (new version of the component) h3 tag
  • lotusInfoTable h2 tag
  • lotusMenu h3 tags
  • lotusPalette h2 tag (there is not an example of this, but this is to support a header in the palette header rather than tabs)
  • lotusSection2 h2 tag
  • lotusTips (new version of the component) h3 tag
  • lotusTitleBar2 h2 tag (h1 in the breadcrumb)
  • About box h1 tag, h2 tags on the page outside of the about box
  • Error page h1 tag
  • Login page h1 tag
  • Metrics page h1 tag
  • Welcome page h1 tag

lotusHeading2:

  • lotusDialog subheading h2 tags
  • lotusForm2 section heading h2 tags
  • lotusPalette lotusPaletteNav h3 tags
  • lotusSection2 subheading h3 tags
  • About box h2 tags (lotusHeading is used for h2 tags on the about page outside of the about box).
  • Login page h2 tags

lotusHeading3:

is reserved for cases where product teams need a third level of headings. There are no examples of this in the code.

lotusTitle:

  • lotusForum lotusPost h4 tags
  • lotusPaletteWidget h4 tags (lotusTitle was already being used on the wrapping div for the h4 tags, so this class was changed to lotusWidgetTitle)
  • lotusTable/lotusInfoTable h4 tags
  • forum lotusPost title h4 tags

Put only text in heading tags

Update the following components (view the code on individual component pages) to meet the accessibility requirement of only having text (which can be wrapped in a link tag) in html heading tags (h1-h6):

  • lotusDialog
  • lotusMenu
  • lotusPalette
  • lotusInfoTable
  • lotusSection2
  • lotusTips

Twisties, close buttons, icons all exist inside of a header element (or div) in addition to the html heading element, following this format - <header>[twisty]<h#>header text</h#>[icon]</header>

Add aria attributes to your code

See individual components and the accessibility guide in this developer documentation for more information.

Other

  • Add title attributes to individual tags in a tag cloud to meet accessiblity requirements
  • Update tables to remove some older accessibility recommendations (like empty summary tags on layout tables and scope attributes for simple table headers)
  • Put alt="" alt text on Comment avatars (instead of the name, which is redundant).
  • Use inline lists instead of lotusDividers in between groups of things (like filters in a header and meta info in our content displays). Used aria lists when another list became embedded inside the inline list, like for our tag lists in a group of meta information.
  • For image "labels," use alt text when the image is going to be hidden when images are turned off, otherwise use aria-label
  • For the information and success messages, change role="status" to role="alert"
  • Remove role="presentation" from the table in the footer with table elements

Recommended Changes

Fix Internet Explorer 8 performance issue

Add following to the top of the head section of your page (more info):

<!--[if IE 6]><![endif]--><!--fixes IE8 performance issue of conditional comments blocking css download-->

Optional: Update to HTML5

Change the top of your page to use the following doctype: <!DOCTYPE html>

Remove the following attributes from the html tag: xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US"

You can optionally remove the type attributes from script and link tags

To get the new HTML5 elements recognized by Internet Explorer browsers, put the following conditional comments on your page:

 <!--[if IE]>
 <script type="text/javascript">
 document.createElement('article');
 document.createElement('aside');
 document.createElement('footer');
 document.createElement('header');
 document.createElement('hgroup');
 document.createElement('nav');
 document.createElement('section');
 </script>
 <![endif]-->

Article tags used in the following components:

  • Comments (replaces the lotusPost div)

Aside tags used in the following components:

  • Right column of the page - replaces the lotusColRight div

Footer tags used in the following components:

  • Footer - replaces the lotusFooter div
  • Legal - new construct that wraps the lotusLegal table

Header tags used in the following components (keeping existing class names or adding new ones):

  • Banner - replaces the lotusBanner div
  • Dialog - replaces the lotusDialogHeader div
  • Forms - add around form titles (class = lotusFormTitle) and form section headers (class = lotusFormSectionHeader)
  • Header - replaces the lotusHeader div
  • Help - add around the h3 tags and class with lotusHelpHeader
  • Menu - part of the new menu section header construct, around twisties and h3 tags (class = lotusMenuHeader)
  • Information Table - add around the h2 tag as part of a new heading construct (class = lotusTableHeader)
  • Customize Palette - replaces the lotusPaletteHeader div. Also part of new palette nav header construct that sits above the left column navigation (class = lotusPaletteNavHeader).
  • Section - part of a new header construct wrapped around the h2 tag (class = lotusSectionHeader). Also used for subsection headers, wrapping the h3 tag (classe = lotusSubheader).
  • Tips - part of new header construct (class = lotusTipsHeader)
  • Title Bar - replace the lotusTitleBar2 div

Hgroup tags used in the following components:

  • About box on about page, to wrap the two heading tags (h1 and h2)

Nav tags used in the following components:

  • Banner - new construct that wraps the navigation links (lotusLinks)
  • Breadcrumbs - replaces the lotusBreadcrumbs div
  • Menu - replaces the lotusMenu div
  • Paging - replaces the lotusPaging div
  • Title Bar - new construct that wraps the tabs

Section tags used in the following components:

  • Sections (and their variations) - replaces the lotusSection2 div

Updated components

Banner

The Banner has some additions:

  • The lotusLogo node should now be an anchor element and by default, the lotusAltText is displayed. Remove the background image on lotusLogo. The image logo can be used by toggling the display values on the lotusLogo img and lotusAltText.
  • The lotusUnreadBadge span is new.
  • The lotusUtility list has been updated and includes icons and a right IBM logo.

Buttons

Buttons have been simplified:

  • Switched to using button tag for action buttons (can include an image) - use lotusBtn class. This replaces link buttons.
  • Using input tags for form buttons (now classed with lotusBtn instead of lotusFormButton - dialogs and forms)
  • Image buttons just use one option - a span classed with lotusBtnImg that wraps an input type="image" element.
  • Note: lotusDelete is not considered a button and uses a link surrounding an image.

Dialogs

There is now only one version of a dialog. Alternate header/footer variations were deprecated. Update your dialogs to the standard version if not using a dojo dialog.

The dialog requires new markup for the close icon.

Footer

You can now use either inline lists or tables to construct footers. The styles in place will output inline lists horizontally (good for shorter lists) and allow tables to show a vertical list of links for each table cell (good for multiple categories of links).

Forms

  • Forms are now created using divs.
  • Use lotusForms2 class. lotusForm table-based styles are deprecated.
  • Use additional lotusLeftLabels class on form div when you want labels to align to the left (top alignment is preferred)
  • Additional lotusFormPlain class is no longer needed because the background color of the form is now determined by where it sits on the page.
  • Error messages at the top of a form are now done using an error message component.
  • Add lotusIcon class to help icon, which is placed inside a form label, after the label text.
  • All fields are now wrapped in a div with class=lotusFieldWrapper.
  • Meta text can be used to provide help for a field as an alternative to popup help. It is contained in a div with class lotusMeta which is placed inside of the lotusFieldWrapper div, directly after the form field.
  • New lotusFormErrorIcon class for error icons, which follows the lotusFieldWrapper div.
  • Added new form sections.
  • Added optional label text that isn't an actual form label (lotusFormLabel class)
  • Fieldset legends need to be used for wrapping sets of checkboxes or radio buttons for proper error display. (They can be invisible to the sighted user, if desired)
  • Apply lotusAccess to a fieldset legend if you want it to hide offscreen
  • Form buttons now use the lotusBtn class. The lotusFormButton class is deprecated.
  • Deprecated lotusFieldBorder styles, which were used to add a border around a field to give it emphasis.
  • The error text for login forms has been updated.
  • See the forms component for more specifics, especially those about error handling.

Help and Tips

These two components have been split into separate components rather than variations of the lotusInfoBox (these styles have been deprecated).

  • Use the lotusHelp class on the help component.
  • Remove inner div with class="lotusInfoBox".
  • Add the new header construct (header html5 tag around an h3 tag with class="lotusHeading")
  • Use the new lotusTips class on the tips component.
  • Use the new header construct (header html5 tag around an h3 tag with class="lotusHeading" and close button)
  • Wrap the tips text in a div with class of lotusTipBody

Legal

Legal component is now wrapped in a footer tag (or div)

Mega Menus

  • Add the lotusNavMenuLarge class to the lotusLayout table in the apps mega menu.

Menus

  • Use new header construct for menu headers, with the lotusMenuHeader class on the header tag (or div) and the lotusHeaderSelected class as an additional style when the header is selected.
  • The lotusUnreadBadge span is new.

Messages

  • New lotusMessage2 class; lotusMessage styles are deprecated.
  • Add lotusIcon class to message type icon
  • Change span that wraps the message text to a div with class="lotusMessageBody"
  • Close icon is no longer optional
  • Confirmation message is now a sucess message. Use lotusSuccess instead of lotusConfirm. For the icon use lotusIconMsgSuccess instead of lotusIconMsgConfirm.

Paging

  • Add lotusPagingTop to the top set of paging controls to trigger additional styling.

Popup components

Popup components (action menus, dialogs, help) are no longer hidden by default using top:-9999px. You will have to originally hide them yourself by adding the display:none inline style (alternatively, you could add the lotusHidden general class).

There is a new popup component in preview mode. The existing, simpler help popup still exist for simple popups like error messages (see forms component).

Sections / Portlets / Widgets

  • Change lotusSection to lotusSection2 and look at the section component code snippet to implement the accessiblity changes required for the section header.
  • For existing lotusWidget components, convert the classes in your markup to use the lotusSection prefix (lotusSectionHeader, lotusSectionBody, lotusSectionFooter). Change the top level class to lotusSection2. Update the header to be accessible following the section/portlet code snippets. If your widget will sit on a dashboard/home/portal/mashup page add an additional lotusPortlet class to the component.
  • For sections where no chrome is desired, add the lotusSectionPlain class as a multiple class at the component level (lotusSection2 lotusSectionPlain). You also have the option of using one of the general lotusChunk layout classes if a section isn't really needed.
  • Update the class for and action menu icon on a section header to use lotusActionIcon because lotusActionMenu is the class for our action menu component.

Posts

  • Make sure individual li tags in a lotusCommentList have the lotusCommentItem class. This was always documented but a couple of the examples in older versions of the developer documentation were missing it.
  • When creating an activity stream, use the existing lotusBoard wrapper on a containing div, and inside of that, create an unordered list with class lotusStream. Each li tag wraps a post.
  • See the base post component for additional classes available when creating posts.
  • See the comment component for the new condensed comment list and an example of comments with inline actions.

Title Bar

The updated title bar can have action buttons and tabs, but never at the same time.

  • Change lotusRightCorner to lotusWrapper.
  • Add a 24px image in the lotusHeading h2 tag.
  • In the title bar search, remove the span that wrapped the search scope text. Update the accessibility attributes to account for that removed text.
  • Buttons traditionally in the place bar should get moved to links in lotusTitleBarExt, below the title bar.
  • Tabs are currently not supported in the 3.0.1 title bar, but will be supported in a future release.

Deprecated Components

The following components are deprecated this release.

  • Breadcrumbs with dividers - use the simple version of breadcrumbs moving forward.
  • Link Buttons and link/image version of an image button - use real form buttons instead.
  • Tree - use the dojo tree control instead
  • Person card - will become replaced with a newer object card and this version is obsolete.
  • Separate sections and widgets - replaced with a new section component with a portlet variation (dropping the overloaded "widget" term)
  • Dialogs with alternate headers / links in dialog footers
  • Table-based forms (lotusForm) along with lotusFormErrorSummary and lotusFieldBorder styles.
  • Confirmation messages (replaced by success message)
  • Place Bar / lotusTitleBar - elements on this component are now merged into the new version of the Title Bar
  • Welcome Box - the new box uses a cancel button instead of a cancel link

Updated pages

General

  • Move Messages and Info Tables above Header component (page titles)
  • Move special page classes to the lotusFrame div or a new wrapping div
  • Changed the page minimum width from 990px to a standardized 960px.

Home Page

  • Now uses a variation of the lotusLayout table for creating multiple columns. Add the additional lotusColumns class.
  • Add lotusFirst to the first column of the layout table and lotusLast to the last column.

Login pages

  • Add a banner to your login pages. Make sure the banner includes the lotusRightCorner and lotusInner nodes.
  • Update the login forms to use the new form structure.
  • Updated error message text.

Error page

  • Add the lotusIcon class to the error icon image

Welcome page

  • New header construct with the close button inside (to match all other headers with close buttons).
  • Replace link buttons with html buttons
  • Replace the lotusSection with lotusChunk (and use an html5 section element)
  • New header construct for search profiles section.
  • Use lotusForm2. The welcome page form is a little different and doesn't use lotusFieldWrapper, because it isn't a form that has any error handling.

Dojo

  • Version 3.0 includes a full theme for Dojo version 1.5. You'll need to add the lotusui30dojo class to the <body> tag and load the new theme files into your page as you would any other Dojo theme.
  • There is now only one set of dojo style overrides - for a menu tree. All the rest of the style overrides for Dojo have been removed and folded into the lotusui30dojo Dojo theme.