Customize TeamForge

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:

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:

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.
   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 the readme.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.
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.
   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.

Edit the home.vm template to produce the page you want. You can change these objects on the site home page:

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:

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
   

   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 file templates/mail/user_welcome_ja.vm
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/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.

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
   

[]:

[]: