CRM 4.0表单脚本开发一览

Form Scripting Overview

The previous chapters discussed application programming interfaces (APIs) and server-side event options for Microsoft Dynamics CRM. In this chapter we will focus on the many events and programmatic possibilities available to you by using form scripting techniques.

As you would expect, the Microsoft Dynamics CRM SDK acts as an excellent reference, and you can always consult it for additional detail and sample code options. We reference some of the SDK information here for convenience but add to the information in the SDK to cover additional topics and samples.

We cover the following topics in this section:

• Understanding scripting with Microsoft Dynamics CRM
• Referencing Microsoft Dynamics CRM elements
• Available Microsoft Dynamics CRM form events

Understanding Client-Side Scripting with Microsoft Dynamics CRM

Client-side scripting helps distribute the application processing load between the client computer and the Web server. Because Microsoft Dynamics CRM uses a Web-based architecture, it displays all its data on Web pages. However, Microsoft Dynamics CRM pages don't appear as typical Web pages that users see when browsing the Internet. Rather, Microsoft Dynamics CRM relies heavily on DHTML to achieve a more advanced and functional user interface. Because the DOM treats each HTML element as an object, a developer can use traditional DHTML programming techniques to access Microsoft Dynamics CRM forms to create even more customized and sophisticated Web pages in Microsoft Dynamics CRM.

Microsoft Dynamics CRM supports a specialized subset of DOM methods and events as defined in the client-side SDK. We examine many of the available properties and methods here, but you can refer to the Microsoft Dynamics CRM SDK for a complete list of supported methods.

Referencing Microsoft Dynamics CRM Elements

The "Client Extensions and Scripting" section of the Microsoft Dynamics CRM SDK provides information regarding client methods, properties, and events available to a programmer. In Tables 7-1 through 7-9, we highlight a few that you will probably use frequently in your own scripts.

Table 7-1. Global Variables
Name	Description
SERVER_URL	Returns the URL of the CRM Web server
USER_LANGUAGE_CODE	Provides the language code set by the user in Microsoft Dynamics CRM
ORG_LANGUAGE_CODE	Returns the base language for the organization
ORG_UNIQUE_NAME	Returns the organization name

Table 7-2. Global Methods
Method	Description
IsOnline	Gets a Boolean value indicating whether the form is currently online
IsOutlookClient	Gets a Boolean value indicating whether the form is currently being displayed in one of the Microsoft Office Outlook clients
IsOutlookLaptopClient	Gets a Boolean value indicating whether the form is currently being displayed in Microsoft Dynamics CRM for Outlook with Offline Access
IsOutlookWorkstationClient	Gets a Boolean value indicating whether the form is currently being displayed in Microsoft Dynamics CRM for Outlook

Table 7-3. crmForm Properties
Property	Description
All	A collection of CRM attributes on the form.
IsDirty	Gets or sets a value indicating whether any of the fields on the form have been modified.
FormType	Gets an integer value designating the mode of the form. Possible values are:  0 = Undefined Form Type  1 = Create Form  2 = Update Form  3 = Read-Only Form  4 = Disabled Form  5 = Quick Create Form  6 = Bulk Edit Form  Please review more information regarding form types in the "Advanced Topics" section of this chapter.
ObjectId	Gets the entity GUID that the form is displaying. This property returns null if the form is in Create mode.
ObjectTypeName	Gets the entity name of the displayed form.

Table 7-4. crmForm Methods
Method	Description
Save()	Executes the save function (simulates a user clicking Save).
SaveAndClose()	Executes the save and close function (simulates a user clicking Save and Close).
SetFieldReqLevel(sField, bRequired)	Sets a field as required. Note that this method might change or might not be available in future releases.

Table 7-5. crmForm.all Field Collection Properties
Property	Description
Precision	Gets the number of digits to display forcurrency and float data types.
DataValue	Gets or sets the value of the field. Additional parameters are available for picklist andlookup field types.
Disabled	Gets or sets a value indicating whether the field is available for user entry.
ForceSubmit	Gets or sets a value indicating whether the field should be submitted to the database on a save. By default, any enabled,modified field will be submitted. This property is useful when you need to submit a disabled field.
IsDirty	Gets a value indicating whether the field has been modified.
Min	Gets the minimum allowable value forcurrency, float, and integer data types.
Max	Gets the maximum allowable value forcurrency, float, and integer data types.
MaxLength	Gets the maximum length of a string or memo field.
RequiredLevel	Gets the required status of the field. Possible values are:  0 = No Constraint  1 = Business Recommended  2 = Business Required

Table 7-6. crmForm.all Field Collection Methods
Method	Description
SetFocus()	Moves the mouse cursor to the field, making it active on the form
FireOnChange()	Executes the Microsoft Dynamics CRMOnChange event for the attribute specified

Table 7-7. crmForm.all.<lookupfield> Attributes
Attribute	Description
Id	Gets or sets the GUID identifier. Required for set.
TypeName	Gets or sets the referenced entity name. Required for set.
Name	Gets or sets the name of the record to be displayed in the lookup field on the form. Required for set.

Table 7-8. crmForm.all.<picklistfield> Properties and Methods
Syntax	Description
DataValue	Gets or sets the currently selected option, returning an integer.
SelectedText	Gets the text displayed with the currently selected option.
GetSelectedOption	Gets a picklist.
Options	Returns an array of picklist objects and sets new options for a drop-down list by specifying an array of picklist objects.
AddOption(Name,DataValue)	Adds a new option at the end of the picklist collection. Name and DataValue must have valid values.
DeleteOption(value)	Removes a picklist option based on the passed in integer value.

Table 7-9. crmForm.all.<picklistfield> Attributes
Attribute	Description
Text	Gets or sets the text displayed for the option
DataValue	Gets or sets the index value of the selected option

Note

Pay special attention to the new global variables available to you. These variables are important for multilingual and multi-tenant deployments.

The lookup and picklist field types differ from the other fields because they act as arrays(a collection of name/value pairs). The value that Microsoft Dynamics CRM stores in the database (a GUID for lookup fields and an integer for picklist fields) is not the value that the usersees on the form. Microsoft Dynamics CRM includes the following additional attributes fordisplaying the translated value as shown in the next three tables.

Note

Don't forget that the lookup and picklist field types have access to most of the methods contained in the crmForm.all collection as described in Table 7-6. For example, a lookup orpick-list field also has the Disabled and ForceSubmit properties.

Note

You should plan to use only the TypeName attribute. For backward compatibility, Microsoft Dynamics CRM also exposes the Type attribute, which is based on a unique integerassigned to every native entity and to custom entities when they are created in a new deployment. You cannot rely on these integers in your code because they can differ for custom entities between deployments.

The attributes listed in Table 7-7 are available for each item within the array returned when you access crmForm.all.<lookupfield>.DataValue. For standard lookup attributes, there willonly be one item returned. ForPartyList attributes, such as the To field on an e-mail activityform, you could have multiple items returned. The code below loops through a PartyList attribute and displays the various attribute values for each record.

var lookupItem = new Array;

lookupItem = crmForm.all.to.DataValue;

var i;

var result;

// Loop through displaying the data

for (i in lookupItem)

{

  if (lookupItem[i] != null)

  {

    // Text value of the lookup.record

    result = lookupItem[i].name + " | ";

    // GUID of the lookup.record

    result += lookupItem[i].id + " | ";

    // Entity name of the lookup.record

    result += lookupItem[i].typename;

    alert(result);

  }

}

Available Events

Microsoft Dynamics CRM supports three client-side events that you can use for your custom scripts:

• Form onLoad event Executes immediately after the form loads in the browser. By using this event, you can manipulate the form before Microsoft Dynamics CRM displays it to the user.
• Form onSave event Triggers when the user clicks the Save, Save and Close, or Save and New buttons. This event occurs before the form is submitted to the server and canbe used to cancel the save operation. Also, this event always fires, even if the user did not change any of the fields on the form.
• Field onChange events Fires when the user navigates away from a form field (clicks elsewhere or presses the Tab key) in which he or she has changed the value.

Tip

If you want to cancel the save operation, use the following syntax within the onSave event: event.returnValue = false;.

You can add your client-side script to an entity form, in addition to adding scripts with the ISV.Config file by using the JavaScript attribute. Here's a quick refresher on adding client-side scripts with the entity form. We'll cover adding form scripting through ISV.Config later in this chapter.

Adding event code

1.	Using the System Administrator or System Customizer role, navigate to the Settings section, click Customizations, and then click Customize Entities.
2.	In the Customize Entities section, double-click the entity that you want to customize.
3.	In the navigation pane, click Forms and Views.
4.	Double-click Form from the resulting list.

The form editor page is displayed and shows all the tabs and fields that the form will display to the user.

Customizing form events

To customize the form events (onLoad and onSave), follow these steps:

1.	Click Form Properties in the Common Tasks area. A dialog box appears that lists the onLoad and onSave events.
2.	Select the event to which you want to add code, and then click Edit.
3.	Enter your custom script in the Event Detail Properties dialog box, select the Event Is Enabled check box, and then click OK.

Adding scripts to the field event

Adding scripts to the field event (onChange) works the same way as it does for form events:

1.	In the form editor, double-click the field where you will add your code. Or you can select a field and then click Change Properties.
2.	The Field Properties dialog box opens. Click the Events tab.
3.	Click Edit. You will see the Event Detail Properties dialog box, as shown in Figure 7-1.

Figure 7-1. The Event Detail Properties dialog box

 

Remember the following key points related to configuring your client-side scripts on the entity forms:

• You must enable your script by selecting the Event Is Enabled check box in the Event Detail Properties dialog box. This check box tells Microsoft Dynamics CRM to run the script the next time the event is triggered.
• Although not required, it's a good practice to specify the fields your script uses on the Dependencies tab. Specifying dependent fields blocks users from accidentally removing fields from the form that your script requires.
• You can test and debug your scripts prior to publishing the form to production by using one of the form preview options: Create, Update, or Read-Only.
• Microsoft Dynamics CRM provides a Simulate Form Save button on the preview of a form that triggers the onSave event. You can use this button to test your onSave custom scripts.
• Remember to publish your customizations when you have finished.

Warning

Microsoft Dynamics CRM disables fields with an onChange event enabled in the bulk edit form, preventing a user from entering any text.

We show additional scripting examples later in this chapter; we just wanted to quickly introduce you to the customization process and terminology.