by Travis Sharp
15. August 2011 09:22
When CRM 2011 was rolled out, so was a new method of CRM JavaScript. Now available are libraries, solutions, web resources, etc. that you can use to attain fine-grained control over all of your customizations. With the introduction of web resources you can now load any number of compartmentalized libraries into your forms that can give you that extra feature or business logic that you need.
OnLoad, OnSave, OnChange ... what is that?
(CRM 4 Customizers Can Skip This)
- OnLoad: JavaScript programmers will be used to seing something similar to this. This is the event that is triggered when your form is loaded but before any data begins to show. All form fields, aside from subgrids and iFrames, are available to you through the DOM.
- OnSave: The OnSave event is triggered when the form Save or Save & Close button is clicked.
- OnChange: The OnChange event is triggered when the field loses focus after the contents are modified. Additional methods will be explained in a future blog post as advanced events are beyond the scope of this post.
Form Customization
We will be begin by examining the form customization options on a form. It is important to note that you should use solutions rather than modifying the base system directly; however, for the sake of brevity we will save the topic of solutions for a later post. Once you have opened an entity form to customize, you will see a navigation bar at the top, aka the "Ribbon," which will aid you in all of your customizations. Currently we are only interested in form properties.
The form properties window will allow you to add additional scripts, aka "libraries," to your form. It also allows you to manage event handlers for the entire form, most notably OnLoad, OnSave and OnChange. CRM 4 Developers should take note of their new location. If we click the add button in the form libraries section, we will see all available libraries that we can add to the form and can create a new library if we wish. NOTE: Script libraries are managed in the Web Resources section of your solution.
Namespaces
- Xrm.Page - Xrm.Page is the new crmForm, or if you are just starting: Xrm.Page is the JavaScript namespace where you can access CRM form Components ( UI Elements ) and fields.
- Xrm.Page.ui - This namespace contains functions for manipulation of the form UI. This includes tabs, sections and fields.
- Xrm.Page.context - Provides access to the context object. The context object provides methods to retrieve information specific to an organization, a user, or parameters that were passed to the form in a query string. ( http://msdn.microsoft.com/en-us/library/gg328399.aspx )
- Xrm.Page.data.entity - Provides methods to retrieve information specific to the record displayed on the page, the save method and a collection of all the attributes included in the form. Attribute data is limited to attributes represented by fields on the form. ( http://msdn.microsoft.com/en-us/library/gg334720.aspx )
* Note: There are more methods, namespaces and general objects, but these are sufficient for an introduction.
* Note: Calling crmForm from the IE debugging tools no longer functions as it once did. To obtain the old functionality for debugging purposes, use:
crmForm = window.frames[0].crmForm;
Xrm = window.frames[0].Xrm;
It is also important to note that when developing for CRM 2011, you should use the "Xrm" methods rather than the older crmForm methods in your javascript.
Xrm.Page ( formerly crmForm )
Xrm.Page is the new crmForm, or if you are just starting: Xrm.Page is the JavaScript namespace where you can access CRM form Components ( UI Elements ) and fields. Almost everything that you need to do to the CRM form you can get to through here. Of note, crmForm still does exist and can be used within scripts.
| Xrm.Page.getAttribute("new_field"); |
This function returns an attribute on the form using the lowercase schema name. The object that it returns can be used to update the field data, fire onChange, tell if it is dirty, add additional CRM appropriate events, etc. |
| Xrm.Page.getControl("new_field"); |
This retrieves a control of a field, which can be used to change visibility, enable or disable the field, get the type, etc. |
Xrm.Page.ui
| Xrm.Page.ui.getFormType(); |
This returns a numeric value for the type of form that is currently being displayed, i.e.: update, create, etc. (The exact numbers corresponding to each type are not covered in this post.) |
| Xrm.Page.ui.getViewPortWidth(); |
Returns how many pixels wide the view is. |
| Xrm.Page.ui.getViewPortHeight(); |
Returns how many pixels high the view is. |
| Xrm.Page.ui.getCurrentControl(); |
Returns the current active control. |
| Xrm.Page.ui.controls.get("new_field"); |
Works just like Xrm.Page.getControl() except the Xrm.Page.ui.controls namespace has a few more functions for dealing with controls. |
| Xrm.Page.ui.tabs.get("tabName"); |
This works like getControl except that it is for tabs. It will return a tab object that you can use to change the properties of the tab, the most useful of which include the visibility and the sections object. |
Xrm.Page.context
| Xrm.Page.context.getUserId(); |
This will return the GUID of the current user |
| Xrm.Page.context.getUserRoles(); |
Returns the current user's role/roles. |
| Xrm.Page.context.isOutlookClient(); |
Returns whether or not a user is in the Outlook client. If you need to use a different version of a javascript function or Outlook does not support a particular feature, you can use this. |
| Xrm.Page.context.isOutlookOnline(); |
For the times when you need to determine if the outlook client is online, use this. e.g.: If you have an oData call to retrieve certain data from somewhere else in the system or you have mapping code that depends on an external web service, use this to determine if you're online. |
| Xrm.Page.context.getOrgUniqueName(); |
Returns the unique org name for the current active organization. This is helpful for On-Premise installations that have multiple organizations or online instances. |
| Xrm.Page.context.getServerUrl(); |
Returns the url of the server. |
| Xrm.Page.context.getAuthenticationHeader(); |
Returns the authentication header required to make SOAP calls. |
Xrm.Page.data.entity
| Xrm.Page.data.entity.getId(); |
Returns the current entity's GUID |
| Xrm.Page.data.entity.getEntityName(); |
Returns the current entities schema/logical name. |
| Xrm.Page.data.entity.save(); |
Forces a manual save of the entity. - Note: this function can also take an "Action" |
| Xrm.Page.data.entity.getIsDirty(); |
Determines whether or not the form is dirty, i.e. if there are any unsaved changes. |
Subscribe