You can redesign some aspects of your site to suit your organization's needs and preferences.

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
Sample jar File Structure

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.

  • Custom event and customizations are applied if this entry is set to True (default value).
  • Custom event and customizations are not applied if this entry is set to False.

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 priority of the customization. Customizations are sorted by the servlets based on the priority. Customizations with low priority are included at the end. The priority value could be from 1 to 100, 100 being the default value.

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

  1. 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 needed MANIFEST.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>
    
  2. 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
    
  3. Upload the generated jar file as a custom event so that your customization is applied to TeamForge pages.
    1. Log on to TeamForge as a site administrator.
    2. Select My Workspace > Admin.
    3. Select Projects > System Tools > Customizations and click Create.
    4. Click Choose File, select the customization jar file and click Add.
  4. Enable, disable, delete or download a customization.
    1. Select My Workspace > Admin.
    2. Select Projects > System Tools > Customizations.
    3. Select one or more customizations (check boxes) you want to enable or disable and click Enable or Disable.
    4. Select one or more customizations (check boxes) you want to delete and click Delete.
    5. 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.

  1. 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.
  2. In the look project, check out the branding repository.
  3. 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.
  4. 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.
  5. Commit the changed files into your site’s branding repository.

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.

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.

  • The siteNews html block itself is not customizable.
  • By uncommenting this siteNews object and commenting out communityNews object, site news can be displayed across all projects in the site.
  • In addition to enabling the siteNews html block, you must set ENABLE_SITE_NEWS token to true if you want site news published on your site’s home page.

communityNews

The html block that shows community news. By uncommenting this object, and commenting out siteNews object, community news (news from the look project) can be displayed across all projects in the site.

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 com.collabnet.ce.customization.IProjectData.

adminList

The list of project administrators. Each object of the list implements the interface com.collabnet.customization.IUserRow.

memberList

The list of project members. Each object of the list implements the interface com.collabnet.customation.IUserRow.

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 com.collabnet.ce.customization.widgets.Button.

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 com.collabnet.ce.customization.widgets.Button.

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.

  1. In your local copy of the branding repository, create a directory called templates/mail.
  2. 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
    
  3. 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.

  1. Create conf.d/httpd/httpd.conf.d under /opt/collabnet/teamforge/etc/ directory.
  2. Include custom.conf under /opt/collabnet/teamforge/etc/conf.d/httpd/httpd.conf.d/.
  3. 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/
  1. Run the httpd -e info command to know the Apache configuration/syntax errors, if any.

Remove Custom Apache Configuration

  1. To remove custom configuration:
    cd /opt/collabnet/teamforge/etc/conf.d/
    mv httpd/ httpd_old
    
  2. 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.

  1. 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/.

  2. 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/

  3. 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/9.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/9.6/reports/pg_hba.conf.

  1. Check the postgresql.log file for any syntax errors: /opt/collabnet/teamforge/log/pgsql/postgresql.log.

Remove Custom PostgreSQL Configuration

  1. 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
    
  2. Provision services.
    teamforge provision