How to use configurable custom CSS in your portlet

JSR 168 specifies some classes (e.g. portlet-font, portlet-font-label) that can be used in portlets to style texts.

If you should do some more advanced layout/styling of your portlet output code that might need to be altered later on, a viable solution is to use named CSS classes in your code and define these in a CSS that SiteVision can deliver to visitors. By doing that, the style of your portlet can be altered/modified externally without any need for re-compilation/re-deployment. The disadvantage is that your portlet has a dependency to an external CSS code.

NOTE! To avoid naming collisions - be sure to use unique names for your CSS classes!

To achieve some uniqueness you can prefix or suffix your class names with the name of your organization and/or portlet name. E.g. the class names 'xyz-myportlet-normal' and 'xyz-myportlet-redbox' are preferred to 'nomal' and 'redbox'.

Example

Below is an example of output code of a portlet that needs to be re-compiled/re-deployed if the border color later on needs to be altered (BAD):

Below is an example of output code of a portlet that doesn't need to be changed/re-compiled/re-deployed if the border color later on needs to be altered (GOOD):

But now of course, you have to define your class in a CSS file:

.xyz-myportlet-redborder {
border: 1px solid red;
}

Next section is how to add css classes to the SiteVision output.

Add CSS classes

CSS classes can be incorporated in the SiteVision output code in two ways:

Add a separate CSS file containing your classes as an additional HEAD element for the page/pages where your portlet is used.
Insert your classes directly in the SiteVision CSS file.

Both strategies have pros and cons. Some of them are:

The easiest thing to do is probably just to put your CSS code in the SiteVision CSS file, but it's generally a bad thing to clutter the SiteVision CSS with code that aren't used very much (i.e. Why should clients download a "large" CSS file if it contains lots of code that isn't used?)
If your portlet is used infrequently, HEAD elements could be the way to go to help minimize download time for clients, but HEAD elements might require more administration (the editor that adds your portlet to a page must also add your CSS file as HEAD element).
Both strategies suffers from the "Is this code in use?" problem. If the code is in the SiteVision CSS, then it's almost impossible to determine if the code is in use or not. A CSS file added as a HEAD element has a more narrow scope and is probably "easier/safer" to handle for someone else than the portlet developer himself. The drawback is that you might end up with a website that has unused HEAD element CSS on some pages (i.e. the editors that removed your portlet didn't also remove the HEAD element CSS).

It's up to you to decide which way to go.

Configurable css

You don't necessarily need to hard-wire the css, you can make the css configurable by an administrator in two different ways.

(Though, in real life this might not be an viable option if the output of your portlet contains lots of css.)

Put setting in portlet.xml

You can put your "might want to change this css sometime in the future"-setting(-s) in the portlet xml so an admin can change it without re-compilation (i.e. doesn't need access to the source code). The portlet.xml file is plain xml so most admins should manage to do an update. The SiteVision service must be restarted for the new settings to used.

Use SiteVision custom portlet mode

You can use the SiteVision custom portlet mode to expose your "might want to change this css sometime in the future"-setting(-s). Then an admin can enter the SiteVision editing mode ("offline mode"), double-click your portlet and simply edit the value. The new settings will be used when the page is published.

Last updated: 2013-09-17

Developer guide