Wednesday, August 10, 2011

Some Gotchas when Customizing the "My Content" Personal Site

Customizing an existing SharePoint 2010 site definition such as the personal site (SPSPERS) that provides the "My Content" section in the My Site Host web-application, is a bit different than customizing your own site definitions. As the supported way of customizing existing site definitions is to use feature stapling, you need to consider the provisioning order of elements in onet.xml and referenced and stapled 'SPSite' and 'SPWeb' features. Failing to do so might result in strange end results when creating a new site.

The MCS Norway team has done a good job of documenting the SharePoint element provisioning order, as part of their SiteConfigurator available at CodePlex:
"There are several steps in the creation process and SharePoint provisions in the following order:
  1. Global onet.xml This file defines list templates for hidden lists, list base types, a default definition configuration, and modules that apply globally to the deployment.
  2. SPSite scoped features defined in site definitions onet.xml, in the order they are defined in the file. The onet.xml file defined in the site definition can define navigational areas, list templates, document templates, configurations, modules, components, and server e-mail footers used in the site definition to which it corresponds.
  3. SPSite scoped stapled features, in quasi random order
  4. SPWeb scoped features defined in onet.xml, in the order they are defined in the file.
  5. SPWeb scoped stapled features, in quasi random order
  6. List instances defined in onet.xml
  7. Modules defined in onet.xml
This is a fairly complex process and it can often be hard to know the method for customizing a site definition. A solution can be right in one scenario and completely wrong in another, making this somewhat confusing."
Here are some gotchas related to SPSPERS customization:
  • The doc-libs Shared Documents and Personal Documents do not exist yet during feature stapling; list instances in onet.xml are provisioned in step 6.
  • The my content home page default.aspx do not exist yet during feature stapling; files and pages in onet.xml are provisioned in step 7.
  • Do not create your own customized default.aspx file, it will get filled with the standard web-parts when the file's AllUsersWebParts are provisioned by the onet.xml module in step 7.
  • The quick launch heading node titles are not yet localized during site provisioning, look them up by their id rather than their title when adding links
  • The standard BlogView web-part only works when in a site page in the site root, it won't work in pages stored in lists, doc-libs or custom folders.
  • The Wiki Page Home Page feature is not activated by default for personal sites; do not provision your own /SitePages/ custom list, doc-lib or folder, as this will prevent enabling wiki pages later on.
To customize the standard personal site home page, you must provision a new home page with a different name and change the site's home page setting (SPFolder rootFolder.WelcomePage). Remember to restore the standard setting when deactiving your customization feature.

I strongly recommend using or learning from the SiteConfigurator, download the feature and the source code from CodePlex and join the community there.