Client-Side SDK Overview


After reading Chapter 9, "Server-Side SDK," you should be familiar with the Microsoft CRM API and general architecture. We will now focus on the many events and programmatic possiblilities available to you by using client-side techniques. We'll cover the following topics in the client-side SDK overview:

  • Definitions

  • Understanding client-side scripting with Microsoft CRM

  • Referencing CRM elements

  • Available events

Definitions

Before we get too deep in the client-side SDK and examples, let's review a few key expressions and their definitions.

  • Client-side scripting Code that executes on a user's Internet browser, instead of a centralized Web server.

  • Hypertext Markup Language (HTML) A tag-based language used to render content in an Internet browser.

  • Cascading style sheet A definition document that describes how a Web document should display formats and styles to the user.

  • Document Object Model (DOM) An application programming interface designed to access HTML documents, representing elements in the document in an object-oriented model.

  • Dynamic HTML (DHTML) A technology that extends regular HTML with client-side scripting and cascading style sheets, exposing the elements on an HTML document so that you can manipulate them programmatically by using the DOM.

  • Globally unique identifier (GUID) A string that represents a unique value. Microsoft CRM uses a GUID as the unique identifier for each record.

Understanding Client-Side Scripting with Microsoft CRM

Client-side scripting helps distribute the application processing load between the client computer and the Web server. Because Microsoft CRM uses a Web-based architecture, it displays all of its data on Web pages. However, the Microsoft CRM pages don't appear as typical Web pages that users see when browsing the Internet. Rather, Microsoft 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 may use traditional DHTML programming techniques to access the Microsoft CRM forms to create even more customized and sophisticated Web pages within Microsoft CRM.

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

Referencing CRM Elements

The "Client Programming Guide" section of the Microsoft CRM SDK provides information regarding the client methods, properties, and events available to a programmer. In the following tables, we highlight a few of the key actions that you will probably use frequently in your own scripts.

Table 10-1: Global Methods

Property

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 the full, offline-capable Microsoft CRM client for Outlook, also known as the Microsoft CRM laptop client for Outlook.

IsOutlookWorkstationClient

Gets a Boolean value indicating whether the form is currently being displayed in the online-only Microsoft CRM client for Outlook, also known as the Microsoft CRM desktop client for Outlook.

Table 10-2: crmForm Properties

Property

Description

all

A collection of CRM fields 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

ObjectId

Gets the entity GUID that the form is displaying. This property returns null if the form is in Create mode.

ObjectTypeCode

Gets the integer code of the entity that the form is displaying (1 = Account, 2 = Contact, and so on).

Table 10-3: 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 is unsupported and may change or not be available in future releases.

Table 10-4: crmForm.all Field Collection Properties

Property

Description

Precision

Gets the number of digits to display for currency, and float data types.

DataValue

Gets or sets the value of the field.

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 for currency, float, and integer data types.

Max

Gets the maximum allowable value for currency, 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 10-5: crmForm.all Collection Methods

Method

Description

SetFocus()

Moves the mouse cursor to the field, making it active on the form.

FireOnChange()

Executes the Microsoft CRM OnChange event for the attribute specified.

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 CRM stores in the database (a GUID for lookup fields and an integer for picklist fields) is not the value that the user will see on the form. Because you probably don't want to reference the GUID or integer value, Microsoft CRM includes the following additional attributes of the DataValue property for displaying the translated value as shown in the next three tables.

Table 10-6: crmForm.all.<lookupfield>.DataValue Attributes

Attribute

Description

id

Gets or sets the GUID identifier. Required for set.

type

Gets or sets the object type code. 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 10-7: 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(option)

Adds a new option at the end of the picklist collection. DataValue and Name must have valid values.

DeleteOption(value)

Removes a picklist option based on the integer value passed in.

Table 10-8: crmForm.all.<picklistfield>.DataValue Attributes

Attribute

Description

Name

Gets or sets the text displayed in the picklist.

Data

Gets or sets the data.

Available Events

Microsoft CRM supports three client-side events that you can reference within your custom scripts:

  • Form onLoad event Executes immediately before the form loads in the browser. This event allows you to manipulate the form before displaying it to the user.

  • Form onSave event Triggered when the user clicks the Save, Save and Close, or Save and New buttons. This event happens before the form is submitted and can be used to cancel the save. 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 changed the value.

Note 

The form onSave event for Microsoft CRM does not correspond to the standard DTHML onSave event. If you want to cancel the save, use the following syntax: event.returnValue = false;

We introduced adding client-side scripts to an entity form in Chapter 5, but we'll go through a quick refresher anyway.

Adding Event Code

With a System Administrator or System Customizer role, you will navigate to the Settings section, click Customizations, and then click Customize Entities.

  1. In the Customize Entities section, double-click the entity that you want to customize.

  2. In the navigation pane, click Forms and Views.

  3. Double-click Form from the resulting list.

The form editor page will now display and show all of the tabs and fields that the form will display to the user, as shown in Figure 10-1 for the Account entity.

image from book
Figure 10-1: The form editor page

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 that you want to add code to, and then click Edit.

  3. Enter your custom script in the Event Detail Properties dialog window (shown in Figure 10-2), select the Event is enabled check box, and then click OK.

image from book
Figure 10-2: The Event Detail Properties dialog box

Adding Steps 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 will launch. Click to the Events tab.

  3. Click Edit. You will see the Event Detail Properties dialog box, as shown in Figure 10-2.

Remember these 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 on the Event Properties dialog. This check box tells Microsoft CRM to run the script the next time the event triggers.

  • Although not required, it's a good practice to specify the fields your script uses on the Dependencies tab. Specifying dependent fields will block users from accidentally removing fields from the form that your script requires.

  • You can test and debug your scripts by using one of the form preview options: Create, Update, and Read-Only.

  • Microsoft CRM provides a Simulate Form Save button on the preview that will trigger the onSave event. You can use this button to test your onSave custom scripts.

  • Of course you need to remember to publish your customizations when you're done.

We'll show lots of examples of client-side customizations later in this chapter. We just wanted to give you a quick background on the customization process and terminology.




Working with Microsoft Dynamics CRM 3.0
Working with Microsoft Dynamics(TM) CRM 3.0
ISBN: 0735622590
EAN: 2147483647
Year: 2006
Pages: 120

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net