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

Here's a 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

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>

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