Microsoft Dynamics CRM 2011 for Developers | Web Resources Part 1

Contents

1. Introduction
2. Types of Web Resources
3. Where can Web Resources be Used ?
4. Web Resources Limitations
5. Web Resources Management
6. Using Web Resources on a Form
7. Using Web Resources from the Form Navigation 
8. Using Web Resources on a Dashboard
9. Using Web Resources Direct from SiteMap  
10. Using Web Resources as a Solution Configuration Page
11. Referencing Other Web Resources

Introduction

Web resources are a new feature of Dynamics CRM 2011 that allows storing of client side content in the CRM server database in order to be used for extending the Dynamics CRM web application. That content is then available to be delivered to users as needed during their interaction with the user interface. These resources can be used by URL, which also allows relative path referencing.

Based on that and using the appropriate development tools, a fully functional web site can be created on a development server by using file types that are compatible with web resources. Then, if using a consistent naming convention and relative path references, the web site will function after uploading all the files into Microsoft Dynamics CRM. These web resources can then be exported in a solution and installed on any Microsoft Dynamics CRM deployment (both on-premises and on-line). It will also available to users of Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access when offline because they are synchronized with the user’s data.

Types of Web Resources

Microsoft Dynamics CRM allows ten types to create web resources which fall into seven type categories. We will explore them here:

• HTML Web Pages You can upload *.htm or *.html files as web resources, or you can use the Text Editor in the CRM interface to create your HTML web resources. Web pages can’t contain any code that must be executed on the server (no ASP.NET support). Web pages can only accept one custom query string parameter called data.
• Images You can upload PNG, JPG, GIF, and ICO files. They can be used as icons for custom ribbon controls or Sitemape subareas, decoration for entity forms and web pages, background images.
• Script Enables uploading JScripts for reuse of many parts in the CRM like web page, ribbon commands, or form and field-level events.
• Style Sheet .css files linked to web page web resources to efficiently manage their appearance.
• Data Enables you to upload some XML files to your system
• Style Sheet enables you to upload *.xsl and *.xslt files to be used by Data and Web Page web resources, so you can apply the style on XML files.
• Silverlight enables you to upload *.xap files which is the output of Silverlight application build process. Silverlight applications can be used on forms to create a more rich and visual components for users.

Where can Web Resources be Used ?

All web resources (except XML, XSL, XSLT, CSS) can be used on forms, on dashboards, from SiteMap, or from the application ribbon. All web resources can be used in the context of Web Page web resources.

Web Resources Management

Web resources can be created in the context of any unmanaged solution inside a CRM organization.

If you will create the web resource in the default solution navigate to Settings > Customizations > Customize the System > click on Web Resources from the left navigation > New. Enter the Name, Display Name, and select the web resource type. If you will create the web resource in a default solution other than the default solution, Settings > Customizations > Solutions > and click your solution and complete in the same steps as above.

After uploading a new or updating web resource, you have to publish the web resource before you use it in the application.

You can remove an unmanaged Web Resource at any time as long as it is not currently being by any component. If you attempt to remove a web resource while it is in use by another component you will get an error message.

Web Page web resources are the container that can host (or link to) all the other web resource types, so we will explain all the ways to incorporate Web Page web resources in Dynamics CRM. Then we will explain how to link and integrate other types of web resources.

In order to proceed, we will create a simple "Hello World" page and upload it as a web resource. Create a simple page.html file like the following:

Now open your browser and navigate to your CRM organization, then navigate to Settings > Customizations > Customize the System > click on Web Resources from the left navigation > New. Enter a Name for our page, Display Name, and select Web Page (HTML) from the Type combo box. Click Save, then click Publish, then close the window.

Now we create a simple web page web resource and ready to explore the different ways to use it in our Dynamics CRM. We will explore just the basic usage scenarios, advanced features will be explained in a future post.

Using Web Resources on a Form

Now let's put use our test HTML page web resource on a Form, e.g. Account. Navigate to Settings > Customizations > Customize the System > from the left navigation expand Entities, then expand Account, then expand Forms, then click on the form named Information which have Main in the Form Type column. The form designer will open. Just to make things easier for you, collapse the regions on the form (called tabs in Dynamics CRM) by clicking the small blue rectangle on the left-top corner of each of them. Then Click on Insert in ribbon

 

Then click One Column on the ribbon.

This will insert a one column region (called Tabs in Dynamics CRM) below the currently selected region.

While your new region is selected, click Web Resource on the ribbon.

This will open the Add Web Resource dialog. In the Web Resource textbox click the look-up icon on the right and select our Web Page web resource from the list (you can also search for it by name). Fill the required Name and Label fields, and click Ok.

This will place our web page web resource on the new region we added previously to the form

Now click Save on the form designer then click Publish to publish your for customizations, then click Save and Close to close the window. Click Publish All to ensure that everything is published fine, then close the solution window. Refresh your browser and navigate to the form you have customized, it will be Account in our case and open any record to check that our HTML page web resource is published on the form correctly.

Using Web Resources from the Form Navigation

Using our web page web resource from the left navigation of a form is much more easier than using it on the form. There are two ways to do accomplish this task; one using the CRM web client interface and the other one is through editing the Entity Navigation via the FormXML directly. Now we will use the web interface and will talk about FormXML in a future post.

Use the same steps we did in the previous example to open the form designer of the entity you want to customize, for example Account. Click on Navigation in the ribbon

This will disable the form controls except the left navigation area. Click on Insert tab on the ribbon. Then click Navigation Link

This will open the Navigation Link Properties dialog. Enter Name of the link which will be the text that will appear on the left navigation, then select our web page web resource from the Web Resource textbox (you can link to external URL which will be rendered inside the form at runtime).

Now If you open any account record, you will see our link added on the left, if you click it our web page web resource will be rendered on the right.

Using Web Resources on a Dashboard

Using Web Page web resource on a CRM dashboard is pretty similar to using it on a form. The first step is to create a new dashboard by navigating to My Work > Dashboards > click New on the ribbon. This will open Select Dashboard Layout dialog, select the layout you want (for example, 3-Column Focused Dashboard), and click Create.

The dashboard designer window opens. Click on the Insert Web Resource icon on any region on the dashboard (indicated by arrows in the image)

This will open the same Add Web Resource dialog we worked with before. Do the same steps to add the web page, then gave a name to your dashboard and click Save and Close. This will close the close the designer window and open the new dashboard in your CRM main window. For example, I added the web page web resource to the left region on the dashboard and named it Test Dashboard, and below what I got.

Using Web Resources Direct From SiteMap

In order to make our web resource accessible directly from Sitemap, we have to edit the SiteMap. Unfortunately there is now way to edit the SiteMap from the Dynamics CRM web interface, you have to export the SiteMap in a temporary unmanaged solution, edit the SiteMap XML, then import the solution back again.

To create a new solution, navigate to Settings > Customizations > Solutions >  New

This will open the New Solution window, enter a Display Name, Name, Version, select a Publisher, and click Save

After you click Save, the window will change to allow you adding your solution components. Click Add Existing > SiteMap

Click on Export Solution icon

In the solution export dialog click Next > Next > ensure that the package type is Unmanaged then click Export. The Dynamics CRM server will package the solution files for you in a zip file and deliver it for you. You will see a file download message from your browser to download the zip file.

Save the zip file, extract its contents, open the customizations.xml file in Visual Studio (or your favorite XML editor). If you collapsed all the nodes in the XML Editor, you will see that the SiteMap parent node have many Area nodes. Each node represents the major parts of CRM web client navigation, which are available on the left bottom part of the window.

 

Now expand the the area node with Id=”Workplace”, which represents the Workplace in the web client. You will see Group nodes for each sub-section of Workplace area

 

Now expand the group node with Id=”MyWork”, which represents MyWork in the web client. You will see SubArea nodes for each sub-section of the MyWork area.

 

Now let’s say we want to add the link to our web page web resource just next to Dashboards under MyWork. Locate the SubArea with Id="nav_dashboards" and insert the following XML after it to make our link

This xml adds two links on the SiteMap, both of them links to our web page web resource. The first one uses the web resource direct URL which can be used to access the web resource even from external systems (vice versa, you can link other URLs directly to your CRM). To get the web resource URL, navigate to Settings > Customizations > Customize the System > click Web Resources from left navigat > double click the desired web resource to open its properties dialog, you will find the URL in the bottom of the form

The second link uses the keyword $webresource to reference the web resource by name. We will talk about $webresource keyword in the “Referencing Other Web Resources” section of this post.

Now its time to get these SiteMap modifications into CRM. Save customizations.xml, Select all the exported solution files and add them to a .Zip file, navigate to Settings > Customization > Solutions > and click Import. In the solution import dialog upload your .Zip file, and click Publish All Customizations at the end. If you navigate to your CRM home page and refreshed the page you will see the links on the left

Using Web Resources as a Solution Configuration Page

Solutions are containers that track customizations and allow it to be moved around from server to server. When building a custom solution you may want to add a page where you provide details about your solution and its features. Configuration pages for solutions can fulfill your requirement for such a page. Let’s see how we can use our web page web resource as a solution configuration page. Navigate to Settings > Customization > Solutions > click your solution > on the Solution dialog click on the Information from the left navigation

Then choose our web page web resource in the Configuration Page textbox

Then Click Save and then Click Publish. Now you will see a new link added on the left navigation after the Information link, it will be called Configuration

if you click it, you will see our web page web resource on the right.

Referencing Other Web Resources

While some web resources can be added directly to a form or a dashboard, others can only be referenced through their relative path. There are many ways you can use to reference Web Resources:

$webresource Directive You should use it when referencing a web resource from XML like from a ribbon control, or a SiteMap sub area (like what we did before). When using the $webresource directive, Microsoft Dynamics CRM will create or update solution dependencies.

Relative URL You can use relative URL when referencing from HTML or other areas that doesn’t support using $webresource. To make this works, it is recommend that you use a consistent naming convention for the web resources that reflect a virtual file structure. The solution publisher’s customization prefix will always be included as a prefix to the name of the web resource. This can represent a virtual ”root” folder for all web resources added by that publisher. You can then use the forward slash character (/) to simulate a folder structure that will be honored by the web server.

From another web resource, you should always use relative URLs to reference each other. For example, for the webpage web resource new_/content/contentpage.htm to reference the CSS web resourcenew_/Styles/styles.css, create the link as follows:

For the webpage web resource new_/content/contentpage.htm to open the webpage web resource isv_/foldername/dialogpage.htm, create the link as follows:

Dialog Page

Full URL As web resources are URL accessible, you can open the information dialog of any web resource and copy the URL in the bottom of the window and use it anywhere you can use a URL (as we did before).

In this post we introduced the web resources feature in Microsoft Dynamics CRM 2011. We started with exploring the different types of Web Resources, where can Web Resources be Used in our customization scenarios, and what is the limitations we have on using web resources. Because web Page web resources are the containers that can host (or link to) all the other web resource types, we explained all the ways to incorporate Web Page web resources in Dynamics CRM. Then we explained how to link to other types of web resources.