CSS Best Practices

Owned by Jen Bourey
Last updated: Nov 30, 2010Version comment

CSS usage in portlets requires care by the portlet developers to avoid styling conflicts with both the portal framework and other portlets on the same page. Below are uPortal's recommendations for using CSS in your portlets to help mitigate these issues.

CSS Loading

Unfortunately the JSR-168 specification doesn't provide a way for a portlet to contribute to the <head> of a document for things like loading CSS files. That leaves the best option for a developer to load the CSS frameworks that the portlet needs inline in the HTML markup of the page. Below is an example of loading a CSS file in the portlet content.

<link rel="stylesheet" href="/MyPortletWebapp/css/my_portlet.css" type="text/css"/>
<div class="MyPortletWebapp">
    <!-- portlet content here -->
<div>

CSS Scoping

You'll notice in the example above that immediately after the CSS <link> element is a div with a class name specific to the portlet web application. This div is used to scope all style rules created for the portlet.

Scoping your portlet's CSS under an outer div named specifically for your portlet web application has two important advantages:

  1. Your scoped CSS rules will be the most specific styles for your elements and take precedence over other styles on the page.
  2. Your scoped CSS rules will not apply to any elements outside of your wrapper div preventing unintended side effects on other content on the page.

In the example below the text-decoration style is changed for all <a> elements but only under the wrapper div for this portlet.

my_portlet.css
.MyPortletWebapp a {
    text-decoration: none;
}
.MyPortletWebapp a:hover {
    text-decoration: underline;
}

IDs versus Classes

Many CSS developers coming from standard web application development are used to targeting CSS rules to elements based on the element's ID. With portlets your content could be included multiple times on the page or other portlets on the page could have conflicting IDs. The solution for the conflicting ID problem with portlets is to use a unique namespace string provided by the portlet API. The problem this then presents for CSS is that the IDs for the elements are not static. The recommendation then is to only ever target CSS rules for portlets by class name and never by ID.