Share via

How to: Customize the Variations Root Landing Logic in SharePoint Server 2010 (ECM)

  • Article

Applies to: SharePoint Server 2010

When you provision a site collection in Microsoft SharePoint Server 2010 and configure variations, it does the following:

  • Creates a page in the variation home site named VariationRoot, by using the VariationRootPageLayout.aspx page layout file in the Master Page and Page Layouts Gallery.

  • Replaces the default Welcome page of the Variation home site with the VariationRoot page.

If you browse to the Variation home site, SharePoint Server 2010 looks up the WelcomePage property of the site and runs the VariationRoot page. Because that page is based on VariationRootPageLayout.aspx, it runs the page layout file. The VariationRootPageLayout page layout contains a reference to a file called VariationsRootLanding.ascx and one user control that is defined in the VariationsRootLanding.ascx file. The Page Layout executes the logic in the VariationsRootLanding.ascx file and redirects the user to a Variation site.

The default logic used in the VariationsRootLanding.ascx file is to redirect the user to the Variation site that matches the browser's accept lang, or array of language codes in which the current document is available. The VariationsRootLanding.ascx file is defined in the path \<Program Files>\Common Files\Microsoft Shared Debug\Web Server Extensions\14\Template\ControlTemplates.

If you want the default Variation root landing page logic to redirect the user to a Variation site that is not based on the accept lang, you can do this in one of three ways. Each option has its own advantages and disadvantages, and you should consider them carefully before deciding which approach to use:

  • Directly edit the VariationsRootLanding.ascx file.

    This is the quickest way to edit the logic. Edit the logic in the VariationsRootLanding.ascx file as needed, on the front-end Web server file system.

    Note

    You must update the VariationsRootLanding.ascx file on each of the front-end Web server computers. All site collections in the server farm are tied to the custom Variation root landing logic that you specify.

  • Copy the contents from the VariationsRootLanding.ascx file into the page layout in the Master Page and Page Layouts Gallery.

    For details about implementing this approach, see the first procedure, To copy the contents from the VariationsRootLanding.ascx file into the Page Layout. Like the previous approach, this approach also provides rapid customization through direct editing, with no DLL compilation and deployment issues. And, because each site collection uses its own set of page layouts, this approach also enables customization of variation root landing logic on a site-collection level. To complete this process, you must update the web.config file on each of the front-end Web server computers.

    Warning

    Use caution when setting the AllowCompilation flag on the VariationRootPageLayout.aspx file. Using inline code means that someone could inject malicious code into the page.

  • Create a precompiled assembly.

    For details about implementing this approach, see the second procedure, To create a precompiled assembly. This approach poses no security risk related to opening a Master Page and Page Layouts Gallery item for inline code execution. Like the previous approach, customization is done on a site-collection level. However, every time you need to change the variation root landing logic, you must recompile the assembly. This approach therefore offers a less rapid change-test-deploy cycle. You must deploy the assembly on all front-end Web server file system computers.

There is an additional scenario that you can use, by modifying code in the VariationsRootLanding.ascx file. If you use a scoped deployment job to deploy a Variations site, and the job does not deploy all Variation labels in the Variation hierarchy from the deployment source, users who ordinarily redirect to those labels receive a 404 error when navigating to the Variation root on the deployment destination. For example, if you have a label in the Variation hierarchy that targets a German locale, and that label is not included in your scoped deployment, browsers set to prefer German locales encounter a 404 error when navigating to the Variation root on the destination computer. The root landing logic, by default, does not check the validity of the redirect URL that it uses.

One way to address this issue is to modify the root landing logic to detect when there is a functioning Web site present at the target redirect URL. To learn how to do this, see the third procedure, To modify the root landing logic to detect when a functioning Web is present.

To copy the contents from the VariationsRootLanding.ascx file into the Page Layout

  1. Copy the code from the VariationsRootLanding.ascx file and embed it in the VariationRootPageLayout.aspx in the Master Page and Page Layouts Gallery.

  2. Make the changes that you want in the VariationRootPageLayout.aspx file.

  3. Remove the reference to the VariationsRootLanding.ascx and its user control from within VariationRootPageLayout.aspx.

  4. To allow inline code execution of VariationRootPageLayout.aspx, modify the web.config file on each Web client, as follows.

      <SharePoint>
    <SafeMode ... >
      <!-- Marks VariationRootPageLayout.aspx for ASP.NET compilation. -->
      <PageParserPath VirtualPath= "/_catalogs/masterpage/VariationRootPageLayout.aspx" 
        CompilationMode="Always"  
        AllowServerSideScript="False"
        AllowUnsafeControls="False" 
        IncludeSubFolders="True"/>
      </PageParserPaths>
    </SafeMode>
  </SharePoint>

To create a precompiled assembly

  1. Copy the code from the VariationsRootLanding.ascx file to create your own control in your own assembly DLL.

  2. Make the changes that you want in the control.

  3. Add a reference to your control to VariationRootPageLayout.aspx in the Master Page and Page Layouts Gallery.

  4. Remove the reference to VariationsRootLanding.ascx and its user control from within VariationRootPageLayout.aspx.

To modify the root landing logic to detect when a functioning Web site is present

  1. Open the VariationsRootLanding.ascx file.

  2. In the GetRedirectUrl() section, find this line of code.

    return (string.IsNullOrEmpty(matchedUrl) ? sourceLabelUrl : matchedUrl);

  3. Replace the line of code in Step 2 with the following code.

    // Customization for handling matchedUrl not valid. 
// (For example, a content deployed target site collection, 
// without source hierarchy.)
matchedUrl = (string.IsNullOrEmpty(matchedUrl) ? sourceLabelUrl : matchedUrl);                           
using (SPSite site = new SPSite(matchedUrl))
using (SPWeb web = site.OpenWeb())
     {
     // If matchedUrl is the same as the URL of the Web
     // that you just opened, then matchedUrl is valid.
     if (string.Compare(matchedUrl, web.Url, StringComparison.OrdinalIgnoreCase) == 0 && web.DoesUserHavePermissions(SPBasePermissions.Open))
       {
      //Target URL is valid; return it.
        return matchedUrl;
        }
        else
        {
      //Target URL was NOT valid; the variation label is missing.
      //Perform logic here to redirect the user appropriately.
      //If nothing is done here, then this function returns null
      //and the landing behavior reverts to the
      //VariationsRootLandingRunTime control.
      //This control displays a simple error message that
      //indicates that it could not find an appropriate subsite to 
      //redirect to.
        }
   }

See Also

Other Resources

Variations and Multiple Languages Sites in SharePoint Server 2010 (ECM)