Wiki Navigation

Customization and Branding Strategies

Overview

Project.net is designed to be re-branded to fit a user's installation; the product's name, logo, URLs and what tools are available to the users are a few of the options. You were exposed a little to site configuration during installation when you configured the site name and support email addresses for your location.

This document provides an overview of the strategies and options available to those who wish to override or add static resources to their Project.net installation. Static resources include images, cascading stylesheets, javascript and static html pages.

Modern J2EE servers support applications to be deployed as WAR or EAR archive files which contain all static resources in addition to Java classes, JSP pages and configuration. In the case of the Project.net application, all the static resource files for the "Project.net Default Configuration" are included in the EAR file. Administrators cannot simply replace images in a webserver images directory, nor can they add their own images and other static resources.

There are several approaches to adding or replacing static resources used by the Project.net application.

Basic Description of Configurations

A configuration describes a set of "tokens" that allow a Project.Net server to appear and behave differently if a person has accessed the server with a special URL. For example, if you want your company's name to appear throughout the program and all URLs to go to a specific website, you would change the values of a few specific tokens. Most of the text and images visible in Project.net are controlled through tokens, in addition to:

The static text that appears on most web pages, i.e. field titles and menu labels.
Paths to cascading style sheets
Paths to images
Appearance of some links
Availability of certain Project.net modules

Generally, a configuration is accessed using a special URL. For example, the production Project.Net application server is hosted at http://login.project.net. However, you might access another customer's branded web site at http://somecustomer.project.net. Note, Project.net can have more than one active configuration, each accessed via its own special URL. The special URL's are indicated in the configuration setup and any valid URL can be used.

Customizing text

Most of the static text within Project.net is contained in a token. You can easily alter the text to match your own wording by creating a custom configuration and changing the appropriate tokens. Project.net is fully localizable and supports multi-byte character sets.

Customizing images

You can replace most of the images used in Project.net through a combination of tokens and the use of a WebLogic or Tomcat Virtual Directory. Alternate or customized images are placed in a virtual directory and their tokens changed to refer to this directory. At runtime, Project.net will use the images in the virtual directory rather than its default image directory. Unless you plan to modify the JSP pages the replacement images must be the same size as the originals.

Altering page header

You can control the height and content of Project.net's page header.

Customizing fonts and text styles

Fonts and text styles can be set by overriding Project.net's Cascading Style Sheets (CSS), similar to substituting your own image. You can also modify any CSS file to incorporate dynamic values from an existing or new configuration token.

Altering basic page layout

Beyond this, to change the layout of a Project.net page you will need to alter the Java Server Page (JSP) for that page. The pages are not extremely complicated and the tag library used is well-documented, but you will have to unpack the Project.net deployment EAR (Enterprise Archive), alter the existing JSP file, repacking and re-deploying the modified EAR.

You can also modify any CSS file to incorporate dynamic values from an existing or new configuration token.

Creating a custom login screen

If the standard configuration tokens do not provide enough control over the login page, it is straightforward to replace it with one of your own design.

Common Customization Choices

This table will help you understand a few of the items you can customize and how.

Logo IF
Text T
Links T
Layout J
Top page header TJ
Bottom of page branding fixed
Top two bars (grey and black) on pages IF
Personal, Business, Project, Resource, Enterprise icons IF
Action toolbar icons IF
Control visibility of tools in Navigation Toolbar T
Channel bar text T
Channel bar icons IF
Page text T
Text style (font, size, face) CSS
Custom login screen TJ

Key

T (Token) - Value set through system administrator interface
J (JSP) - Alter JSP (Java Server Page)
IF (Image File) - an image file stored in a WebLogic or Tomcat Virtual Directory
CSS (Cascading Style Sheets) - Modify CSS files for workspace pages

Create a configuration for your installation

Project.net contains many of its settings in configuration tokens; these tokens are stored in named configuration sets. For example, if you want your company’s name and logo to appear on the Project.net login page, you would change the values of two specific tokens.

While you can alter the Project.net default configuration set, it is recommended that you create a configuration just for your installation. Project.net will first use the values from your configuration. Any values not set in your configuration will receive their values from the system default configuration. Using a separate configuration isolates your custom settings, making them more obvious. More importantly, alternate configurations are preserved whenever the Project.net software is upgraded, while the default configuration loses any changes.

Note, Project.net can have more than one active configuration. Which configuration is selected for a user is determined by the URL or IP address he or she used to access the Project.net server. For example, users accessing the server through projects.mycompany.com may see the results of the default configuration, while those using custom-projects.mycompany.com could see a site customized by an alternate configuration.

Note, it is possible to "dump" the configuration tokens in the form of a script that can be applied
to another database, "loading" those tokens into the second database.  To extract the tokens,
modify and run the script: /trunk/core/db/oracle/create-scripts/tools/
generate_update_system_properties_dml.sqlto.  Run the resulting script against another Project.net
database to set those tokens in the second database.

Create a custom configuration

Follow these steps to create a installation-specific configuration

Instructions

From within the Application Administration interface, chose Manage / Configurations.
Click the Create icon to create a new configuration.
Enter:
- Name - Suggestion: use Standard Production Configuration or use the value used for the siteHost token.
- Description - Suggestion: include the siteHost value as part of the description.
- Abbreviation – This will be used as part of the token identifier.
- Choose the Default Language. You can leave this as the default value.
- Select multiple Supported Languages by holding down the Control key while clicking the desired names. You can leave this as the default value.
- Supported Host Names (CSV) – The values in this field determine when this configuration set will be used. List the web site names you want associated with configuration, separated by commas. If you enter projects.mycompany.com, login.projects.mycompany.com either address will cause the values in this configuration set to be used, in conjunction with the values from the default configuration.
Submit your changes to create the configuration set.

Site-specific token values

Follow these steps to create a installation-specific configuration

Instructions

From within the Application Administration interface, chose Manage / Configurations.
Click on the name of the custom configuration from the list of configurations.
Choose Tokens from the menu on the left.
Select Basic Branding from the Category list.
Click Filter
Set the appropriate values for the tokens below.

If a token does not appear in the list you can enter its name in the Token Name: search field and click the Filter button to locate it.

prm.global.brand.defaulthost: Same as the default configuration token
prm.global.brand.defaultjsprooturl: /
prm.global.brand.defaulttimezone
prm.global.brand.defaultsitescheme: http://
prm.global.brand.legal-name
prm.global.brand.name
prm.global.login.channel.login.title
prm.global.brand.logo.login.href
prm.global.default.site.href
prm.global.footer.copyright.href
prm.global.footer.poweredby.href
prm.global.login.requestinformation.text
prm.global.default.email.fromaddress
prm.global.help.feedback.emailaddress
prm.global.help.info.emailaddress
prm.global.help.legal.emailaddress
prm.global.help.sales.emailaddress
prm.global.help.support.emailaddress

Submit your changes. They will not take effect until the application server has been restarted, generally from the WebLogic Console, the Windows Services Console or Linux services tomcat5 restart.

Troubleshooting a configuration

Once you have established an custom configuration the first thing to verify is that Project.net is using that configuration rather than the default. Here are some hints:

In the custom configuration set the token prm.project.login.login_header_text-1 to something like "Alternate Configuration". This will make it easy to determine when this configuration is being used. If you go to the login page and it still says "Member Log in" rather than "Alternate Configuration" then the custom configuration is not being used.
Check the hostname values for the custom configuration. List any hostnames that should trigger this configuration. You may want to include 'localhost' or any specific ports. For example, "login.project.net, login.project.net:8080, localhost".
Make sure the hostname for the default configuration is blank. Since it is a required field you may have to enter 'bogus-hostname.project.net' as its value. Do not include localhost or any of the hostnames used for the custom configuration.
Note, you do not need to restart the application server after changing a value in any of the configurations, such as a hostname.

Customizing images

Common images replaced in Project.net

pnet_logo2.gif
pnet_home_button.gif
prm.global.header.banner.image

Pre-requisites

If you have not, create a Project.net configuration that will override the default configuration .
Choose a file system location to hold your replacement images (ex. C:\pnet\brand\images, /opt/pnet/brand, etc). It is suggested to create a sub-directory for each Project.net configuration or brand, if you have more than one configuration.
Figure out which image you want to replace and its size. From within a browser, right-click on the image, select Properties from the pop-up menu. From the properties dialog look at the Address (URL): entry and note the name of the image, which appears at the end of the URL. Also record the size of the image, listed in the Dimension field. For example, the Project.net logo on the login page is named pnet_logo2.gif and is 165 pixels wide by 90 pixels tall.
Create a replacement image the same type and size as the original. Save it in the directory chosen above.
Follow the remaining instructions based upon your configuration below.

Adding Static Resources via a Tomcat Context Resource

If you are using the Tomcat application server you can substitute static resources, such as a custom image, through a Tomcat context. The use of a context enables you to substitute customized images for Project.net's without touching the Project.net EAR file.

Instructions

The following instructions assume the alternate image is named mycompanyLogo.gif and is stored in a directory named /opt/pnet/conf-data/my-custom-configuration/. Substitute the directory and filename as appropriate for your system.
Within APACHE_HOME/conf/Catalina/localhost/ create the the following file named conf-data.xml (The value for docBase is the path to the base directory that will hold the alternate image.)
```
<Context
  path="/conf-data"
  docBase="/opt/pnet/conf-data"
  debug="1"
  reloadable="true"
  crossContext="true">
</Context>
```
Restart Tomcat.
Login to Project.net as an application administrator.
From within the Application Administration interface, chose Manage / Configurations.
Click on the name of your custom configuration from the list of configurations.
Choose Tokens from the menu on the left.
Search for the token named prm.project.login.pnet_logo2.
Change its value to /my-custom-configuration/mycompanyLogo.gif
- This pathname is relative to the directory listed as docBase in conf-data.xml.
Apply the settings.
Logout of Project.net. You will see your logo in the upper left of the log in page.
Troubleshooting
- If you still see the Project.net logo chances are the default configuration is still being selected over your alternate one.
  1. Right-click on the logo and select Properties from the pop-up menu.
  2. From the properties dialog look at the Address (URL): entry. If does not have the image file you defined in the prm.project.login.pnet_logo2 token then your configuration is not being selected. Refer to the troubleshooting section of Creating a Project.net configuration.
- If the logo is missing (i.e. an icon with a red X is displayed instead) again look at the image properties to see what image should be displayed. Check for typos in the name. If the name and path is correct double-check conf-data.xml. Do not forget to restart Tomcat after changing this file.

Adding Static Resources via a WebLogic Virtual Directory

If you are using a WebLogic application server you can substitute static resources through the server. WebLogic server incorporates the concept of a virtual directory. When it receives a request for a certain web page or type of file it will look in the virtual directory for the file before searching the application's directory structure. The use of a virtual directory enables you to substitute customized images for Project.net's without touching the Project.net EAR file.

This approach will only work if the Project.net application (typically pnet.ear) is deployed as the default web application within a WebLogic Server instance. The strategy is to create a WAR file containing a virtual directory mapping in the weblogic.xml descriptor. This mapping points to a operating system directory that will contain static resources in addition to the resources contained in the Project.net EAR.

Instructions

The following instructions assume the alternate image is named mycompanyLogo.gif and is stored in a directory named C:\pnet\brand\images).
Create a WAR archive file (mybrand.war or whatever you want to call it). This will define a virtual directory pointing to C:/pnet/brand, the file system directory that will contain custom static images for branding. The myband.war file should be zip file with name ending in “.war” and containing the following two files in a WEB-INF folder:

WEB-INF\web.xml

WEB-INF\weblogic.xml The web.xml should contain the following text:

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
</web-app>

The weblogic.xml file should contain the following text. The <local-path> should be modified to match where you have placed the static resources on your machine:

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE weblogic-web-app
  PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN"
  "http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd">

<weblogic-web-app>
<virtual-directory-mapping>
     <local-path>c:/pnet/brand/</local-path>
     <url-pattern>/*</url-pattern>
</virtual-directory-mapping>
</weblogic-web-app>

Login to the BEA WebLogic console (http://localhost:7001/console) and deploy the mybrand.war as a Web Application Module to the same Weblogic Application (PRM-1 by default) that contains the Project.net Application (pnet.ear by default). Name the Web Application Module “mybrand” (or whatever name you want to be used in the URL). Note: the name you give the Module is important since it will be part of the URL.
Restart the WebLogic application (PRM-1)
Test that the new static images are available. In this example, the image file testimage.jpg placed in the file system directory C:\pnet\brand will be accessible via the URL: http://localhost/mybrand/testimage.jpg
Login to Project.net as an Application Administrator and modify tokens in your configuration. For example, it you want to change the login logo to mycompanyLogo.gif change the following token from:
```
prm.global.brand.logo.login		/images/logo/pnet_logo.gif  
```
to:
```
prm.global.brand.logo.login		/mybrand/mycompanyLogo.gif  
```

Adding Static Resources via an Apache Webserver

If you are using the Apache web server you can substitute static resources through the server.

Instructions

Edit the httpd.conf file (probably /etc/httpd/conf/httpd.conf) and add the following lines at the bottom underneath the rest of our additions:

<LocationMatch /ext* >
  SetHandler default-handler
</LocationMatch>

Alias /ext /home/weblogic/extResources
<Directory /home/weblogic/extResources >
  Order allow,deny
  Allow from all
</Directory>

Create a directory /home/weblogic/extResources (the capitalized R is very important, failure to do it correctly will make you irritated later)
Place files that you want to be served in this directory.
The user running httpd (probably apache) will need to have some permissions. It will need to have execute permissions on each directory leading up to the extResources directory. (That is, /home /home/weblogic /home/weblogic/extResources). It will also need to have read on the files you want to show. If you want to create subdirectories inside of extResources, just make sure the apache user has "x" permissions.
Restart your server. Look for the apachectl cmd (probably /usr/sbin/apachectl) and run /usr/sbin/apachectl restart.
Test your files with a web browser (e.g. http://projects.yourcompany.com/ext/images/topnav-banner-bg.gif )

Customizing page header

You can change both size and content of the header at the top of the page.

To change the size, create the following token
- prm.custom.topmenu.height
- It should be a text value with header height in pixels

To set custom content
- Create file page.html or page.jsp
- Create or update token
  - prm.custom.topmenu.content
  - with the text value 'html' or 'jsp'
- To use the standard header, remove prm.custom.topmenu.content or give it a blank value.

Modifying the Project.net EAR file

Worst case, it is always possible for to unzip the Project.net EAR file and modify, replace and add static resources as well as compliled JSPs, servlets and Java classes. However, these modifications must be maintained by by hand during upgrades since they will not be present in future releases by Project.net

Interface customization via CSS

You can customize any CSS file with dynamic values from either an existing or new configuration token.

For example, the following static CSS with a fixed value for left::

file /css/ourcss.css

div#ourFrame, {
  position: absolute;
  left: 10;
}

Can have its value contained in the configuration token prm.ourframe.left using this format

div#ourFrame, {
  position: absolute;
  left: $$prm.ourframe.left$$;
}

At runtime, $$prm.ourframe.left$$ will be replaced with the database value for the token prm.ourframe.left.

Note: To use this feature you have to add filter mapping for your css file into web.xml for your application server (both for WebLogic and Tomcat)

<filter-mapping>
	    <filter-name>CSSDbValues</filter-name>
	    <url-pattern>/css/ourcss.css</url-pattern>
    </filter-mapping>

You can also define a default value in case the token was not added into database or does not have a value. Default values should be added to filter declaration as init param in the correct web.xml files.

<filter>
	    <filter-name>CSSDbValues</filter-name>
	    <filter-class>net.project.css.CSSDbValues</filter-class>
	    <init-param>
	    	<param-name>prm.ourframe.left</param-name>
	    	<param-value>1o</param-value>
	    </init-param>
    </filter>

Replacing the login screen

Create html (or jsp) page for custom login screen and save it in '/custom'.

Now, add or edit the following token

prm.custom.loginscreen.content
with text value 'html' or 'jsp'
- To use the standard login screen, remove prm.custom.loginscreen.content or give it a blank value.

<form action="/LoginProcessing.jsp"" method="post">
<input type="hidden" name="userDomain" value="1000">
Login: <input type="Text" name="J_USERNAME" size="20" maxlength="32"><br/>
Pass: <input type="Password" name="J_PASSWORD" size="20" maxlength="20"   MAXLENGTH="60"><br/>
<input type="submit" name="submit" value="Submit">
</form>

Download in other formats:

Plain Text

Logo	IF
Text	T
Links	T
Layout	J
Top page header	TJ
Bottom of page branding	fixed
Top two bars (grey and black) on pages	IF
Personal, Business, Project, Resource, Enterprise icons	IF
Action toolbar icons	IF
Control visibility of tools in Navigation Toolbar	T
Channel bar text	T
Channel bar icons	IF
Page text	T
Text style (font, size, face)	CSS
Custom login screen	TJ