Write code for Microsoft Dynamics CRM 2013 forms

Article
06/01/2017

Applies To: Dynamics CRM 2013

Form programming provides ways to interact with entity forms by using JavaScript that is executed for events that occur on the form.

In This Topic

When to use form programming

Factors to Consider When You Use Form Programming

Write form scripts that perform well

Different Form Presentations

Development tools

When to use form programming

Microsoft Dynamics CRM provides many options to control business processes. Form programming is one option. With Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online, you have a new option: business rules. Business rules provide a way for someone who does not know JavaScript and is not a developer to apply business process logic in a form. More information: Create and edit business rules

The primary advantage of form programming and business rules is that they are immediate. They do not require data to be submitted to the server and, therefore, provides the best performance for many scenarios. Because they allow for human interaction, they are also the most flexible options.

While business rules have an advantage because they can be created and maintained by someone who is not a developer, they have certain limitations and are not intended to replace form scripts. Form programming allows you to achieve things that cannot yet be done using business rules.

Tasks frequently performed by using form programming include the following:

Data validation
Automation
Process enhancement and enforcement

Data Validation

Whenever possible, you should perform validation of data while the data is being edited. The definition of the Form field will perform the most common data validation for you. For example, a Single Line of Text field formatted for an email address will not allow an invalid value to be entered into it.

Use form programming for additional validation of data that is unique to your organization. For example, your organization may have specific rules about how telephone numbers should be formatted or a minimum length for the Subject field in a service activity.

Automation

You can achieve significant productivity enhancements when you use form scripting to automate common tasks. You can set field values that depend on the data that is entered into a form, that will help save users considerable time when entering data. Using form programming for automation is valuable because it lets the user verify that a standard process is valid in a particular case. Users can make necessary adjustments before saving a record.

Process Enhancement and Enforcement

You can customize the data to display or the layout of the form to optimize the form for specific tasks in your organization’s processes. You can use form programming to show or hide specific form elements, or to open different forms that have been defined for an entity. You can control which fields are required based on data present in the form or in related records.

Factors to Consider When You Use Form Programming

The logic applied in form programming can only be executed in the browser of someone interacting within the Microsoft Dynamics CRM application entity form. Because of this, you should not rely solely on form programming to initiate or enforce processes related to your data. Records can be created or updated directly through the Web service APIs or through workflows outside the context of the form. Form programming should complement business logic applied by using plugins and processes so that all records created or updated in any manner will comply with the same processes.

While form programming provides capabilities to hide form fields so that users may not be able to view or update some entity data, it does not represent a complete solution for enforcing security requirements. A user can see entity data that is not visible on the form by using a variety of methods, such as Advanced Find. More information: The security model of Microsoft Dynamics CRM 2013

Write form scripts that perform well

When you write scripts for forms, use the following practices to help achieve the best performance:

Avoid including unnecessary JavaScript web resource libraries
The more scripts you add to the form, the more time it will take to download them. Usually scripts are cached in your browser after they are loaded the first time, but the performance the first time a form is viewed often creates a significant impression.

For a specific example, don’t include jQuery in your form scripts simply because you want to use XMLHttpRequests. While jQuery has the $.ajax function that many people are familiar with to perform these requests, it is a developer preference, not a necessity. It is possible to perform these requests using the native XMLHttpRequest object found in all browsers supported by Microsoft Dynamics CRM. More information: Use of jQuery
Avoid loading all scripts in the Onload event
If you have code that only supports OnChange events for fields or the OnSave event, make sure to set the script library with the event handler for those events instead of the OnLoad event. This way loading those libraries can be deferred and increase performance when the form loads.

We do not recommend using the addOnChange method within the OnLoad event handler simply as a matter of convenience. While this may reduce the number of steps necessary to add your event handlers, it causes the form to load more slowly.
Use collapsed tabs to defer loading web resources
When web resources or IFRAMES are included in sections inside a collapsed tab, they will not be loaded if the tab is collapsed. They will be loaded when the tab is expanded. When the tab state changes, the TabStateChange event occurs. Any code that is required to support web resources or IFRAMEs within collapsed tabs can use event handlers for the TabStateChange event and reduce code that might otherwise have to occur in the OnLoad event.
Set default visibility options
Avoid using form scripts in the OnLoad event that hide form elements. Instead, set the default visibility options for form elements that might be hidden to not be visible by default when the form loads. Then, use scripts in the OnLoad event to show those form elements you want to display.

Different Form Presentations

There are several different ways that forms are presented. These affect the type of code or available events you can use for each.

Updated entities

All custom entities and certain system entities have an updated user interface that includes using the command bar and new form APIs. The updated system entities are listed in the following table:

Account	Appointment	Campaign
Campaign Activity	Campaign Response	Case
Competitor	Contact	Contract
Contract Line	Email	Fax
Invoice	Lead	Letter
Marketing List	Opportunity	Opportunity Product
Order	Phone Call	Price List Item
Product	Quick Campaign	Quote
Recurring Appointment	Sales Literature	Team
Task	User

Note

Some updated entities include composite attributes. These require some special consideration. More information: Write scripts for composite attributes.

Updated entity forms may also include a collaboration control that provides access to Notes, Activities, and Posts if they are enabled for the entity. The Xrm.Page object does not provide access to the collaboration control. You can access the section element that contains the collaboration control if you want to show or hide it by using scripts.

New form programming methods and event

The following table lists the new form programming methods available in Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online for updated entities only.

Method	Description
Xrm.Page.context.client.getClient	Returns a value to indicate which client the script is executing in.
Xrm.Page.context.client.getClientState	Returns a value to indicate the state of the client.
Xrm.Page.context.getUserName	Returns the name of the current user.
Xrm.Page.data.entity.getPrimaryAttributeValue	Gets a string for the value of the primary attribute of the entity.
Xrm.Page.data.refresh	Asynchronously refreshes the data of the form without reloading the page.
Xrm.Page.data.save	Saves the record asynchronously with the option to set callback functions to be executed after the save operation is completed.
Xrm.Page.data.entity attribute.getIsPartyList	Determines whether a lookup attribute represents a partylist lookup.
Xrm.Page.ui control.clearNotification	Removes a message already displayed for a control.
Xrm.Page.ui control.setNotification	Displays a message near the control to indicate that data is not valid.
Xrm.Page.ui.clearFormNotification	Use this method to remove form level notifications.
Xrm.Page.ui.setFormNotification	Use this method to display form level notifications.
Xrm.Page.ui control.addCustomFilter	Use fetchXml to add additional filters to the results displayed in the lookup. Each filter will be combined with any previously added filters as an ‘AND’ condition.
Xrm.Page.ui control.setShowTime	Specifies whether a date control should show the time portion of the date.
Xrm.Utility.alertDialog	Displays a non-blocking alert dialog with a callback function.
Xrm.Utility.confirmDialog	Displays a non-blocking confirm dialog with different callbacks depending on the button clicked by the user.

The new PreSearch event occurs just before the search dialog box opens when you set a lookup value. This event does not have user interface to set an event handler in the application; it can only be set using the Xrm.Page.ui control.addPreSearch method. Use this event with the addCustomFilter, addCustomView and setDefaultView methods to control the views opened when people search for a record to set as the value of a lookup field.

Entities that use classic forms

System entities that were not updated use classic form presentation. Forms for these entities continue to use the ribbon if they did in CRM 2011 and do not have access to form APIs added in this release. These entities are listed in the following table:

Address	Article	Article Comment	Bulk Delete Operation	Business Unit
Connection	Discount	Discount List	Document Location	Email Attachment
Follow	Goal	Goal Metric	Import Source File	Invoice Product
Order Product	Price List	Queue Item	Quote Product	Rollup Field
Rollup Query	Saved View	Service	Service Activity	SharePoint Site
Site	Territory	Unit	Unit Group

Entities enabled for CRM for tablets

Only selected system entities and custom entities are available to be shown by using Microsoft Dynamics CRM for tablets. The following system entities may have editable forms in CRM for tablets.

Account	Activity	Appointment	Competitor
Connection	Contact	Lead	Note
Opportunity	Opportunity Product	Phone Call	Task

Because CRM for tablets does not have the same behaviors as forms in the web application, some APIs are not available. For example, in CRM for tablets tabs cannot be expanded or collapsed, so the Tab TabStateChange Event does not occur and the Xrm.Page.ui tab. setDisplayState cannot be used to expand or collapse tabs.

Development tools

Because JavaScript is an interpreted language special development tools are not required. JavaScript is just text so it can be edited in the application or in a text editor such as Notepad. However, you can achieve significant productivity gains when you use an integrated development environment (IDE) that provides features to support editing JavaScript files, such as Microsoft Visual Studio and Microsoft Visual Studio Express.

Share via

Write code for Microsoft Dynamics CRM 2013 forms

In This Topic

When to use form programming

Data Validation

Automation

Process Enhancement and Enforcement

Factors to Consider When You Use Form Programming

Write form scripts that perform well

Different Form Presentations

Updated entities

New form programming methods and event

Entities that use classic forms

Entities enabled for CRM for tablets

Development tools

See Also

Additional resources