Look and Feel Customization

Look and feel customization

In order to help you with your customization, an example of a fully customized Interview Portlet using the Social Services Screening rulebase can be found in the Java runtime zip file at examples\interview-portlet\social-services-screening. Additionally, the rulebase source can be found at examples\rulebases\source\SocialServicesScreeningPortlet.zip.

Add static resources

Like in Web Determinations, developers can customize the Interview Portlet by adding custom images and other static resources that can be either local (within the opa-interview-portlet web application), or external (accessed via URL).

Load local resources

To add an image to a portlet page, do the following:

  1. Place the image file in the "images" directory of the deployed portlet (opa-interview-portlet\WEB-INF\classes\images).

  2. Refer to the image in the appropriate Velocity template by using the following code, where imgFileName is set to the name of the image file:

<img src="${urlRewriter.getResourceURL("${image-resource-request}/imageFileName")}" alt="Alternative title"/>

For instance, in the Social Services Screening example, some goal controls on the summary screen have a custom attribute PortletImgPath. This property is set to a value like sss/AmIEligible_v03.gif, where AmIEligible_v03.gif is an image file found in the directory WEB-INF\classes\images\sss of the portlet war file. The customized GoalControl.vm template then renders the image as follows:

#set($imgPath = ${control.getProperty("PortletImgPath","")})
#if ( $imgPath == "" )
  ${control.getText()}
#else
  <img src="${urlRewriter.getResourceURL("${image-resource-request}/${imgPath}")}"/>
#end

To reference a static HTML page in a portlet page, do the following:

  1. Place the HTML file in the resources directory of the deployed portlet (opa-interview-portlet\WEB-INF\classes\resources).

  2. Refer to the resource in the appropriate Velocity template by using the following code, where htmlFileName is set to the name of the HTML file:

<iframe src="${urlRewriter.getResourceURL("${resource-request}/htmlFileName")}"/>

        <p>Alternative text</p>

</iframe>

For instance, in the Social Services Screening example, some label controls on the summary screen have a custom attribute PortletResourcePath. This property is set to a value like help/more_info_food_stamps.html, where more_info_food_stamps.html is an HTML file found in the directory WEB-INF\classes\resources\help of the portlet war file. The customized LabelControl.vm then renders the link as follows:

#set($resPath = ${control.getProperty("PortletResourcePath","")})
...
#if ($resPath != "")
  <a href="${urlRewriter.getResourceURL("${resource-request}/${resPath}")}">
#end
#parse("investigation/control-text.vm")
#if ($resPath != "")
  </a>
#end

Note:

Because the portlet only generates an HTML fragment, it does not have access to the HEAD element and therefore it is not possible to include CSS style-sheets in the generated HTML. Any styling must be done at the portal page level.

Configure the location of images and static resources

By default, images are loaded from the directory opa-interview-portlet\WEB-INF\classes\images and resources are loaded from the directory opa-interview-portlet\WEB-INF\classes\resources.

These directories can be changed to another location by setting the images.path and resources.path properties in opa-interview-portlet\WEB-INF\classes\configuration\application.properties. (For more details, see Resource Loading properties)

Load external resources

To add an external image to a portlet page, refer to the image in the appropriate Velocity template by using the following code, where imgURL is set to the URL of the external resource: <img src="imgURL" alt="Alternative title"/>

Customize appearance

As the portlet framework does not allow for a standards-compliant way of including CSS files, the templates have been modified to hard include style information into HTML elements.

These styles are controllable through new settings in the appearance.properties file and have been given names that reflect the original style (basically by appending '-style' to the original style name; for example, the style settings for the "warning" style is contained in the "warning-style" setting.

Someone customizing the appearance of the portlet has the choice of either modifying the new style settings in the appearance.properties file or modifying the template files directly - which basically corresponds to the web determinations process of either modifying the .css file or the templates.