Export (0) Print
Expand All

Adding a Context-Sensitive Topic for Custom Entities

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

When you create a custom entity, a new Microsoft Dynamics CRM list page and form are created for the entity. By default, all custom list pages are hooked up to the Help topic "Custom Entity List" and all custom forms are hooked up to the Help topic "Custom Entity Form."  By default these pages include information about common tasks that apply across a number of record types.

There are two approaches you can use to provide custom help content, listed below in order of complexity.

  1. Add your content to the pages provided
  2. Integrate custom help pages to the help application.

Add your content to the pages provided

Simply modifying the default Custom Entity List (ui_cust_customlist.htm) and Custom Entity Form (ui_cust_customform.htm) files may be sufficient for your needs. You may wish to include links to other custom html files that provide details for specific entities.

You should be sure to keep a backup of your modified files and be prepared to replace them if you upgrade Microsoft Dynamics CRM or apply a hot fix that updates the help content. An upgrade or hot fix may overwrite the existing files.

This is a very simple direct approach – but it is inconsistent with the way help works for other entities and may be confusing to users.

Integrate custom help pages to the help application.

To truly provide an entity specific context sensitive topic for custom entities, you can integrate custom pages for each entity into the help application by registering them with help_toc.xml.

The last volume element in help_toc.xml is used to relate specific help pages to specific Microsoft Dynamics CRM application pages. This volume has the hidden="true" attribute so it is not displayed in the table of contents. You can add new page elements to set custom help pages for custom entities for list and form pages.

Before you can begin, you must know the entity type code for the custom entity. Entity type codes begin with 10000 and are incremented by one for each new custom entity. Entity type codes are unique for each Microsoft Dynamics CRM implementation.

You can retrieve the type codes for all entities by using the RetrieveAllEntities message.

If you have an on-premise deployment, you can use the Metadata Browser to view the entities and their type codes for your organization. See Using the Metadata BrowserV4d0_SP2810c_MetadataBrowser.

To create a custom help page for a custom entity list page

After you know the entity type code for the custom entity, do the following:

  1. Create an .htm page in the help\<language code>\OP\content folder.
    • You may want to use the existing ui_cust_customlist.htm page as a starting point but save it with a different name.
    • Use a consistent naming convention to separate the page from others, for example aw_new_thing_list.htm.
  2. Open the help_toc.xml file (in the help\<language code>\OP folder) with the text editor of your choice, such as Notepad.
  3. Locate the following page element:
    <page procedure="true" topic="ui_cust_customlist" filename="custom_entity_list">Custom List</page>
    
  4. Copy the element and paste it in the same chapter.
  5. Modify the page element to:
    • Set the topic equal to the new file name without the .htm extension
    • Set the Filename equal to the page that displays the list. The format for this page is: /_root/homepage.aspx?etc=<entity type code>.

The result should look like this when your custom page is aw_new_thing_list.htm and the entity type code is 10001

<page procedure="true" topic="aw_new_thing_list" filename="/_root/homepage.aspx?etc=10001">Custom Thing List</page>
  1. Save help_toc.xml.
  2. Confirm that the custom page displays by opening the list view for the custom entity and clicking Help > help on this page.

Note   If you get a "The Page cannot be found error", make sure the topic attribute is typed correctly and does not include the '.htm' file extension.

To create a custom help page for a custom entity form page

The process to launch a custom help page for a custom entity form requires some additional steps. The help application will always attempt to launch the page defined in help_toc.xml for the filename="/userdefined/edit.aspx". By default this is the ui_cust_customForm.htm page.

To launch a custom page, you must perform two steps:

  • Configure the new form page in help_toc.xml
  • Add and configure a script element in ui_cust_customForm.htm to redirect the help application to the custom page.

Configure the new form page in help_toc.xml

After you know the entity type code for the custom entity, do the following:

  1. Create an .htm page in the help\<language code>\OP\content folder.
    • You may want to use the existing ui_cust_customForm.htm page as a starting point but save it with a different name.
    • Use a consistent naming convention to separate the page from others, for example aw_new_thing_form.htm.
  2. Open the help_toc.xml file (in the help\<language code>\OP folder) with the text editor of your choice, such as Notepad.
  3. Locate the following page element: ( It is below the comment "CUSTOMIZATION: TOPICS FOR CUSTOMIZED ENTITIES" )
    <page procedure="true" topic="ui_cust_customform" filename="custom_entity_list">Custom Form</page>
    
  4. Copy the element and paste it in the same chapter.
  5. Modify the page element to:
    • Set the topic attribute value equal to the new file name without the .htm extension
    • Set the filename attribute value equal to the page that displays the list. The format for this page is: "/userdefined/edit.aspx?etc=<entity type code>".

The result should look like this when your custom page is aw_new_thing_list.htm and the entity type code is 10001

<page procedure="true" topic="aw_new_thing_form" filename=" /userdefined/edit.aspx?etc=10001">Custom Thing Form</page>
  1. Save help_toc.xml.

Add and configure the script element in the ui_cust_CustomForm.htm page

  1. In ui_cust_CustomForm.htm, add the following script element at the top of the <head> element:
    <script>
     var pathname = document.location.pathname;
     var helpDirIndex = pathname.indexOf("help/")+ 5;
     var LCID = pathname.substring(helpDirIndex,helpDirIndex+4); 
     var helpURL = top.opener.location.href;
     var etcLocation = helpURL.indexOf("etc=")+4;
     var strEtc = helpURL.substring(etcLocation,etcLocation+5);
     var firstParams = "?area=/userdefined/edit.aspx?etc=";
     var secondParams = "&user_lcid="+LCID;
     switch (strEtc)
      {
       //add any custom entity references here
      }
    </script> 
    
  2. In the section of the script that says "add any custom entity references here", add the following lines including the entity type code for each custom entity that you have configured in help_toc.xml.
    case "[add entity type code here]":
       top.location = top.location.pathname + firstParams +"[add entity type code here]"+secondParams;
       break;
    

    For example, if you have configured help files for the two custom entities represented by entity type codes 10000 and 10001:

    case "10000":
       top.location = top.location.pathname + firstParams +"10000"+secondParams;
       break;
    case "10001":
       top.location = top.location.pathname + firstParams +"10001"+secondParams;
       break;
    
  3. Save ui_cust_CustomForm.htm
  4. Confirm the custom page displays by opening the form for the custom entity and clicking Help > help on this page.

Related Topics


© 2010 Microsoft Corporation. All rights reserved.


Show:
© 2014 Microsoft