Form Scripting Quick Reference
This topic presents a quick reference of frequently used form scripting methods based on tasks you perform with them. For the full reference, see Xrm.Page Reference. All examples on this page use the default account entity main form unless otherwise specified.
In This Topic
-
Accessing Form Controls
-
Use Form Controls
-
Use OptionSet Controls
-
Use IFRAME and Web Resource Controls
-
Use Lookup Controls
-
Use the SubGrid Control
Using Attributes
Attributes store the data available in the record.
Accessing Attributes
Attributes are available from the Xrm.Page.data.entity.attributes Collection. To access an attribute you can use the Xrm.Page.data.entity.attributes.get method or the shortcut version Xrm.Page.getAttribute. The get method accepts four types of arguments:
-
String: Returns an attribute object where the attribute name matches the string.
-
Number: Returns the attribute object where the Xrm.Page.data.entity.attributes collection index matches the number.
-
None: Returns an array of all the attributes.
-
Delegate function(attribute,index): Returns an array of any attributes from the Xrm.Page.data.entity.attributes collection that cause the delegate function to return true.
| Task | Example |
|---|---|
|
Access an attribute by name |
Assigns the attribute for the Account Name field to the nameAttribute variable |
|
Access an attribute by index |
Assigns the first attribute in the Xrm.Page.data.entity.attributes collection to the firstAttribute variable. |
|
Access all attributes |
Assigns an array of all the attributes in the Xrm.Page.data.entity.attributes collection to the allAttributes variable. |
|
Access all attributes that meet a specific criteria |
Assigns an array of all the attributes in the Xrm.Page.data.entity.attributes collection that meet the criteria set in the anonymous function, which returns true when the attribute type is “optionset” to the optionsetAttributes variable. |
The Xrm.Page.data.entity.attributes collection also has a forEach method that you can use to access attributes within a function. The following example displays an alert for each attribute that must contain data in a form: Xrm.Page.data.entity.attributes.forEach(function (attribute, index) { if (attribute.getRequiredLevel() == "required") { alert(attribute.getName()); } });
Use Entity Attribute Data
The examples in the following table show how you can retrieve or change data stored in attributes.
| Task | Method | Example |
|---|---|---|
|
Get the value of an attribute |
Assigns the value of the Account Name field to the nameValue variable. |
|
|
Set the value of an attribute |
Sets the value of the Account Name field to “new name”. |
|
|
Get the text value of the currently selected option of an optionset attribute |
Assigns the text of the selected option in the Address Type field to the addressType variable. |
|
|
Get the currently selected option object in an optionset attribute |
Assigns the selected option in the Address Type field to the addressTypeOption variable. |
Use Attribute Metadata
The examples in the following table show how you can query attribute properties to understand what kind of attribute it is or change the behavior of the attribute.
| Task | Method | Example |
|---|---|---|
|
Get the type of attribute |
Assigns the string value that represents the type of attribute for the first attribute to the attributeType variable. |
|
|
Get how the attribute is formatted |
Assigns the string value that represents the format of the first attribute to the attributeFormat variable. |
|
|
Get the initial value of a Boolean or optionset attribute |
Assigns the initial number value of the Address Type field to the attributeInitialValue variable. |
|
|
Determine whether an attribute value has changed |
Assigns a Boolean value that indicates whether the Account Name field value has changed to the isNameChanged variable. |
|
|
Get the maximum allowed value for an attribute that contains a number |
Assigns a Boolean value that indicates whether the value of the newValue variable exceeds the maximum value allowed for the Credit Limit field to the newValueBelowMax variable. |
|
|
Get the maximum allowed length for an attribute that contains a string |
Assigns a Boolean value that indicates whether the value of the newAccountName variable exceeds the maximum length allowed for the Account Name field to the nameTooLong variable. |
|
|
Get the minimum allowed value for an attribute that contains a number |
Assigns a Boolean value that indicates whether the value of the newValue variable is below the minimum value allowed for the Credit Limit field to the newValueBelowMin variable. |
|
|
Gets the logical name of an attribute |
Assigns the logical name value of the first attribute on the page to the attributeName variable |
|
|
Get the option object representing a value |
Shows an alert that displays the text of the Address Type field option with a value of 1. |
|
|
Get a number value representing the level of precision for the number attribute |
Assigns the precision value of the Credit Limit field to the creditLimitPrecision variable. |
|
|
Get a string value representing whether the an attribute is required to have a value |
The creditLimitRequired variable value may be none, required, or recommended. |
|
|
Change whether data is required in a field in order to save a record |
Makes the Credit Limit field required. |
|
|
Determine whether the data in an attribute will be submitted when the record is saved |
The nameSubmitMode variable value will be either always, never, or dirty to represent the submitMode for the Account Name field.. |
|
|
Control whether data in an attribute will be saved when the record is saved |
The example will force the Account Name field value to always be saved even when it has not changed. |
|
|
When field level security has been applied to an attribute, |
Assigns a Boolean value that represents the user’s privilege to update the Account Name field to the canUpdateNameAttribute variable. |
Using Save Event Arguments
When enforcing business logic it is frequently necessary to prevent a record from being saved so that the user can include required information. To do this you must configure the event handler to pass in the execution context. The execution context contains the getEventArgs method to retrieve arguments for the event. These arguments include methods you can use to control whether a record will be saved or query properties that tell you about the save event.
| Task | Example |
|---|---|
|
Prevent a record from being saved. |
Use the eContext parameter to capture the execution context and use the preventDefault method included with the event arguments. |
|
Determine what action initiated the save. |
Use the eContext parameter to capture the execution context and use the getSaveMode method included with the event arguments to convert the integer code value into text. |
Using Controls
Controls represent the user interface elements in the form. Each attribute in the form will have at least one control associated with it. Not every control is associated with an attribute. IFRAME, web resource, and subgrids are controls that do not have attributes.
Accessing Form Controls
Controls are available from the Xrm.Page.ui.controls Collection. To access a control you can use the Xrm.Page.ui.controls.get method or the shortcut version Xrm.Page.getControl.
The get method accepts four types of arguments:
-
String: Returns a control where the logical name matches the string.
-
Number: Returns the control where the Xrm.Page.ui.controls collection index matches the number.
-
None: Returns an array of all the controls.
-
Delegate function(control,index): Returns an array of any controls from the Xrm.Page.ui.controls collection that cause the delegate function to return true.
| Task | Example |
|---|---|
|
Access all the controls for a specific attribute |
Assigns an array of all the controls for the name attribute to the nameControls variable. |
|
Access a control by name |
Assigns the first control representing the Account Name field to the nameControl variable. The first control added to a form for an attribute will have the same name as the attribute. Each additional control name will have an index number appended to the name. For example, three controls for the name attribute will have the names: name, name1, and name2 respectively. |
|
Access a control by index |
Assigns the first control in the Xrm.Page.ui.controls collection to the firstControl variable. |
|
Access all controls |
Assigns an array of all the controls in the Xrm.Page.ui.controls collection to the allControls variable. |
|
Access all controls that meet a specific criteria |
Assigns an array of all the attributes in the Xrm.Page.ui.controls collection that meet the criteria set in the anonymous function which returns true when the control type is “optionset” to the optionsetControls variable to. |
Each section also has a controls collection that contains just the controls for that section. The following code sample assigns the generalTabAccountInfoSectionControls variable to an array of controls found in the Address section of the General tab. var generalTabAccountInfoSectionControls = Xrm.Page.ui.tabs.get("general").sections.get("address").controls.get();
Use Form Controls
After you have access to a control you can call the following methods.
| Task | Method | Example | ||
|---|---|---|---|---|
|
Determine if a control is visible |
Assigns a Boolean value to the isNameVisible variable that represents whether the Account Name field is visible. |
|||
|
Hide or show a control |
Hides the Account Name field. |
|||
|
Get a reference to the attribute for the control |
Assigns the attribute for the control for the Account Name field to the nameAttribute variable.
|
|||
|
Determine the type of the control |
Assigns an array of optionset controls to the optionSetControls variable. |
|||
|
Determine if a control is enabled |
Assigns an array of disabled controls to the disabledControls variable.
|
|||
|
Disable or enable a control |
Disable each control for the name attribute.
|
|||
|
Get the label for a control |
Assigns the value of the control for the Account Name field to the nameControlLabel variable. |
|||
|
Change the label for a control |
Changes the label for the Account Name field to Company Name. |
|||
|
Get the name of a control |
Assigns the name of the first control in the Xrm.Page.ui.controls collection to the firstControlName variable. |
|||
|
Get the parent of a control |
Assigns the parent section of the control for the Account Name field to the parentSection variable. |
|||
|
Set focus on a control |
Sets focus on the Account Name field. |
Use OptionSet Controls
Optionsets have some special methods. It is important to remember that the attribute defines the valid options for an optionset. When you work with an optionset control you can manipulate available options but you cannot create new options.
| Task | Method | Example |
|---|---|---|
|
Add an option to an optionset control |
Using a reference to the control for the Address Type field, access the attribute for the control and use the getOption method to set the billToAddressOption variable to the option representing the Bill To option. Use clearOptions to remove any existing options and use addOption to set billToAddressOption as the only option available for this control. |
|
|
Remove all the options from an optionset control |
Remove all the options from the control for the Address Type field. |
|
|
Remove a single option from an optionset control. |
Remove the Bill To option from the control for the Address Type field. |
Use IFRAME and Web Resource Controls
An IFRAME control allows you to include a page within a form by providing a URL. An HTML web resource added to a form is presented using an IFRAME element. Silverlight and image web resources are embedded directly within the page.
| Task | Method | Example |
|---|---|---|
|
Get the value of the data query string parameter passed to a Silverlight web resource. |
Assigns the value passed through the data query string parameter to the dataValue variable. |
|
|
Get the URL for the content currently displayed in an IFRAME. |
Assigns the string representing the current IFRAME.src attribute value to the iframeSource variable. |
|
|
Set the URL for the content to be displayed in an IFRAME. |
Sets a URL to be the IFRAME.src for the control. |
|
|
Get the URL that represents the default configured URL for an IFRAME. |
Assigns the initial URL configured to be displayed in the IFRAME to the initialUrl variable. |
|
|
Gets the object in the form that represents the web resource or IFRAME. |
Assigns an object reference to the obj variable. For an IFRAME this will be the IFRAME Document Object Model (DOM) element. For a Silverlight web resource it will be the Object Object element that represents the embedded Silverlight plug-in. |
Use Lookup Controls
A common requirement for lookup controls is to specify the default view displayed when a user updates the field.
| Task | Method | Example |
|---|---|---|
|
Add a custom view for a lookup. |
Sets the viewId, viewDisplayName, fetchXml, and layoutXml variables to pass as arguments so that a custom view is added as the default view to the control for the Parent Account lookup field. |
|
|
Get the default view for a lookup. |
Assign the id value of the default view to the defaultViewId variable. |
|
|
Set the default view for a lookup. |
Sets the default view for the control for the Parent Account field to the id value in the viewId variable. |
Use the SubGrid Control
The SubGrid control is a grid within a form. It has one unique method.
| Task | Method | Example |
|---|---|---|
|
Refresh the data displayed in the subgrid |
Refresh the Contactssubgrid. |
Use Form Navigation
You can use and manipulate the navigation items on the left side of the form. These navigation items typically show records related to the record displayed in the form.
You can access navigation items using the Xrm.Page.ui.navigation.items Collection Like all collections in the form, there is a get and forEach method.
| Task | Method | Example |
|---|---|---|
|
Get the name of a navigation item |
Create a navItemIds array that contains the id values of each navigation item in the Xrm.Page.ui.navigation.items collection. |
|
|
Get the label of a navigation item. |
Assign the label for the More Addresses navigation item to the navAddressesLabel variable. |
|
|
Set the label of a navigation item |
Change the More Addresses navigation item label to Other Addresses. |
|
|
Show or hide a navigation item |
Hide the More Addresses navigation item. |
|
|
Determine if a navigation item is visible |
Assign a Boolean value to the moreAddressesVisible variable to represent whether the More Addresses navigation item is visible. |
|
|
Set focus on a navigation item. |
Set focus on the More Addresses navigation item. |
Use Tabs and Sections
Each form has collection of tabs. Each Tab has a collection of sections. Each section has a collection of controls. You can programmatically access these elements and use their methods.
| Task | Method | Example |
|---|---|---|
|
Determine if a tab is expanded or collapsed |
Assign a Boolean value to the isGeneralTabExpanded variable that indicates whether the General tab is expanded. |
|
|
Expand or collapse a tab |
Collapse the General tab. |
|
|
Determine if a tab is visible |
Assign a Boolean value to the isGeneralTabVisible variable indicating whether the General tab is visible. |
|
|
Show or hide a tab |
Hide the General tab. |
|
|
Get the label for a tab |
Assign the General tab label to the generalTabLabel variable. |
|
|
Change the label for a tab |
Change the General tab label to Major. |
|
|
Set focus on a tab |
Set focus on the General tab. |
|
|
Get the name of the tab |
Assign the name of the first tab to the firstTabName variable. |
|
|
Get the parent tab of a section |
Set focus on the tab that contains the Industry field. |
|
|
Determine if a section is visible |
Assign a Boolean value to the industrySectionVisible variable indicating whether the section containing the Industry field is visible. |
|
|
Show or hide a section |
Hide the section that contains the Industry field. |
|
|
Get the label for a section |
Assign the label of the section containing the Industry field to the industryFieldSectionLabel variable. |
|
|
Change the label for a section |
Change the label of the section that contains the Industry field to Detailed Information. |
Add or Remove Event Handlers at Runtime
Event handlers are usually configured using the form editor in the application but you can also add them to the form OnSave event and attribute OnChange events at run time using these APIs. The examples in this section will refer to the following function definition: function myFunction() {//perform action here}
While you can add an anonymous function, the function must have a name to reference in order to remove it.
| Task | Method | Example |
|---|---|---|
|
Add a function to the OnSave event |
Add the myFunction function to the OnSave event. |
|
|
Remove a function from the OnSave event |
Remove the myFunction function to the OnSave event. |
|
|
Add a function to the OnChange event of an attribute. |
Add the myFunction function to the OnChange event of the Account Name field. |
|
|
Remove a function from the OnChange event of an attribute |
Remove the myFunction function to the OnChange event of the Account Name field. |
Use Contextual Information
Use these methods to get information about the user, the organization, and the client. The following table provides some of the most useful context methods. For all the context methods, see Client-Side Context Reference
| Task | Method | Example |
|---|---|---|
|
Get the URL to connect to the organization. |
Assign a string that represents the URL to the serverUrl variable.
|
|
|
Get the unique identifier for the current user. |
Assign a string that represents the user’s Id to the userId variable. |
|
|
Get the language code that represents the user’s preferred user interface language. |
Assign a number that indicates the user’s preferred language to the userLCID variable. |
|
|
Get an array of strings that represents the GUID values for each security role assigned to the current user. |
Assign an array of strings that represents the user’s security roles to the userRoles variable. |
|
|
Determine whether the script is running in the Microsoft Dynamics CRM for Microsoft Office Outlook client. |
Assign a Boolean value that represents whether your code is running in the Microsoft Dynamics CRM for Outlook client to the isOutlookClient variable. |
|
|
Determine whether the user is working offine with the Microsoft Dynamics CRM for Microsoft Office Outlook with Offline Access client. |
Assign a Boolean value that represents whether the user is currently working offline to the IsOutlookOffline variable. |
Use Entity Data
The following table contains methods you can use to get information about the current record. For more information, see Xrm.Page.data.entity.
| Task | Method | Example |
|---|---|---|
|
Get the logical name of the current entity |
Assign the logical entity name to the entityName variable. |
|
|
Get the Id of the current record |
Assign the id of the record to the recordId variable. |
|
|
Save the current record |
Saves the record. There are optional arguments. Use saveandclose or saveandnew to perform the equivalent actions using the Save & Close or Save & New buttons. |
|
|
Determine whether any data in the current record is changed. |
Assign a Boolean value that represents whether data in the record has changed to the isDirty variable. |
|
|
Get a string that represents the data that will be sent to the server when the record is saved. |
Assign a string that represents the data to be saved to the dataXml variable. |
See Also
Reference
Xrm.Page ReferenceConcepts
Use the Xrm.Page Object ModelWrite Code for Microsoft Dynamics CRM Forms
Other Resources
Client-Side Programming ReferenceMicrosoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.
Note
Tip