Version: Early Access

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 Digital.ai 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 a 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.

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.

important

Custom branding changes can be overridden when your site is upgraded to a new version. You may have to reapply any look-and-feel modifications after an upgrade.

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.
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.
  Logo Change Guidelines
  - The logo can be of any format—PNG, Gif, JPEG, and SVG. However, use a transparent logo file such as SVG. JPEG files, for example, are not transparent.
  - The logo can be of any size, but choose the aspect ratio appropriately. However, the logo width should be at least 100px.
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.

note

For the general steps for changing the look and feel of a page, see Customize a Page, Picture, Text String, or Other Elements on Your Site.

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

tip

If both 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. 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][siteoptiontokens.html#enablesitenews] 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 Digital.ai 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.

note

For the general steps for changing the look and feel of a page, see Customize a Page, Picture, Text String, or Other Elements on Your Site.

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.

note

Before customizing your site, download the branding files. See Customize a Page, Picture, Text String, or Other Elements on Your Site.

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 file templates/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][movedbdmintoonepginstance]), 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/13.15 /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/13.15 /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
```