Entity Customization: Forms and Views

When a user opens a record, Microsoft CRM displays the form for that record's entity. In addition, Microsoft CRM will display a record's form whenever a user clicks the Information link in the navigation pane, as shown in Figure 5-1.

Most of the system entities use a form, but some of the non-customizable system entities, such as Case Resolution and Organization, don't use a form because users don't view or update these records directly. There are also a few customizable system entities that don't use a form either, such as:

• Contract Template

• Customer Relationship

• Discount

• Discount List

• E-mail Template

• Opportunity Relationship

• Price List

• Price List Item

• Resource Group

• Team

• Territory

• Unit

• Unit Group

Microsoft CRM uses one unique form per entity, so when you customize an entity's form keep in mind that all users will see the same form. For example, you cannot create one form that displays certain fields for sales users, and then create a second form that displays a different set of fields for customer service users.

When you view the default Microsoft CRM entity forms, you will notice that most of data fields displayed on the form are just attributes of the entity. Of course, you probably will want to customize the default form layouts to add more than just attributes to meet the requests of your users. Microsoft CRM allows you to customize the following areas of each form:

• Fields

• Field event scripts

• Tabs

• Sections

• IFrames

• Form event scripts

• Form design and layout

This Topic will explain all of the details related to configuring each of these areas of the form. Form customization follows the same process that you learned in Chapter 4 for attribute customization. After you set up the form exactly how you want it in the Customize Entities section, you must publish the entities you customized before users can see your changes. In addition, you must have the appropriate security permissions to edit forms and publish entities.

To access the entity form editor, follow these steps

1. Go to the Customization section of Microsoft CRM and click Customize Entities.

2. Double-click the entity that you want to edit to open the entity editor.

3. Click Forms and Views.

4. Double-click Form to open the form editor.

   

Forms consist of four components:

• Tabs Tabs allow you to group and organize the data fields for an entity. The default tabs for an entity typically include General, Details, Administration, and Notes.

• Sections On each tab, you can group information into sections. For each section, you can specify a section name and decide whether you want to display the section name and a divider on the form. In Figure 5-2, Account Information and Address are sections on the form. Note that Account Information is grayed out indicating that the section name will not display on the form.

• Fields Fields display the actual data related to an entity. Almost all of the fields on a form are attributes of the entity.

• IFrames Microsoft CRM allows you to display an IFrame (also known as an inline frame) on the form of an entity. You can think of an IFrame as a "window" within the form that allows you to display a different Web page inside the window frame. We'll explain IFrames in more detail and give examples later in this chapter.

In the form editor, you'll notice that dotted lines encapsulate the different areas of the form. These dotted lines indicate the sections, fields, and IFrames. Obviously, the default form for each entity appears a little differently because each entity contains unique attributes. However, all of the entity form editors use these two tools:

• Common Tasks

• Preview

As Figure 5-2 shows, you'll see the Common Tasks tools in the right column of the form editor. You can access the Preview tool from the form editor menu bar. In the following sections, we'll explain how to use both of these tools when you're editing a form. After you understand what the form editor tools do, we will go into greater detail about how to use these tools to set up and configure the following data related to a form:

• Form properties

• Sections

• Fields

• IFrames

You will use the Common Tasks tools to edit everything on the form, including data fields, event scripts, and form layout. The Common Tasks tools consist of the following:

• Directional arrows Four green arrows allow you to move the form components around on the form. The arrows can move fields, sections, tabs, and IFrames. To move a field, section, or IFrame, select it on the form; the dotted line around the area is then highlighted in green. Then click an arrow to move the highlighted item to a new position. To move a tab, select it on the form, and then click an arrow to move it.

• Add a Tab The Add a Tab tool allows you to add a new tab to the form. Microsoft CRM adds the new tab to the right of existing tabs. Note that you can add a maximum of eight tabs.

• Add a Section This tool allows you to add a new section to a form. Microsoft CRM always adds the new section below the last section on the currently selected tab.

• Add Fields The Add Fields tool allows you to select new fields to add to the form. When you click Add Fields, the dialog box only displays fields not already on the form, so if you don't see the field that you're looking for, it's probably already on the form somewhere. If you want to add a field to a specific section, select the section to highlight it, and then click Add Fields.

• Add an IFrame This tool allows you to add an IFrame to the form.

• Change Properties This tool allows you change the properties of a form component, including tabs, sections, fields, and IFrames. You can also open the Change Properties dialog box by double-clicking a component in the form editor.

• Remove This tool allows you to remove a component (including tabs, sections, fields, and IFrames) from the form.

• Form Properties This tool allows you to specify scripts to run when Microsoft CRM triggers form events.

You'll use the Common Tasks tools to layout and design almost all of the information that appears on an entity's form. At first it might seem like a lot to learn, but the tools are very intuitive and straightforward, so we're sure you'll learn to use these Common Tasks tools quickly.

When you're done manipulating your form and you have everything where you want it, you can use the convenient form preview tool to evaluate how the form will appear to users before you publish it. Microsoft CRM offers the following three types of form previews:

• Create Form Simulates how the form will appear and behave when users create a new record for the entity.

• Update Form Simulates how the form will appear and behave when users edit an existing record.

• Read-Only Form Shows how the form will appear to users who do not have permissions to edit a record.

The form preview feature does more than just show you the form layout—you can also test any custom scripts that you added to the form. Microsoft CRM offers you three different events for which you can create custom scripts:

• onLoad form event

• onSave form event

• onChange field event

Obviously, being able to test and debug your event scripts using the preview tool will save you time. When you launch the form preview, Microsoft CRM will fire the onLoad event which you can use to trigger your custom script. Because the preview doesn't actually save a record, you can use the Simulate Form Save button in the form preview menu bar to triggers the onSave form event. You can also fire the onChange field event by changing the field focus (by pressing the Tab key to leave a field or by clicking a different field).

The Form Properties tool in Common Tasks allows you to add custom scripts to the form's onLoad and onSave events. The Form Properties dialog box contains two tabs (shown in Figure 5-3):

• Events You can add custom scripts to a form that run when Microsoft CRM triggers the onLoad or onSave event. When you add custom scripts to the form, Microsoft CRM allows you to manually specify which fields those scripts reference (on the Dependencies tab of the event). By indicating the script-dependent fields, Microsoft CRM will prevent other system customizers from removing a field from the form that a script uses. If you don't specify dependent fields and a user unknowingly removes a script-dependent field from a form, the script will fail.

• Non-Event Dependencies If you are also using additional external (non-event) scripts, you can manually specify these fields as dependent.

  

As we just explained, if you try to remove a field from a form that you specified as dependent (either on an event or a non-event), Microsoft CRM denies your request and displays an error message similar to the one shown in Figure 5-4.

Now that you understand how to add scripts by using the Form Properties page, let's walk through a few simple examples to illustrate how and why you might want to use the onLoad and onSave events.

When users create a new task in Microsoft CRM, the default form appears like the one shown in Figure 5-5.

Because this form in Microsoft CRM 3.0 did not change much from Microsoft CRM version 1.2, we know that customers frequently want to make the following changes to the form:

• Change the default duration from 30 minutes to blank.

• Automatically populate today's date in the Due Date field.

These two changes might seem simple at first, but digging deeper into the details of these fields reveals some issues. Because the Duration field looks like a picklist field, you might expect to be able to simply change the default value by editing the Duration attribute of the Task entity. However, even though the Duration field appears to be a picklist, it is actually a special integer field used on a variety of picklist fields in Microsoft CRM. For these special fields, you cannot set a default value (or add picklist values) like you can for normal picklist fields.

In regards to the Due Date field, you learned in Chapter 4 that datetime attribute data types do not have a default value. Because the Due Date field uses the datetime data type, we can't use the attribute editor to specify today's date as the default value in the Due Date field. Hence, we now have two issues to solve regarding the customer requests.

Despite the two problems we just outlined, we can easily meet the customer's needs by leveraging the onLoad event of the task entity's form. To do this, we will add a simple script to the form's onLoad event, and Microsoft CRM will run our script every time a user opens the task form. When our script runs, it will programmatically change the value of the Duration and Due Date fields to the values that we specify. The last issue that we need to address with our script is to make sure that we change the Duration and Due Date values only when users create a new task. Obviously, we wouldn't want to change the Due Date and Duration values when a user opened a previously created task. When we're done, every time a user creates a new task, our script will set the Duration field to blank and the current date as the due date.

Now we'll describe how you would set up, test, and deploy this code.

• Go to the Customization section of Microsoft CRM and click Customize Entities. Double-click the Task entity to open the entity editor.

• Click Forms and Views, and then double-click Form to open the form editor for the Task entity.

• Click Form Properties. On this page, you can choose to add a script to the form's onLoad or onSave event.

• As we mentioned previously, we want to use the onLoad event so that the script runs when users open a form.

• Select OnLoad, and then click Edit to open the Event Detail Properties page. On this page, enter the following code:

  					 var CRM_FORM_TYPE_CREATE = 1;
  					 var CRM_FORM_TYPE_UPDATE = 2;
  					 switch (crmForm.FormType)
  					 {
  					  case CRM_FORM_TYPE_CREATE:
  					  crmForm.all.actualdurationminutes.DataValue
  					 = null; 
  					 crmForm.all.scheduledend.DataValue = new Date();
  					  break;
  					  case CRM_FORM_TYPE_UPDATE:
  					  // do nothing
  					  break;
  					 } 

• Now let's quickly review how this JavaScript code will programmatically set the values on the form. This code sets the actualdurationminutes field (the schema name for Duration) to null, which means blank. It also sets the scheduledend field (the schema name for Due Date) to the current date by using the JavaScript Date() function. The onLoad event will run this script every time a user opens a form, but remember that we want to set the default values only when users create a new task. Therefore, this code includes a switch statement so that our script runs only for the form type of 1. Microsoft CRM assigns a form type value to each form (1: Create, 2: Update, 3: Read Only, and so on) so that you can tie this information into your scripts, as we did in this example. In this script, a form type of 2 indicates an Update form, so that the script won't alter the Due Date or Duration field values.

• After you enter the code, select the Event is enabled check box. This check box indicates whether Microsoft CRM should run your script when it fires the onLoad event.

• To set up the dependencies related to our code to ensure that no one accidentally removes the Duration or Due Date fields from the task form (because our script would generate an error if those fields were missing), click the Dependencies tab.

• The Available fields list displays all of the fields that appear on the task form. To make Due Date and Duration dependent fields, select those values in the left column, and then click the >> button to move them into the Dependent Fields list.

  

• Click OK.

• Click OK again to return to the task form editor.

• Before you try to preview this script, save the changes you made by clicking Save.

• To test the script on the create form, click Preview, and then click Create Form. The form should appear as shown here.

  

• You'll see that the Duration drop-down list is blank, and the Due Date field displays today's date and time. You might need to resize the preview window to make it large enough to display all of the fields correctly.

• If you test the script on the update form (click Preview, and then click Update Form), you'll see that the Due Date field does not default to today's date as we expect. However, you might notice that the Duration field appears blank. When you use the Update Form preview, Microsoft CRM shows you an update of a blank record, so it will always show picklists as blank. The script ran correctly, but the fact that Microsoft CRM shows an update of a blank record might cause some little nuances with the form previews?

• To publish the task entity, return to the entity editor. Click Actions, and then click Publish on the top toolbar. That's it, you're done!

This example showed you how to tap into the form's onLoad event to manipulate field values before users see the form. Even if you didn't understand the syntax of this code example, you should understand the concepts of customizing your forms by adding custom scripts that tie into Microsoft CRM form events. Figure 5-6 is a flow chart that shows how Microsoft CRM processed the code in our example.

Form sections allow you to group together and organize multiple data fields in a manner that makes the most sense for your users. Every field you add to a form must belong to a section, and you can have as many sections as you need on a form. Each section contains multiple properties:

• Name The name of the section. It must be unique for each entity.

• Label Specifies whether you want the section name to appear to users on the form. You can also specify whether you want to display a divider line under the section name on the form.

• Location Specifies which tab on the form the section should appear on.

• Layout Specifies the formatting layout of the fields in the section. After you create a section, you cannot change its layout. You can access the section's layout on the formatting tab when you view a section's properties.

  Working with sections is a pretty straightforward process, and only the layout properties require a more detailed explanation.

  When you add a new section, you have the option to specify its layout. Microsoft CRM allows you to choose from one of two mutually exclusive section layouts:

• Variable Field Width This layout displays all of the fields in the section in two columns. However, you can specify that specific fields (on a field-by-field basis) in the section span the width of both columns on the form.

  

• Variable Field Height A Variable Field Height section layout gives you the option to specify how the columns and widths should display in a section. You can choose from one of four column formats.

  

When you select one of these formats, the number of columns in that section remains fixed. So, unlike a Variable Field Width section, you cannot configure a field to span the width of multiple columns. Another way to think of Variable Field Height layout is as a fixed width section. All of the fields in a Variable Field Height section will have the width that you specify when you create the section (1:2, 2:1, 1:1, or 3). However, the Variable Field Height layout allows you to include text areas in a column and change the height of the column to meet your needs.

All of the default Microsoft CRM 3.0 forms (and all of the forms in Microsoft CRM version 1.2) use the Variable Field Width layout exclusively. We created a sample section layout that uses the Variable Field Height to illustrate one potential design (Figure 5-7).

Similar to sections, you can add, modify, remove, and change the properties of a field by using the Common Tasks tools. For each field on a form, you can set the following properties related to that field (shown on the tabs in Figure 5-8):

• Display

• Formatting

• Schema

• Events

You can adjust the following display settings for each field:

• Label Use this section to set the text that appears on the form to the left of the field. You can hide the field label by unchecking the Display label On the form check box.

• Field Selecting the Disabled on the form check box makes the field read-only on the form. This means that users can read the value of the field, but they cannot change it.

• Location Use this section to specify the tab and section where the field should appear on the form.

• Locking Selecting the check box in this section prevents users (including yourself) from removing the field from the form. A lock icon appears in the form editor next to the field label of a locked field. Of course, a user with customization privileges to customize a form could simply unlock a locked field and then remove it. Therefore, locking a field isn't foolproof, but it should indicate to others that it shouldn't be removed from the form.

On the Formatting tab, you can set up additional formatting properties. For a field in a section that uses the Variable Fixed Width layout, you can use the Layout section to toggle between the one-column and two-column displays. If this section is disabled, the field is in a section that uses the Variable Fixed Height layout.

Bit Data Types For fields of the bit data type, you can specify the formatting of the data field on the form. By default, Microsoft CRM displays bit options such as yes/no and true/false with two radio (option) buttons. However, you can change this formatting to a check box or drop-down list if you like (see Figure 5-9).

Ntext and nvarchar (text) Data Types For fields of the ntext and nvarchar data type, you can also configure the row layout to change the number of rows of the text area to display on the form (see Figure 5-10).

For fields within a Variable Fixed Width section only, you can also specify whether the field should automatically expand to use available space. If you select this check box, the form will override the number of rows you specified and expand to include more rows if they will fit in the window. You can use this auto-expand feature on only one field per tab. Figure 5-11 shows two different forms and the benefit of using the auto-expand feature.

As we covered earlier in this chapter, you can include custom scripts that Microsoft CRM triggers on the field's onChange event. Let's set up a simple example of an onChange event to illustrate how you might use this feature. Many businesses assign a unique account number to each of their customers, and our example customer would like every account number to contain eight digits. Creating a custom onChange script that runs on the Account Number field would be a good way to remind users that every account number should be eight digits in length.

						var oField = event.srcElement;
						if (typeof(oField) != "undefined" &&
						oField != null) {
						 if (oField.DataValue.length !=
						8)  alert("Account Number should
						be 8 characters."); }
						 

• Customizing Views
  Microsoft CRM uses views to display multiple records at one time. You can customize almost all of the views used in Microsoft CRM to display... Read More
• Customizing Activities
  Activities are the heart Microsoft CRM. The main purpose of any CRM system is to effectively track and manage all of the sales, service, and marketing data related to your customers... Read More