At a recent event on Microsoft’s campus, I had the opportunity to speak with several MVPs about their experiences with the new solutions framework in Microsoft Dynamics CRM 2011. They were excited by the possibilities of solutions but had questions about some of the patterns and practices they should employ. I want to share with you one of the patterns that my team has been using, with the hope that you can benefit from it and share your experiences, improvements, and thoughts with me as well.
This pattern covers configuration data, primarily global settings and sitemap URLs. This is not the only approach, and it won’t always be the right approach for your solution. It’s pretty easy to use, though, and so you should consider it a tool in your toolbox.
Let’s assume we’re building a solution which has some customizable components inside CRM and also has a “Search” link in the Sitemap. So we might want to store the following data:
- Size to display the CRM component: small, medium, or large
- Color of the CRM component: red, green, blue, or yellow
- URL for the Search link: e.g. http://bing.com
By default, we would use “medium”, “green”, and Bing as the search engine. It’s a little-known fact that there are other search engines out there, and some customer might want to use one of these instead. But we wouldn’t want to force them to edit their Sitemap just to change a URL. Similarly, we wouldn’t want people to have to spelunk through a lot of code just to change the look of our solution (since we intend it to be customizable). So how can we centralize these settings and make them relatively easy to change?
Our approach will be to create a settings file which is Javascript code. The code will look like this:
var MYCOOLSOLUTION_SETTINGS_LOADED = true;var Settings = {ComponentSize : 'medium', // allowed values are 'small', 'medium', and 'large'Color : 'green', // allowed values are 'green', 'red', 'blue', and 'yellow'SearchLink : 'http://www.bing.com'};
Save this code as a Web resource called “new_settings.js” (of course, your prefix might be something other than “new_” – if you don’t understand how prefixes work, check out this KB article on the topic).
If a form script needs to use the values, it’s super easy: just make sure new_settings.js is loaded for that form as well, prior to your other form scripts. In case you need a refresher: customize the form, click Form Properties, add new_settings.js and your form script to the Form Libraries section.
In any standalone Javascript file (such as one loaded by an HTML Web resource) which needs these values, you must include a snippet like the following:
// include settings if it's not already includedif(typeof(MYCOOLSOLUTION_SETTINGS_LOADED) == 'undefined') {var s = document.createElement("script");s.type = "text/javascript";s.src = "new_settings.js";document.getElementsByTagName("head")[0].appendChild(s);}
You only need to do this once per Javascript file, preferably at the top. (Be sure you understand exactly when the code will execute – it’s pretty easy to think you’re loading a file at a different time than the browser actually executes it.) Of course, you’ll want to make sure s.src actually equals the relative path to the settings file. Now you’ll be able to reference Settings.ComponentSize, Settings.Color, and Settings.SearchLink to get to the appropriate configuration settings.
At this point you’re probably thinking something like, “OK, this makes sense for forms and Web resources, but you promised me Sitemap customization capabilities as well.” I will now deliver on that promise. Basically, instead of hardcoding a URL into the Sitemap, we’ll hardcode a link to a Sitemap shim under our control. The shim will load the settings file and then redirect the user to the actual target site.
The code for the shim, which is an HTML Web resource, looks like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>redirecting...</title><script type="text/javascript" src="new_settings.js"></script></head><body><script type="text/javascript">window.location = Settings.SearchLink;</script></body></html>
Save this as a Web resource called “new_search.html”, and then create a navigation link in the Sitemap with the text “Search the Web” and “$webresource:new_search.html” as the link. If you don’t know how to edit the Sitemap, you can read the SDK documentation on the topic. Now, whenever a user clicks on our “Search the Web” link in the sitemap, they’ll be taken to whatever URL is specified in Settings.SearchLink.
There are a few downsides to this approach that you should be aware of before implementing it:
- Changing the settings requires editing the new_settings.js file in your solution. Therefore, you must set its managed properties in such a way that the system customizer can edit it.
- Since new_settings.js is regular ol’ executable Javascript, a system customizer could break your solution pretty easily, whether maliciously or simply by accidentally leaving out a comma or semicolon.
- Only clients which can execute Javascript will perform properly. Web and Outlook clients should always work. Mobile Express, third-party mobile apps, and Silverlight will require a different approach.
I hope this post has shown you an easy way to centralize your global settings and sitemap URLs, while cautioning about the limitations and dangers.
Cheers,