Customization Best Practices for SharePoint Project Management Central R2.0

SharePoint Project Management Central R2.0 is packed with great new features. Of these new features, the PM Central team is especially excited to announce the ability for users to customize PM Central. New customization features enable users to change logos or colors, and to retain those changes when upgrading to a PM Central version newer than R2.0 in the future.

Please note that while many of the following customization best practices are similar to our previous customization best practices blog post, there is new information, such as how List Rollup R5.0 works with PM Central as well as nested master pages and CSS files, so please pay particular attention to this new information to ensure the smoothest customization transitions.

The best practices cover a range of topics, divided into the following sections:

  • Recommended Best Practices for PM Central Customization
  • The Building Blocks of the PM Central Site Templates
  • What Happens During an Upgrade
  • Customizing the Master Page and Style Sheets
  • Adding and Viewing Additional Columns Using List Rollup R5.0 and the Data-Viewer Web Part
  • What Customizations Are Possible?
  • Frequently Asked Questions (FAQs)
  • Don’ts When Customizing PM Central

Recommended Best Practices for PM Central Customization

In general, we recommend that you do the following:

  1. Always back up your existing sites before making modifications.
  2. Keep a detailed log of your changes.

The Building Blocks of the PM Central Site Templates

Before you customize PM Central, make sure that you understand how the PM Central site templates work and how modifications can impact them.

The site templates consist of:

  • the site definition
  • the master page and style sheets (CSS)
  • ASPX pages and SharePoint Navigators
  • Bamboo Web Parts
  • list

Site DefinitionsThe webtemp.BambooProjectCentral.xml contains IDs that are associated with the site template and configuration. We use these IDs as identifiers for future upgrades.

For more information about templates and site definitions, read this Microsoft MSDN article.

Master Page and Style Sheets (CSS)

The table below lists the current master pages and CSS files that are used for the portfolio, department, and project sites in PM Central R2.0. Please note that there are changes in how the files are named in R2.0 to how they were named in R1.8.

Site Type

Master Page

CSS

Top Site

TopSite_Parent.master: main master page for the regular SharePoint theme
SA12Top.master: nested master page for the regular SharePoint theme

TopSite_Template_Parent.master: main master page for the custom template
SA12Top_Template.master: nested master page for the custom template

TopSite_TeamSite.css: main CSS file for the regular SharePoint theme
TopSite_TeamSite_Customer.css: CSS file that can be customized for the regular SharePoint theme

TopSite_Template.css: main CSS file for the custom template
TopSite_Template_Customer.css: CSS file that can be customized for the custom template

Department Site

DepartmentSite_TeamSite_Parent.master: main master page for the regular SharePoint theme
DepartmentSite_TeamSite.master: nested master page for the regular SharePoint theme

DepartmentSite_Custom_Parent.master: main master page for the custom template
DepartmentSite_Custom.master: nested master page for the custom template

DepartmentSite_TeamSite.css: main CSS file for the regular SharePoint theme
DepartmentSite_TeamSite_Customer.css: CSS file that can be customized for the regular SharePoint theme

DepartmentSite_Custom.css: main CSS file for the custom template
DepartmentSite_Custom_Customer.css: CSS file that can be customized for the custom template

Project Site

ProjectSite_Parent.master: main master page for the regular SharePoint theme
sa12.master: nested master page for the regular SharePoint theme

ProjectSite_Template_Parent.master: main master page for the custom template
sa12x.master: nested master page for the custom template

ProjectSite_TeamSite.css: main CSS file for the regular SharePoint theme
ProjectSite_TeamSite_Customer.css: CSS file that can be customized for the regular SharePoint theme

ProjectSite_Template.css: main CSS file for the custom template
ProjectSite_Template_Customer.css: CSS file that can be customized for the custom template

 

The Main Master Page and the Nested Master Pages

When one master page references another master as its master, the master pages are called “nested” master pages. You can have any number of nested master pages in a single master. This type of structuring enables the designers to create a number of nested masters without compromising the look and feel of the site.

In PM Central R2.0, the “parent” master pages, or the “main” master pages, will be customized our engineering team. All of the necessary components are defined in PM Central R2.0’s main master page. Users cannot customize the main master page. In the next release after R2.0, the main master pages will be modified when we run upgrades to newer versions.

Best Practices for Nested Master Pages and CSS Files

  • Nested master pages need to have the .master extension appended to its name.
  • Nested master pages also need to have all the controls that are mapped to the content placeholders and have content placeholders for the nested master pages themselves as well.
  • Users should not change the ContentPlaceHolderID of asp:content controls.
  • Nested master pages cannot be created in the design view of SharePoint Designer.
  • If users customize the nested master page for the site, it will not be updated when users upgrade to a newer version. Therefore, users’ modifications will be retained. If users did not modify the nested master page, the look and feel will be based on the parent/main master page after they upgrade to a newer version.
  • In the nested master pages, users should not rename the ContentPlaceHolder on asp:content controls. Renaming the ContentPlaceHolder results in errors on the pages when they are displayed in a Web browser.
  • If users customize the nested CSS file for the site, it will not be updated when upgrading to a newer version (upgrade timer job in the newer version). Therefore, users’ modifications will be retained. If users did not modify the nested CSS file, the look and feel will be based on the parent/main CSS file after they upgrade to a newer version (upgrade timer job in the newer version).

In general, the main master page references the CSS file. This design presents the banner, the font and the color that you see when you navigate to the portfolio site.

This is what the browser displays with just the portfolio site’s master page:

ASPX Pages and SharePoint Navigators

Multiple pages make up the portfolio and project sites, such as My Summary. These pages are displayed as tabs via SharePoint Navigators and the Top Site Navigators list. The list lists the pages and the URLs in order. For example, Project Central would be the first tab, and the My Summary tab would be next. The ASPX pages contain Web Parts that are used as data sources or to display data.

Bamboo Web Parts

The following is a list of the Web Parts included in PM Central and their function.

Lists

PM Central uses multiple lists to display data within the portfolio and project sites, including Tasks, Project Health, Issues, Risks, and more. These lists—especially the Tasks list—contain custom columns. The code references the columns using internal names in order to perform processes and to aggregate and display data. For example, the Parent Task column’s internal name is Owning Task ID. If this column is deleted, errors will occur.

What Happens During an Upgrade

For PM Central R2.0 and newer versions, the following actions occur during an upgrade:

  • The old site templates are backed up and replaced with new site templates, which reference the new master page and CSS using the IDs. If users made changes in the nested master pages and in the nested CSS files, those changes will not be touched.
  • New Web Parts and tabs are added using code.
  • The features are activated.

Customizing the Master Page

To check which pages use the master page, and open the site using Microsoft SharePoint Designer. Open the page that you want to check. Make sure that the page is in the code view to view the MasterPageFile properties.

Then go to the _catalogsmasterpage folder and right-click on the master page to see what master page is used for the site. If the master page is used for the site, the Set as Default Master Page and Set as Custom Master Page options are grayed out.

To customize the CSS for tags, we set a class or ID for those tags. Customize them using <style type=”text/css”> </style> in the CSS file or inline style.

Using Custom CSS

The CSS can be customized three ways:

1) By adding <style type=”text/css”> </style> to <head runat=”server”> </head>

2) By inline style on the tags where you want to customize the CSS

3) Or including the CSS file in <head runat=”server”> </head>

Changing Images at the Portfolio, Department or Project Sites

You can customize your portfolio, department or project sites adding your own graphics.

For example, to change poweredBy.png to button.png:

Navigate to Site Actions > View All Site Content. Under Picture Libraries, select Pics.

Upload your image to the Pics folder. Navigate to the portfolio site and select Site Actions > Site Settings > Master Page Gallery. Open the following two pages in SharePoint Designer:

  • TopSite_Template_Parent.master: the main master page for the custom template
  • SA12Top_Template.master: the nested master page for the custom template

From the nested SA12Top_Template.master, change the name logoSA12.png to button.png. Click Save.

Next, click Save for the TopSite_Template_Parent.master.

Note: When you open and save the nested master page, although you do not change anything to the main TopSite_Template_Parent.master, you must “un-ghost” the main/parent master page as well opening and save the parent master page file using SharePoint Designer. If you skip this step, all of the Web Parts will be closed, and pages will be shown as blank pages. If you forget to un-ghost the parent master page and all of the Web Parts are no longer there, see the steps below in How to Restore the Lost Web Parts.

The following dialog box is displayed. Click Yes to save.

Now the new logo is displayed.

How to Restore the Lost Web Parts

After you have made changes to the master pages and go back to the Web browser, your site might look like this:

Go back to SharePoint Designer. Select AllItems.aspx from the left pane. From the split option on the right pane, right-click and select Web Part Properties.

Deselect Close the Web Part and click OK.

Or, open the code and locate “<IsIncluded>false</IsIncluded>”, meaning that the Web Part is closed, and change it to “<IsIncluded>true</IsIncluded>”.

Changing the Style Sheet for the Portfolio, Department or Project Sites

For example, to change the black text color to purple for the PM Central is powered logo:

All CSS files are stored under _catalogsmasterpage. In this case, because we are using the custom template for the portfolio site, we need to modify the nested TopSite_Template_Customer.css.

  • TopSite_Template.css: the main CSS file for the custom template
  • TopSite_Template_Customer.css: CSS file that can be customized for the custom template

To change the style sheet, navigate to Site Actions > Site Settings. Under Galleries, select Master Pages. Choose the TopSite_Template_Customer.css file that you want to modify and check it out. Modify the file using SharePoint Designer, then check it back in.

Copy the lines from the TopSite_Template.css into TopSite_Template_Customer.css and change the color from #f5f5f5 to #800080.

Copy to TopSite_Template_Customer.css or define the class:

}

.bs-powered{

font-family:Verdana;

font-size:11px;

font-weight:bold;

color:#800080;

}

You can also change the color in the 12 hive folder, but if you do this, the change occurs globally, and it will affect all new sites that are created.

Adding and Viewing Additional Columns Using List Rollup R5.0 and the Data-Viewer Web Part

For example, we want to add an additional column named Overall Health to the Project Health List, and we want the information in the column to be rolled up to the portfolio site.

First, navigate to the Project Health List at the portfolio and project sites and go to List Settings. Create a new column as a Choice column and name it Overall Health. Add the values as Neutral, Good and Poor.

Then, from the portfolio site, navigate to ./PMCentralPages/ListRollupSchema.aspx.

Edit the Project Health – Active Project schema.

Click on Select Columns.

Add Overall Health from Available Columns to Selected Columns.

Select Create/Update Schema.

Navigate to the portfolio site. From the Project Central tab’s Project Summary, edit the Data-Viewer Web Part.

Add Overall Health to Selected Columns again. Click Apply and then OK.

The new Overall Health column is displayed on the Project Summary.

What Customizations Are Possible?

With a better understanding of how PM Central’s pages are created, you can determine what customizations can be applied to PM Central R2.0 (or newer) and what will happen to your customizations after an upgrade.

In general, you can modify your portfolio, department or project sites using the recommended guidelines on how to customize any SharePoint site. Most modifications using the standard browser interface are acceptable. Please note, however, that in PM Central R2.0 or newer, if you have added Web Parts to pages that need to be replaced in the next upgrade (due to new features having been added to the .aspx pages), those Web Parts will not be retained in the upgrade process.

The table below covers several customizations and whether or not you will lose the customizations after an upgrade.

Description PM Central R2.0 or Older After Upgrade
1 Add new Web Parts to the pages Yes, it is OK. No, it is not OK.

 

2 Add additional columns and views to existing Lists

Add new Lists (e.g., project tasks list, status reports, custom lists, etc.) and Document Libraries (Wiki, Collaboration, translation, Shared Documents folders, etc.)

 

Yes, it is OK. Yes, it is OK.
3 Change the look and feel of themes and graphics Yes, it is OK. No, it is not OK.

It is OK in R2.x. Note: Please follow our policies for customization.

4 Add new navigation tabs on the portfolio, department and project sites

 

Yes, it is OK. Yes, it is OK.
5 Create new pages from a Web Part page in SharePoint Yes, it is OK. Yes, it is OK with the condition that new pages should be stored under the PMCentralPages list in the Document Library.

 

6 Modify the master page and CSS files with or without SharePoint Designer Yes, it is OK. No, it is not OK.

It is OK in R2.x. Note: Please follow our policies for customization.

7 Add additional columns and views to existing Lists; add new Lists; add documents to the Document Libraries; change logos; and save the template as a standard site template to use for creating other project sites Yes, it is OK. Yes, it is OK.

Frequently Asked Questions (FAQs)

Can I replace the master page with another master page that has a different name?

Yes, for PM Central R2.0 or older.

However, after you upgrade to PM Central  R2.0 or older versions, you will lose this customization after you upgrade because the code and features reference the elements with the names of the original master page.

When you rename the master page to another master page with a different name, the features will not be activated on your existing sites; therefore, you will not see any new changes with your existing sites. The workaround is to save your master page. After the upgrade, rename the build’s master page to old and rename your master page to SA12Top.master or SA12Top_Template.master.

Can I redesign the pages by adding a new Web Part?

Yes, for PM Central R2.0 or older.

After you upgrade to PM Central R2.0 or older versions, you will lose this customization because, during the upgrade, the application replaces the pages with the pages from the new build.

Can I modify CSS?

Yes, for PM Central R2.0 or older. Follow the steps outlined above in Changing the Style Sheet for the Portfolio, Department or Project Sites.

Can I change the master page to point to another CSS file?

After you upgrade to PM Central R2.0 or older versions, you will lose this customization because during the upgrade, the application will replace the old master pages with the new master pages from the new build, and it will reference the CSS files from the new build.

Can I save PM Central sites as site templates and then use them to create new sites?

Yes, you can save the project site as a site template, but there are future implications if you customize the site using SharePoint Designer.

Any new site that is created from a site template that is derived from the original PM Central site needs to access the required site definitions. If you create a site in the same Web application where PM Central is installed, you shouldn’t have any problems. However, if you create a new site in a different farm or Web application, you need to install PM Central on that farm first. This is because the site templates contain pages with the Bamboo Web Parts, and these Web Parts were deployed to the original Web application, not the new Web application.

For more information about templates and site definitions, read this Microsoft MSDN article.

Can I modify the site and save it using SharePoint Designer?

If you use SharePoint Designer to further customize your site, it will be disconnected from the site definition. SharePoint will store the site in a database instead of using the template in hive 12 when the site is rendered. (See our SharePoint Branding for the KB Accelerator article for more information.)

When this happens, future upgrades to PM Central’s site definition will no longer be reflected in your site. During the upgrade, the application will activate some features using the references in the site definition. As explained in the Site Definition section above, the site definition file, webtemp.BambooProjectCentral.xml, contains IDs that are associated with the site template. During the upgrade, the application uses what is in the site definition to upgrade and to activate the features on the pages. However, customizations that you have made and saved using SharePoint Designer are saved in the database, not the site definition. Therefore, customizations are lost after the upgrade because the application reads the site definition and the IDs, not the database. Customizations are lost after an upgrade because they no longer exist in the site definition.

Can I upgrade an existing site when future releases of PM Central become available?

Yes, you can. Our installation will upgrade the site definition and Web Parts when a new release becomes available. For sites that are created based on the old site definition, we will provide a feature that will perform the upgrade. However, please note that the upgrade program will be based on our base template. The upgrade could fail if you make nonapproved changes to the site, such as adding a new class to the CSS file, renaming the columns in the list, renaming the master page to another master page, and referring to another CSS file with a different name, and so on.

Read the following section and be aware of any unsupported modifications made to the site. See the above section on modifying and saving a site using SharePoint Designer for information on why you may not see your customizations after an upgrade.

Don’ts When Customizing PM Central

The following is a list of items that you should not change from the base application.

Be aware of the harmful effect of using SharePoint Designer to edit the site directly. Doing so will disconnect the site from the site definition. The upgrade process will automatically activate the features. However, your original changes that you made using SharePoint Designer will be gone.

Do not change the site definition in hive 12.

Do not modify the following master pages, CSS files, and column names in these lists. The columns use aggregated data and perform business logic, and any changes will result in unpredictable behavior. You can rename the nested master page, but you cannot rename the CSS files, nested or parent, and you cannot rename the parent master page.

    • Master Pages:

      Site Type

      Name

      Top Site

      TopSite_Parent.master

      Top Site

      TopSite_Template_Parent.master

      Department Site

      DepartmentSite_Parent.master

      Department Site

      DepartmentSite_Custom_Parent.master

      Project Site

      ProjectSite_Parent.master

      Project Site

      ProjectSite_Template_Parent.master

    • CSS Files:

Site Type

Name

Top Site

TopSite_TeamSite.css

Top Site

TopSite_Template.css

Department Site

DepartmentSite_TeamSite.css

Department Site

DepartmentSite_Custom.css

Project Site

ProjectSite_TeamSite.css

Project Site

ProjectSite_Template.css

 

  • Project Health List: If you modify the following columns, you will break the List Rollup Web Part.

Column

Type

Project Name

Single line of text

Project Start Date

Date and Time

% Complete

Date and Time

Project Status

Choice

Project Manager

Person and Group

Risk Status

Bamboo KPI Column

Issue Status

Bamboo KPI Column

Schedule Status

Bamboo KPI Column

Project Department

Choice

  • Tasks List: Do not modify any of the columns in this list.
  • Issues List: Do not modify any of the columns in this list.
  • Risks List: Do not modify any of the columns in this list.
  • Pics Picture Library: Do not delete any images in this Picture Library. You can replace the images as long as the new image has the same file name as the image you are replacing. You can add new images to this Library.
  • Department Site List: Do not delete the columns in this list.
  • Monthly Resource Allocation Summary List: Do not modify any of the columns in this list.
  • Summary Cost Monthly List: Do not modify any of the columns in this list.
  • Monthly Resource Actual Cost Allocation Summary List: Do not modify any of the columns in this list.
  • Modify Pages List: Do not modify any of the columns in this list.
  • Portfolio Site Navigators List: Do not change the URL column. The code uses them from the back end to display them as tabs.
  • Project Site Navigators List: Do not change the URL column. The code uses them from the back end to display them as tabs.
  • Configuration Checklist: Do not delete prebuilt items in the list. The Configuration Checklist Web Part will show erroneous data if the default items are deleted.
  • Alert Plus Configuration List: Do not delete items or edit data in the following columns:

Column

Type

Comments

Alert List

Single line of text

Alert Event Alert List Name

Single line of text

Alert Event

Choice

E-mail Frequency

Choice

CAML Query

Multiple lines of text

Message Alert

Multiple lines of text

Recipient Type

Choice

Recipient Lookup Alert Source

Single line of text

Recipient Lookup Type

Choice

Alert List DataView Path

Single line of text

Cannot change /PageName.aspx

  • PMCentralPages Document Library: Do not rename the supplied .aspx pages in this library. Modifying this list will affect the navigation.
  • Discussion.aspx Page in the Project Site: Do not delete the JavaScript code at the bottom of this page. Doing so will break the functionalities of Link to item.
  • Help.aspx at the Portfolio Site: Do not delete the JavaScript code at the bottom of the Help page in the portfolio site.

As always, our team is committed to making PM Central the most useful and beneficial project management and collaboration tool for SharePoint available. We are open to your feedback, and we welcome your questions and comments in the PM Central forum.

Interested in PM Central R2.0? Contact us today!