Customizing the subpages

The following sections describe customizing the subpages in the CollabNet Baseline Project template.

Customizing the left navigation pane and the toolbar

The CollabNet Baseline Project instance adds the following links to the left navigation pane and to the Stages subpages in the toolbar:

• Definition
• Design
• Code & Build
• Testing
• Deployment
• Support.

You can rename, add, or delete any of these subpages. The directories that contain the subpages are named using the convention n-stagename, where

• N is a number that determines the order in which the subpage appears in the top Navigator toolbar.
  In the navigator, subpages are listed in numeric order. While the subpages do not need to follow a strict numeric sequence, n must be a simple integer, such as 1, 2, or 5. The integer must be followed by a dash ("-"). Any other format (for example, 1.a, 1/1, and so on) cannot be recognized as a subpage directory. Any directories that fail to follow this convention will be treated as a simple (non-subpage) subdirectory of the parent directory.
• Stagename is the name of the subpage.

If you add a subpage, you must renumber the directories for the later subpages. If you add or delete any subpages from the subpage directory structure, both the top navigation toolbar and the subpage links in the left navigation pane are updated.

When adding a subpage, you may want to also add icons. All icons must be exactly the same size. The icon files should be in GIF format and have transparent backgrounds. If you are supplying new icons, you will need two of them:

• A small icon (28 x 28) in a normal state.
• A small icon in a rollover state.

Using Web-safe 216 color palette is recommended for compatibility with systems that have 8-bit or less graphics capability. If this is not an issue, you may want a different color palette for systems that are capable of 16-bit or better graphics. Note that these icons must be exactly the same height to work properly.

You can also create tool tips that are shown when users move their cursor over the icon or label in the Subpage Navigator toolbar.

The following procedures assume you are working on a project template in the project-templates directory. You can preview a project template from the Project templates link in the left navigation pane on the Administration tab. Or, you can create a test project, modify the template files for this project, and later copy the contents back into the project-templates project.

To add, remove, or modify subpages in the top Navigator toolbar and left navigation pane:

1. If you have not done so already, create a template directory that contains all of the files and directories from the CollabNet Baseline Project directory or a custom template.
   For example, you may create project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the template directory. Note that if you create a project that is based on such a template, you can modify the template in the www directory for that project.
2. Copy an existing directory in this structure to a new directory and use the n-stagename naming convention to name this directory.
   For example, you could add the following directory: project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/NewFirstSubpage.
3. Renumber the other folders as needed.
   For example, using the above example of adding a new Stages subpage at the beginning, you would edit the remaining directory names as follows:
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Definition
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Design
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Code & Build
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Testing
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Deployment
   project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Support
4. Add the newly-created subpage using your version control tool (if you are creating a new subpage), and update any modified files.
5. Commit all changes using your version control tool.

To associate icons with an added subpage in the navigation toolbar:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the project template directory.
2. Navigate to the subpage directory where you want to add the icons, for example, cn-project-pages/Stages/Definition.
3. Using Subversion, add the new icons to the icons directory of this project template.
   Name these icons small.gif and small-over.gif.
   Alternatively, you can give these files .jpg or .png extensions (lowercase only).
4. Using your version control tool, commit your changes. Note: If you do not provide a rollover icon ("small-over.gif"), the image disappears when you roll the mouse over the small.gif icon.

To add or modify tool tips for a subpage link in the navigation toolbar:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the project template directory.
2. Navigate to the subpage directory where you want to add a tool tip, for example, cn-project-pages/Stages/Definition/.
3. View the snippets sub-directory of the subpage directory.
4. Using Subversion, edit the description.txt file in the snippets directory.
5. Using your version control tool, commit your changes.

To determine if the navigation toolbar is shown on project home pages:

1. Log in as a domain administrator.
2. Click the Administration tab.
3. Click Configure > project defaults in the left navigation pane.
4. In the Application Lifecycle Management section, check the Lifecycle Management Home Page option to display the toolbar on the project home page.
   Note: If you enable the Lifecycle Management Home Page option, project owners still have the option to supress the navigation toolbar on the home page for specific projects.

Basic customizations for a landing page

Basic customizations include the following:

• The links in the Activities area (the light blue background).
  You can modify the links to Project Tracker queries, links to external applications, and links to data generated by external applications. You can also add small icons to groups of query links in the Activities area (the field with the light blue background).
• Links to resources that are relevant to the subpage or page.
  These are links to anything that you think would be of interest to users. For example, on the landing page for the Definition subpage, you may want to add resource links to web sites that provide information on collecting requirements.
• Arbitrary content that you create as needed.
  The CollabNet Baseline Project provides snippet files that allow you to extend the default content of each page.
• The lifecycle artifacts and attributes.
  Some of the artifacts and attributes that are supplied for use with the CollabNet Baseline Project must be modified. See Required customizations of CollabNet Baseline Project artifacts, attributes, and rules for details. In addition to the required customizations, you can add or modify these artifacts and attributes. If you do this, note that you may also need to update the queries that are shown in the Actvities area (the light blue background). See Customizing the lifecycle attributes, artifacts, and queries for details.

Important: If you add content to the files in the snippets directories, be aware that all HTML must conform to CollabNet's scripting-safe coding conventions.

Customizing the landing pages

The following procedures describe common customizations for the landing pages.

Customizing an activity link (a link in the blue area) for a Project Tracker query

Many of the Activity links are queries that return Project Tracker artifacts. For example, on the Definition page, there is a query that returns all requirements that have been assigned to the Definition subpage. Another Help topic describes the query criteria for the lifecycle artifacts. See the lifecycle artifact Help for details.

Task overview: Modifying lifecycle artifacts and queries

1. Edit the relevant artifact type and attribute definitions.
2. Create a custom query that uses the new artifact type definition.
3. Copy the query URL in the browser address bar.
4. Edit the appropriate subpage page to display the new query.
5. Modify the query URL so that the domain prefix is removed and the special characters are escapted. For example, ensure that all instances of "&" are represented as "&".

To edit or create an artifact type definition:

1. Click the Administration tab.
2. Click Project Tracker > Artifact Types.
3. Follow the online Help to add or modify the appropriate artifact type.
   Note: After adding or modifying the artifact type, a project owner must add it to any existing projects where the artifact type is used.

To create a custom query:

1. Assuming that you have created a project that uses the template that you are modifying, click the Projects tab, and select the project.
2. Click Project Tracker > Query Artifacts in the left navigation pane.
3. Click Create New.
4. Click Advanced Query.
5. Define the query criteria.
6. When the query results produce the desired result, copy the query results URL from the browser address bar.
7. Paste the URL into a text file.

To edit the subpage to reflect the changes:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the project template directory.
2. Using Subversion, update the top.html. file in the snippets directory.
3. Edit the top.html file or bottom.html file in the snippets directory for the appropriate subpage or page.
   For example, you would edit project-templates/trunk/www/templates/My-Process/cn-project-pages/Stages/Definition/snippets/top.html.
   Where My-Process is the name of the project template directory.
4. Paste the query results URL in the appropriate location in the Activities area or a table.
   For example, to update a URL in the Activities area, find the appropriate list item below the <!-- Start Activity Box --> comment, for example:
   <li><a href="/servlets/Scarab/remcurreport/true/template/Search.vm?nextTemplate=IssueList.vm&action= Search&eventSubmit_doSearch=Search& grp=si&si=&qattdelim=true&it=3&mitdelim=true& col=11%2C13%2C2&coldelim=true" title="View all requirements that have been eliminated from consideration">All excluded </a></li>
   Note: The pasted URL will not be pretty.
5. Remove the prefix for the query URL.
   The prefix is http or https://project.domain, where project is the name of the project where the query was captured and domain is the domain where the project resides. The URLs should begin with "/servlets/Scarab".
6. Ensure that special characters in the URL are escaped. For example, replace all instances of ampersand ("&") with the HTML tag "&amp;".
7. Add information in a title attribute to display a tool tip when the user places the cursor over the activity link.
8. Commit the changes using your version control tool.

To customize an icon for an activity link (in the blue area):

1. Navigate to the subpage directory where you want to add an activity link icon, for example, cn-project-pages/Stages/Definition/.
2. View the snippets sub-directory of the subpage directory.
3. Using Subversion, edit the top.html. file in the snippets directory.
4. In top.html, add the class name of the icon to the Div tag that delimits the group of queries where you want to add the icon, for example:
   <div class="view_icon">
   CollabNet supplies the following icons:

   Class name: add_icon
   Image path: /branding/images/add-new-artifact.gif

   Class name: download_icon
   Image path: /branding/images/download.gif

   Class name: edit_icon
   Image path: /branding/images/edit.gif

   Class name: launch_icon
   Image path: /branding/images/launch.gif

   Class name: report_icon
   Image path: /branding/images/generate-report.gif

   Class name: view_icon
   Image path: /branding/images/query-artifacts.gif

5. To use a new a new icon in the Activity area, add the icon files to this location:
   /branding/images/
   
6. Also, if you are adding a new, icon, use your version control tool to add the new class to this CSS file:
   src/htdocs/overridable/static/csi/css/alm.css
   When referring to images within the CSS file, the paths would start with the following:
   /branding/images/

To add or remove a column of activity links:

1. Navigate to the subpage directory where you want to add or remove the column of links, for example, cn-project-pages/Stages/Definition/.
2. View the snippets sub-directory of the subpage directory.
3. Using Subversion, edit the top.html. file in the snippets directory.
4. Add or remove the column from the activity links table, using the following guidelines:
   To preserve the dividers between the columns, code the column using the tag "<td class="activitytable_center">.
   For the far left column, code the column using the tag "td class="activitytable_left">.
   For the far right column, code the column using the tag "td class="activitytable_right">.
   Each <td> element has an inline CSS style="width:xx%;" attribute. The intent of this attribute is to create columns of uniform width. If you change the number of columns, the width value is calculated as 100 divided by the number of columns.

To customize the resource links on a subpage or page:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the project template directory.
2. Navigate to the subpage directory where you want to edit a resource link, for example, cn-project-pages/Stages/Definition/.
3. View the snippets sub-directory of the subpage directory.
4. Using Subversion, update the bottom.html. file in the snippets directory
5. Open the bottom.html. file in an editor.
6. To delete information from the Resource table, remove the corresponding row in the resources table.
7. To add a resource link, create a new row in the table, as follows:
   <tr class="b">
   <td>[Your definition best practices]</td>
   <td>[<a href="/nonav/cn-project-pages/help/customizing_alm_links.html" onclick="return launch(this.href, 1);" title="Note: link may open in new window" class="helplink">Link - TBD</a>]</td>
   </tr>
   <!-- onclick="return launch(this.href, 1);" makes the link open in a small new window -->
   <!-- Use onclick="window.open(this.href); return false;" to make the link open in a normal-sized new window -->
   <!-- Edit the title to change tool tip -->
   <!-- Remove class="helplink" to prevent question mark cursor -->
8. To ensure that the shading of the rows of this table alternates between light and dark grey, check the class attribute on the tr tag and ensure that these tags alternate between "class=a" and "class=b".
9. Using your version control tool, update the file again and commit the changes.

To add tables and other content to the landing page:

1. Navigate to the project template directory.
   For example, you may go to project-templates/trunk/www/templates/My-Process/cn-project-pages
   Where My-Process is the name of the project template directory.
2. Navigate to the subpage directory where you want to edit a resource link, for example, cn-project-pages/Stages/Definition/.
3. View the snippets sub-directory of the subpage directory.
4. Using Subversion, edit the bottom.html. file in the snippets directory.
5. Add the new content to the bottom.html file.
   Note: If you are adding a table, it is recommended that you follow the conventions for table formatting. To ensure that the shading of the rows of this table alternates between light and dark gray, check the class attribute on the tr tag and ensure that these tags alternate between "class=a" and "class=b".

Creating sub-directories of a landing page

When a link on a landing page takes a user to a subdirectory, you can configure the subdirectory to have the same general look and feel as the landing page, including the following:

• A subpage navigation toolbar
• Documentation tables that are automatically built and modified when users add document files to a documents directory.
  See the user Help on working with Definition subpage documents for an example of this feature.

To make use of these features, the subdirectory must contain the following:

• A snippets directory
• A top.html file within the snippets directory
  This file provides a work area where you can add content.
• A documents directory
  When users add documents to this directory, they will be automatically displayed in the documents table shown on the relevant subpage. The documents table is generated automatically and is placed below the content in the top.html snippet if one exists for the directory or subdirectory.

Files with arbitrary content must be named top.html or bottom.html, and must have a ".html" (lowercase) extension. For example, in the Support subpage for the default CollabNet Baseline Project, there is a link to metrics in the Work Products column of the Activities area. The page that is displayed when users click the Support metrics link is based on the presence of the documents and snippets subdirectories. A snippets subdirectory would contain the following top.html file:

    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <h1 class="alm_h1">
         Metrics
    </h1>
    <div>
         [Instructions on using this page go here.]
    </div>

Note: The meta tag is required for UTF-8 encoding. If you enter non-ASCII characters in the snippets, this meta tag ensures that these characters are displayed correctly in the browser.

Creating a process documentation table in a subdirectories

As with the landing pages for a subpage, you can display a Process Documents table on the landing page for a subdirectory. To do this, you create a documents directory within any new landing page subdirectory. As with other Process Documents tables, the presence of a documents subdirectory causes a Process Documents table to be displayed along with an upload link that allows users to add documents to the table.

Note, however, that a subdirectory cannot contain document templates. In the Process Documents table that is displayed on these pages, the View Document Templates link is not displayed. On the Document Templates page, the new subdirectory will not be listed.

Restricting access to a subpage

If you want to restrict a user's ability to view a particular subpage, you can do so using the permissions scheme in CollabNet. In each page directory that contains subpages, there is a folder for inaccessible icons. These are "grayed" icons that are displayed if the user logs in to an account that has a role that lacks permission to view a particular subpage. If you add a subpage or change the icon for a subpage, you will need to make a corresponding change in the folder for inaccessible icons.

To restrict access to a subpage:

1. Click the Administration tab.
2. Click Resource patterns > Add new resource pattern.
3. Create a resource with a pattern that omits the desired subpage, using the syntax, "cn-project-pages/(?!Stages/number).*"
   Where number is the number of the subpage that you want to deny access to.
   For example, you could add a resource named Cannot View Design Subpage with the following pattern:
   /cn-project-pages/(?!Stages/).*
4. Create a second resource that provides access to everything else except cn-project-pages, for example:
   /(?cn-project-pages/).*
5. Click Roles > Create new project role.
6. Create a role that denies Project Page - View access to a user.
7. Assign this role to any user who you do not want to view this subpage.