Customize TeamForge

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

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.