Change Application Navigation Using the SiteMap
The SiteMap is a node in the customizations.xml file of an exported unmanaged solution. You can edit the navigation options available with Microsoft Dynamics CRM by using security role privileges and by editing the SiteMap. This topic describes the types of changes that you can apply by editing the SiteMap. For more information about the SiteMap, see Edit the Site Map.
In This Topic
- Application Navigation
- An overview of the application navigation capabilities controlled by using the SiteMap, including how they are implemented in the web application and the Microsoft Dynamics CRM for Microsoft Office Outlook client.
- Configuration Options Available by Using the SiteMap
- Descriptions of commonly performed customizations that you can perform by using the SiteMap, including:
The SiteMap provides the structure for navigation in Microsoft Dynamics CRM. It is evaluated together with your security privileges to display navigation options in the application. If your security privileges do not provide read access to an entity specified in the SiteMap, that navigation option will not be displayed to you. The <Privilege> (SiteMap) element can also be used to specify privilege requirements to view a page that is not related to a specific entity.
Web Application Navigation Pane
The following diagram shows the web application navigation pane, the get started pane, and the homepage grid.
Selectable areas appear at the bottom of the navigation pane. When an area is selected the contents of the area appear in the top of the navigation pane. Each area can contain visible groups and each group contains subareas. When a subarea is selected, the content defined for that subarea is displayed in the homepage grid. If content has been defined for the get started pane in a subarea, that content will be displayed until you collapse the get started pane. You can expand the get started pane at any time if you want to see the content again.
Microsoft Dynamics CRM for Outlook Navigation
The following diagram shows the Microsoft Dynamics CRM for Outlook navigation. Microsoft Outlook presents each navigation area in alphabetical order in a tree view instead of using the order specified in the SiteMap. Each person can choose to position the reading pane at the bottom as shown or on the side. They can also choose not to show it. Each entity can be configured to determine whether it will display the reading pane. For more information, see Editable Entity Properties.
Configuration Options Available by Using the SiteMap
The following sections describe common tasks that can be performed by using the SiteMap.
All of the text displayed in the default SiteMap uses a ResourceId attribute to specify the text. You should not change or remove the ResourceId attribute values. If you want to change the label displayed in an element, use the <Titles> (SiteMap) and <Title> (SiteMap) elements to specify the text you want to use for your organization or solution. Any title elements will override the ResourceId attribute values.
Add or Change Icons
You should use a GIF, PNG, or JPG image web resource as the source of your icon. When referencing the web resource, make sure that you use the web resource directive ($webresource:). For example,
Icon="$webresource:sample_/icons/MyIcon16.png" when the name of the web resource is “sample_/icons/MyIcon16.png”. Using this directive will create a dependency so that the web resource cannot be deleted as long as your SiteMap element requires it.
Add or Remove Elements
- To add elements
When editing XML elements in the SiteMap, it is very common to copy and paste existing XML elements to provide an advanced starting point. For more information, see Add new pages to an Area.
Important If you create a new element it must have a unique Id attribute value or importing your solution will fail. You should prepend an appropriate solution publisher customization prefix to the Id attribute value of any new elements that you add.
- To remove elements
Before you remove elements in the SiteMap, consider whether editing the security role privileges for users will achieve your goal. Each <SubArea> (SiteMap) element that is associated with an entity page is evaluated with the user’s privileges and only shown if user is allowed to view records for that entity.
If the subarea displays a page, such as a web resource that is not associated with a specific entity, you can add <Privilege> (SiteMap) elements to the subarea to associate that page with privileges for a specific action or access to an entity.
If none of the subarea elements in a <Group> (SiteMap) or <Area> (SiteMap) can be viewed by a user because of their security privileges, that element will not be displayed.
If you use the <SubArea> (SiteMap)AvailableOffine attribute to prevent a sub area from being displayed while the Microsoft Dynamics CRM for Outlook user is working offline, users will still be able to navigate to the subarea but they will see a message indicating that the page to display is not available offline.If you do not want to edit security roles, you can comment out the node in the SiteMap XML. Commenting out a node is better than deleting it because you can always uncomment the node if you want to restore it in the future.
Note We recommend that you use security role privileges to control access to areas of the application.
Group Links Within Areas
The Workplace and the Settings areas include multiple groups of links. You can use the <Group> (SiteMap) element in a similar manner to create groups in the other areas. A group element is required, but you must include the <Title> (SiteMap) and <Description> (SiteMap) elements for it to be displayed as a group. Finally, you must edit the <Area> (SiteMap) element to add the ShowGroups attribute and set it to true.
Add New Pages to an Area
Use <SubArea> (SiteMap) elements to add new pages to an area. If you want to include a grid for an entity, you include a unique Id, specify the entity by using the Entity attribute, and then provide a title and description by using the <Title> (SiteMap) and <Description> (SiteMap) elements.
To display a custom page in the application, you must set the Url attribute instead of the Entity attribute. The Url attribute can reference a page on an external website or an HTML web resource.
When referencing the HTML web resource, make sure that you use the web resource directive ($webresource:). For example,
Icon="$webresource:sample_/Pages/MyCustomPage.htm" when the name of the HTML web resource is “sample_/Pages/MyCustomPage.htm”. Using this directive will create a dependency so that the HTML web resource cannot be deleted as long as your SiteMap element requires it.
|To display a Silverlight web resource outside an entity form or chart, create an HTML web resource to be the host page for the Silverlight web resource. Then use the $webresource: directive to open the HTML web resource.|
When adding an external page from the SiteMap, it is a common requirement to pass data in the form of a query string to the page. To pass information about your organization name and the language for the user and organization, use the PassParams attribute. For more information, see Passing Parameters to a URL Using SiteMap.
Customize the Get Started Pane
Microsoft Dynamics CRM provides content for different areas of the application to help people get started. Any <SubArea> (SiteMap) element that uses the Entity attribute to display a grid of entity records in the homepage grid area can be configured to display content in the get started pane.
|The get started pane cannot be enabled for subarea elements that use the Url attribute to display a custom page.|
You can create HTML or Microsoft Silverlight web resources to display in the get started pane. In the downloadable files included in the Microsoft Dynamics CRM SDK, you can find files that represent a template that you can use to create HTML web resources for custom get started pane content. This template can be found in the following location in the Microsoft Dynamics CRM SDK download:
The following table lists the <SubArea> (SiteMap) element attributes that you can use to display your pages.
The path to the get started page for this subarea.
The path to the get started page for this subarea if the user is logged in as an administrator.
The path to the get started page for this subarea when Microsoft Dynamics CRM for Outlook is being used.
The path to the get started page for this subarea if the user is logged in as an administrator and Microsoft Dynamics CRM for Outlook is being used.
If only the GetStartedPanePath attribute value is specified, that page will be shown for all users and client types. Use the other attributes when you have content specifically for people who have system administrator privileges or for people who are using the Microsoft Dynamics CRM for Outlook client.
Change Workplace Profile Options
The Workplace area is unique because groups within that area can use the IsProfile attribute to make these groups available as options in your personal options. When the IsProfile attribute is set to true, people will be able to choose which of the groups in that area they want to be displayed. They can choose not to display groups that are not relevant to their work.
Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2012 Microsoft Corporation. All rights reserved.