These instructions support only some basic types of customization. Almost infinite varieties of customization are possible. To get into specific customization options in more detail, search or post a question on the TeamForge discussion forum or talk to your CollabNet representative.
Customize TeamForge Using a Custom .jar
File
You can customize your TeamForge site by building a maven project and uploading the customization jar file that extends or customizes TeamForge.
Maven projects are built and packaged to generate TeamForge customization jar and MANIFEST.MF
files. The generated customization jar file is then uploaded to TeamForge. When you upload a customization jar, it is processed and if it has a custom event, it is registered. Later, if it has customizations, they are cached by the customization mechanism for a cost-free access at every request. Cached customizations are then served by the following three servlets:
Servlet | Description |
---|---|
/ctf/api/main/js-customization |
Retrieves all the Javascript customizations. |
/ctf/api/main/css-customization |
Retrieves all the CSS customizations. |
/ctf/js/modules/customization-<customization-name>/<resource-name>; |
Resolves the resource relative to the main folder configured for the given customization name. |
The customization mechanism provides access to all the enabled customizations in the cache.
A customization jar can contain:
- Custom events
- Javascript customizations
- CSS customizations
- Custom bundles

Here’s a sample customization jar file.
While custom events are configured through an events.xml
file in the META-INF
folder in the jar file, Javascript, CSS and custom bundles are configured through META-INF/MANIFEST.MF
entries.
Here’s a list of META-INF/MANIFEST.MF
entries:
MANIFEST.MF entries | Description |
---|---|
CTF-Customizations-Enabled |
The entry to enable or disable a customization. This entry applies to custom event and customizations.
|
CTF-Customization-Name |
The entry to set the name of the customization to be used for getting bundles. |
CTF-Customizations-Priority |
The entry to set the priority for customizations. Allows you to specify the |
CTF-JS-Customization |
Path to a Javascript file. |
CTF-CSS-Customization |
Path to CSS stylesheet. |
CTF-Bundle-Customization |
Path to the main bundles directory. |
An Illustration of How to Add a CSS Customization
-
Build a customization project.
Maven project structure that includes a custom stylesheet file as a resource:
css-customization% find -type f ./pom.xml ./src/main/resources/custom/custom.css css-customization %
css-customization % cat src/main/resources/custom/custom.css div.core-footer { background-image:url('/ctf/js/modules/customization-mybundles/img/footer.png'); } css-customization %
The
pom.xml
descriptor, uses the packaging plugin for setting the neededMANIFEST.MF
properties:<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.ctf.customizations.samples</groupId> <artifactId>css-customization</artifactId> <version>1.0-SNAPSHOT</version> <packaging>jar</packaging> ... <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> <version>2.4</version> <configuration> <archive> <manifestEntries> <CTF-Customizations-Enabled>True</CTF-Customizations-Enabled> <CTF-Customization-Name>mystyles</CTF-Customization-Name> <CTF-CSS-Customization>custom/custom.css</CTF-CSS-Customization> </manifestEntries> </archive> </configuration> </plugin> </plugins> </build> ... </project>
- Package the Maven project.
css-customization % mvn package [INFO] Scanning for projects... ... [INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ stylesheet --- [INFO] Building jar: /home/matias/workspaces/ctf/css-customization/target/mystyles.jar [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.959s [INFO] Finished at: Wed May 21 20:26:28 ART 2014 [INFO] Final Memory: 8M/105M [INFO] ------------------------------------------------------------------------ css-customization %
Generated jar:
css-customization % jar tvf target/mystyles.jar 207 Wed May 21 20:26:28 ART 2014 META-INF/MANIFEST.MF 17 Wed May 21 20:26:26 ART 2014 custom/custom.css 1092 Wed May 21 20:16:06 ART 2014 META-INF/maven/com.ctf.customizations.samples/css-customization/pom.xml 132 Wed May 21 20:26:28 ART 2014 META-INF/maven/com.ctf.customizations.samples/css-customization/pom.properties css-customization %
Generated
MANIFEST.MF
:Manifest-Version: 1.0 Built-By: matias Build-Jdk: 1.7.0_55 CTF-Customization-Name: mystyles CTF-CSS-Customization: custom/custom.css CTF-Customizations-Enabled: True Created-By: Apache Maven 3.0.4 Archiver-Version: Plexus Archiver
- Upload the generated jar file as a custom event so that your customization is applied to TeamForge pages.
- Log on to TeamForge as a site administrator.
- Select My Workspace > Admin.
- Select Projects > System Tools > Customizations and click Create.
- Click Choose File, select the customization jar file and click Add.
- Enable, disable, delete or download a customization.
- Select My Workspace > Admin.
- Select Projects > System Tools > Customizations.
- Select one or more customizations (check boxes) you want to enable or disable and click Enable or Disable.
- Select one or more customizations (check boxes) you want to delete and click Delete.
- Select one or more customizations (check boxes) you want to download and click Download.
Customize a Page, Picture, Text String, or Other Elements on Your Site
Follow these general instructions to customize a page, picture, text string, or other element on your site.
- Download the sample branding files. Choose one of these files:
- Basic branding package: Contains the files you need to do most of your branding tasks. Safest to use this file if you are doing your own branding.
- Advanced branding package: Contains all the files that can be customized. For use when someone from CollabNet is helping you with your branding.
Note: It is important that you have the most recent version of this archive as a starting point. Check that the version number at the top of thereadme.txt
file in your copy of the branding package is the same as your version of the application. If it is not the same, check www.collab.net to see if there is a more recent version. - In the
look
project, check out the branding repository. - Copy the default version of the appropriate file from the branding zip file to the equivalent directory in your local copy of the branding repository.
- Change the file to produce the results you want. For example:
- To change a logo on your site’s home page, overwrite the
home.gif
file with a new file of the same name. - To change a logo on a project home page, overwrite the
project.gif
file with a new file of the same name.
- To change a logo on your site’s home page, overwrite the
- Commit the changed files into your site’s branding repository.
Important: Your branding repository does not have to contain all the files that are in the sample branding zip file, but the structure of your repository must be an exact mirror of the structure of the sample file set.
Customize the Home Page of Your Site
To change the content of your site’s main page, replace the home.vm
file or add either domain_home.html
or DomainHome.html.html
file to the html
folder in the branding repository.
The \branding\templates\sfmain\home.vm
template controls the look, feel and structure of the standard home page. The default version allows users to log in and sign up for new user accounts, if CollabNet TeamForge is configured to allow user self-creation.
If the DomainHome.html.html
or domain_home.html
file is checked into the branding repository, the contents of the file are displayed as the site home page.
DomainHome.html.html
and domain_home.html
files exist in the repository, the contents of the DomainHome.html.html
are displayed.Edit the home.vm template to produce the page you want. You can change these objects on the site home page:
Object | Description |
---|---|
siteNews |
The html block that shows site news.
|
communityNews |
The html block that shows community news.
By uncommenting this object, and commenting out |
mostActiveProjects |
The html block that shows the most active projects. The html block itself is not customizable. |
displayActivityGraph |
A flag that indicates that the activity graph should be displayed. |
displayTeamForgeLinks |
A flag that indicates that CollabNet TeamForge quick links should be displayed. |
Customize the Home Page of Projects
To change the default main pages of the projects on your site, edit the project_home.vm
file.
Edit the project_home.vm
template to produce the project page you want. You can change these objects on the project home page:
Object | Description |
---|---|
projectData |
The object that contains the information about the project. It implements the interface |
adminList |
The list of project administrators. Each object of the list implements the interface |
memberList |
The list of project members. Each object of the list implements the interface |
projectMember |
A flag that indicates that the user is a member of the project. |
joinProjectButton |
The button that contains the link to the Join Project page. It returns a |
useCustomHomePage |
A flag that indicates that the page shows the Wiki Home page instead of the standard Home page. |
customHomePage |
The html that displays as the Project Home page. |
editCustomHomePageButton |
The button that is used to edit the custom Home page. It returns a |
projectAdmin |
A flag that indicates whether or not the current user is a Project Admin. |
useCustomProjectLogo |
A flag that indicates that the Wiki project logo image will be used instead of the standard project logo. |
customLogoPathString |
The url from where the custom project logo image can be loaded. |
Change Your Site’s Outgoing Emails
When you site sends out automated emails, the text of the emails can be customized to fit your site’s specific needs.
You control screen labels and messages by overriding the resource bundle keys that specify the text strings that appear in Velocity macros and JSPs.
- In your local copy of the branding repository, create a directory called templates/mail.
-
In the
templates/mail
directory, create a file containing the custom content for an email that the system sends out.Give the file the same name as the equivalent sample email file in the branding files package. For example, to override the email that is sent out to new members of the site, name the file
templates/mail/user_welcome.vm
. Use Velocity syntax to identify the parts of the email, like this:##subject Welcome to our TeamForge site! ##subject ##body Here is the content that I want to appear in emails coming from my site... ##body
Note: To customize a template in a specific language, identify the locale as an extension to the file name. For example, to create a user welcome file in Japanese, name the filetemplates/mail/user_welcome_ja.vm
- Commit your new and changed files into the repository.
Customize Your Apache Configuration
The following instructions illustrate how you can include custom configuration to Apache and disable the same if not required.
- Create
conf.d/httpd/httpd.conf.d
under/opt/collabnet/teamforge/etc/
directory. - Include
custom.conf
under/opt/collabnet/teamforge/etc/conf.d/httpd/httpd.conf.d/
. - Provision services.
teamforge provision
The following warning message is displayed, which you can ignore.
Custom configuration found in /opt/collabnet/teamforge/etc/conf.d/httpd/httpd.conf.d has been applied. Please be informed that such configuration may impact the reliability of TeamForge.
The following line is added to /etc/httpd/conf/httpd.conf
:
Include /opt/collabnet/teamforge/etc/conf.d/httpd/httpd.conf.d/
- Run the
httpd -e info
command to know the Apache configuration/syntax errors, if any.
Remove Custom Apache Configuration
- To remove custom configuration:
cd /opt/collabnet/teamforge/etc/conf.d/ mv httpd/ httpd_old
- Provision services.
teamforge provision
Customize Your PostgreSQL Configuration
The following instructions illustrate how you can include custom configuration to PostgreSQL and disable the same if not required.
-
Create
conf.d/pgsql/pg_hba.conf.d/
under/opt/collabnet/teamforge/etc/
directory.If the reporting service is running on a separate port (see Create a Single Cluster for Both Database and Datamart), create
conf.d/reports-pgsql/pg_hba.conf.d/
under/opt/collabnet/teamforge/etc/
. -
Include
custom.conf
under/opt/collabnet/teamforge/etc/conf.d/pgsql/pg_hba.conf.d/
.If the reporting service is running on a separate port, include
custom.conf
under/opt/collabnet/teamforge/etc/conf.d/reports-pgsql/pg_hba.conf.d/
-
Provision services.
teamforge provision
The following warning message is displayed, which you can ignore.
Custom configuration found in /opt/collabnet/teamforge/etc/conf.d/pgsql/pg_hba.conf.d has been applied. Please be aware of that such configuration may impact the reliability of TeamForge.
If the reporting service is running on a separate port:
Custom configuration found in /opt/collabnet/teamforge/etc/conf.d/reports-pgsql/pg_hba.conf.d has been applied. Please be aware of that such configuration may impact the reliability of TeamForge.
Configuration settings from custom.conf
are included in /var/lib/pgsql/11.6/data/pg_hba.conf
.
If the reporting service is running on a separate port, configuration settings from custom.conf
are included in /var/lib/pgsql/11.6/reports/pg_hba.conf
.
- Check the
postgresql.log
file for any syntax errors:/opt/collabnet/teamforge/log/pgsql/postgresql.log
.
Remove Custom PostgreSQL Configuration
- To remove custom configuration:
cd /opt/collabnet/teamforge/etc/conf.d/ mv pgsql pgsql_old
If the reporting service is running on a separate port:
cd /opt/collabnet/teamforge/etc/conf.d/ mv reports-pgsql reports-pgsql_old
- Provision services.
teamforge provision
[]:
[]: