The customization best practices have been updated to reflect changes in PM Central R2.0. Read this blog post for the updated customization best practices.

The PM Central team's adrenaline is still pumping on the heels of PM Central's release on SharePoint 2010. We're excited that PM Central leverages the great capabilities of out-of-the-box SharePoint 2010 and that it is compatible with Microsoft Project 2010. PM Central on SharePoint 2010 offers the same excellent features as PM Central on SharePoint 2007, including the ability to customize your portfolio and project sites to make managing your projects, tasks and resources as simple as possible.

With that in mind, we have updated our customization best practices to include the most current information, expanded explanations and screen shots so that you can customize PM Central to your organization's needs and start managing your projects as quickly as possible.

We are on a mission to make PM Central your go-to project management information system (PMIS). We welcome your feedback in the comments below.

Because the best practices cover a range of topics, the content is 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
• 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 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
• lists

Site Definitions

PM Central's site definition file is located under Program FilesCommon FilesMicrosoft SharedWeb Server Extensions12TEMPLATE1033XML as webtemp.BambooProjectCentral.xml.

The 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 and project sites. The SA12Top.master and the SA12.master files use the regular SharePoint theme. The SA12Top_Template.master and the SA12x.master files are for the custom template.

Site Type	Master Page	CSS
Top Site	SA12Top.master SA12Top_Template.master	TopSite_TeamSite.css TopSite_Template.css
Project Site	SA12.master SA12x.master	ProjectSite_TeamSite.css ProjectSite_Template.css

The custom master page SA12Top_Template.master is for the custom portfolio site. It references the TopSite_Template.css. This design presents the banner, the font and the color that you see when you browse 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.

• Alert Plus: Sets up custom alerts
• Bamboo KPI Column: Displays indicators for the schedule, risks, issues, etc.
• Bamboo Visual Indicator: Displays the percent complete as a progress bar
• Calendar Plus Web Part: Displays various calendar events and color coding
• Chart Plus Web Part: Displays various charts
• Data-Viewer Web Part: Displays Data in a grid view with the ability to filter and sort
• Group Email Web Part: Sends team notifications on any topic
• List Print: Prints the lists using specified templates
• List Rollup Web Part: Aggregates data from multiple lists and multiple sites
• List Simple and Advanced Search Web Parts: Search through the columns of a list
• SharePoint Navigators: Displays custom tabs and menus
• SharePoint Project Portfolio Dashboard: Displays the Gantt view for the project schedules at the portfolio site
• SharePoint Task Master: Tracks tasks and schedules
• Site Creation Plus: Creates new project sites using a standard template
• Tree View Web Part: Organizes documents in a tree view with expand and collapse options

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 R1.8 and older 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.
• New Web Parts and tabs are added using code.
• The features are activated.

In PM Central R1.8 or older, you will lose some of your customizations after you upgrade. However, in the next major release, we will ensure that your customizations are retained after an upgrade.

Customizing the Master Page

To check which pages use the master page, open the site using Microsoft SharePoint Designer. Open the page you want to check. Make sure 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 by 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 by including the CSS file in <head runat="server"> </head>

Changing Images at the Portfolio or Project Sites

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

First, rename your image to the PM Central image you want to replace, for example: logoSA12.png. Then navigate to Site Actions > View All Site Content. Under Picture Libraries, select Pics.

Upload your image to the Pics folder. Your new image should display automatically.

Changing the Style Sheet for the Portfolio or Project Sites

All CSS files are stored under _catalogsmasterpage.

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

• If the site was created by Bamboo PM Central Top-Level Site, choose TopSite_TeamSite.css.
• If the site was created by Bamboo PM Central Top-Level Site – Custom Template, choose TopSite_Template.css.
• If the site was created by Bamboo PM Project Site or Bamboo PM Project Site – NO SEED DATA, choose ProjectSite_TeamSite.css.
• If the site was created by Bamboo PM Project Site – Custom Template or Bamboo PM Project Site – Custom Template – NO SEED DATA, choose ProjectSite_Template.css.

  

What Customizations Are Possible?

Now that you have a better understanding of how PM Central's pages are created, you can figure out what customizations can be applied to PM Central R1.8 or older and what will happen to your customizations after an upgrade.

In general, you can modify your portfolio or project sites using the recommended guidelines on how to customize any SharePoint site. Most modifications using the standard browser interface are acceptable. However, in PM Central R1.8 or older, you will lose some of your customizations after you upgrade. In the next major release of PM Central, we will ensure that your customizations are retained after an upgrade.

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

	Description	PM Central R1.8 or Older	After Upgrade
1	Add new Web Parts to the pages	Yes, it is OK.	No, it is not OK. In R1.8 and older versions, after the upgrade you need to re-add the Web Part because during the upgrade, the application will back up your existing site and create a new site. Based on the site definition, the application references the new build's master page and ASPX page and has no knowledge of the Web Parts that you added.
2	Add additional columns and views to existing Lists Add new Lists (e.g., project tasks list, status reports, custom list, etc.) and Document Libraries (Wiki, Collaboration, translation, Shared Documents folders, etc.)	Yes, it is OK.	Yes, it is OK. In R1.8 and older versions, the columns will still be there as well as the view. However, during the upgrade the application will back up and replace the pages with new pages as well as the settings for the Web Parts. Therefore, you will have to modify the Web Parts to add the custom columns to the views again. Follow the KB on adding columns to views in lists.
3	Change the look and feel of themes and graphics	Yes, it is OK.	No, it is not OK. In R1.8 and older versions, if you replace the original image with your own image and keep the same name, after the upgrade, your logo will still be there. Please follow the KB on modifying the logo and graphics. In R1.8 and older versions, if you modify the CSS to display a different color or theme, this modification will be gone after the upgrade. This is because during the upgrade, the application will back up your old master pages and CSS files and replace with the new files from the new build.
4	Add new navigation tabs on portfolio and project sites	Yes, it is OK.	Yes, it is OK. After the upgrade, the application will retain the navigators list.
5	Create new pages from a Web Part page in SharePoint	Yes, it is OK.	Yes, it is OK with on the condition that new pages should be stored under the PMCentraPages list in the Document Libraries.
6	Modify the master page and CSS files without using SharePoint Designer	Yes, it is OK.	No, it is not OK. In R1.8 and older versions, during the upgrade the application will back up and replace the master page and the CSS files with the ones from the new build.
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. Add additional columns: OK after upgrade. You will need to recreate the data source and re-do the settings in the tool pane of the Web Parts. Please follow the KB on creating new data sources. Change the logos: OK if you use the same file name. Follow the KB on modifying the logo and graphics.

Frequently Asked Questions (FAQs)

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

Yes, for PM Central R1.8 or older.

However, after you upgrade to PM Central R1.8 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 R1.8 or older.

After you upgrade to PM Central R1.8 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 R1.8 or older.

After you upgrade to PM Central R1.8 or older versions, you will lose this customization because during the upgrade, the application replaces the pages with the pages from the new build and references the CSS files from the new build.

For example:

In the ProjectSite_Template.css, PM Central has this class:

You can modify the class .ms-globalbreadcrumb and add a new class.

After the upgrade, the change to the .ms-globalbreadcrumb class and the newly added class will be gone because the application goes back to the original class.

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

After you upgrade to PM Central R1.8 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 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 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, referring 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 column names in these lists. The columns use aggregated data and perform business logic, and any changes will result in unpredictable behavior.

• Master Pages: Do not delete the JavaScript code at the bottom of the master page.
• CSS Files: Do not change the supplied CSS file name. The templates will not work if the CSS file names are changed. You can modify the CSS tags, but this will change the look of the site. Your changes to the CSS tags will be gone after the upgrade because the upgrade will back up your CSS files and replace them with the CSS files from the new build.
• Project Health List: If you modify the following columns, you will break the List Rollup Web Part.

• Tasks List: Modifying any of the columns in this list will break the Data-Viewer and List Rollup Web Parts at the portfolio site.
• Issues List: Modifying any of the columns in this list will break the Data-Viewer Web Part at the portfolio site.
• Risks List: Modifying any of the columns in this list will break the Data-Viewer Web Part at the portfolio site.
• Pics Picture Library: Do not delete or rename 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.
• Portfolio Site Images

• Project Site Images

• 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:

• PMCentralPages Document Library: Do not rename the supplied .aspx pages in this library. Modifying this list will affect the navigation tabs and will create unpredictable behavior for the Bamboo Chart Plus Web Part and the Bamboo Data-Viewer Web Part.
• 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.