:: Home     :: MS Dynamics CRM     :: .Net 1.1     :: .Net 2.0     :: Sharepoint Portal     :: Ajax

  login:        
  passwords:  

Entity Customization: Forms and Views


Customizing Forms

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

Accessing the Form Editor
  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

Common Tasks

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.

Form Preview

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).

Form Properties

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.

p align="center">

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.

Using the Form's Onload Event to Pre-Fill Task Duration and Due Date
  • 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.

Selection

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).

Fields

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

Display

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.

Formatting

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.

Schema The Schema tab displays the schema information for the attribute, including the display name, schema name, and description. To edit the display name and description information, you must update these values using the attribute editor for the entity Events

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.

Using the Field's onChange Event to Enforce Account Number Length
  • Go to the Customization section of Microsoft CRM and click Customize Entities. Double-click the Account entity to open the entity editor.

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

  • Double-click the Account Number field on the form to open the Field Properties page. Click the Events tab.

  • Select onChange, and then click Edit to open the Event Detail Properties dialog box. Enter the following code:

    						var oField = event.srcElement;
    						if (typeof(oField) != "undefined" &&
    						oField != null) {
    						 if (oField.DataValue.length !=
    						8)  alert("Account Number should
    						be 8 characters."); }
    						 
  • Select the Event is enabled check box to tell Microsoft CRM to run this script when the field's onChange event fires.

  • To add Account Number as a dependent field so that our script always runs properly, click the Dependencies tab, select Account Number, and click the >> button. Account Number moves to the Dependent fields list. Click OK.

  • On the Field Properties page, click OK.

  • Save the Account form.

  • To test this custom script, click Preview, and then click Create Form. The preview window appears.

  • Enter 1234567 into the Account Number field, and then press the Tab key. The following prompt appears, reminding you that account numbers should contain eight digits.

    Tweaking the Tab Order of Fields on a Form

    When your users enter data on a form, they can use the Tab key to advance from one field to the next field on the form. To move back to the previous field on a form, they can press Shift+Tab. These keyboard functions allow users to enter form data much more quickly than by clicking from field to field with their mouse. As users press the Tab key, Microsoft CRM moves the cursor from field to field down the column of a section and then it moves to the top of the next column (left to right). When users reach the last field in a section, pressing the Tab key advances them to the upper-left field of the next section (see Figure 5-12).

    In standard HTML code, you can specify a tab index for each field on a form to control the order in which users move from field to field. Unfortunately, you cannot specify tab indexes on form fields in Microsoft CRM. However, you can easily manipulate the tab sequence that users experience by understanding the Microsoft CRM tab behavior and then getting clever with your use of form sections. Conceptually, you can create invisible sections on a form and place the form fields in the appropriate sections, depending on how you want users to proceed. You can make a section invisible by not displaying its name or the divider line on the form. Figure 5-13 shows how to change the tab order from the initial order shown in Figure 5-12.

    IFrames

    Microsoft CRM allows you to add IFrames (also known as inline frames) to an entity's form. IFrames open the door to almost unlimited customization capabilities within Microsoft CRM forms. Conceptually, an IFrame creates a frame within a Web page that displays a second Web page. The Web page within the IFrame can be any Web page that you want, whether it is hosted on your server or not. In the context of Microsoft CRM, you can add one or more IFrames to any entity's form. Figure 5-14 shows an example of an IFrame on an Account form that references a Sharepoint intranet Web site.

    Although you can see that we need to work out some formatting with the Sharepoint Web site in the IFrame, the concept is that you can reference other non-Microsoft CRM Web sites by using an IFrame. Potential uses for an IFrame on a form include the following:

    • Displaying external Web sites

    • Displaying your own custom Web pages

    • Displaying photos or images related to the record

    • Displaying other Web sites on your intranet

    The most important feature of the IFrame capability is that Microsoft CRM allows you to programmatically manipulate the Web address (Uniform Resource Locator, or URL) that the IFrame displays. By doing so, you can display Web pages in the IFrame that are unique to the record you are looking at instead of displaying a generic URL such as http://sharepoint. So instead of showing the same SharePoint site for every record, you could show the portion of the site that is specific to the record you're looking at. Combining the IFrame display within a form with the ability to dynamically create URLs provides you with amazing customization possibilities.

    Now that you understand the benefits of using IFrames in Microsoft CRM forms, let's review the details related to using an IFrame. When you click the Add An IFRAME in the Common Tasks tool on the entity form editor, you are prompted to configure the following IFrame properties on the properties page, shown in Figure 5-15:

    • Name

    • Label

    • Security

    • Location

    • Layout

    • Row Layout

    • Scrolling

    • Border

    • Dependencies

    We'll review each of these properties in detail.

    Name

    In the Name section on the General tab, you specify the name of the IFrame and its URL.

    Name Notice that Microsoft CRM automatically prefixes the value IFRAME_ to your IFrame name. Unlike the attribute schema prefix that you can configure, you cannot alter this value. After you create an IFrame, you cannot change its name.

    URL In the URL field, you enter the address of the Web page or resource that you want to reference in the IFrame. You can specify the full URL (including the http://), or a relative URL.

    Parameters If you select the Pass record object-type code and unique identifier as parameters check box, Microsoft CRM will append additional querystring parameters to the IFrame URL. Table 5-1 shows how the IFrame URL would appear with and without the parameters check box selected if you entered http://www.adatum.com as the IFrame URL.

    Table 5-1: Passing Parameters to IFrames

    Parameters Passed?

    URL displayed in the IFrame

    No

    http://www.adatum.com

    Yes

    http://www.adatum.com?type=<objecttypecode>&typename=<schemaname>&<GUID>

    <GUID> is the globally unique identifier and is the ID of the current record. An example URL with a real GUID would look like this:

    http://www.adatum.com?type=112&typename=incident&{}

    You can see that passing parameters appends the object type code, the schema name, and the GUID of the record to the querystring. Every Microsoft CRM record has a corresponding object type code such as 1, 2, and so on that references entities (for example, 1 = Account, 2 = Contact, and so on). By including these dynamic parameters in the URL, you can make the Web page in the IFrame behave differently if necessary. The Microsoft CRM SDK lists all of the object type codes for each entity.

    Label Similar to form sections, you can add a label to the IFrame on the form and specify whether to display this label to users. Security

    Because IFrames display content from another Web site, scripts from that alternate Web site could run and perform malicious or unintended behavior within Microsoft CRM. By default, Microsoft CRM blocks cross-frame scripts from the IFrame Web site. Chapter 10 explains cross-frame scripting and related security considerations in detail. For the most part, you should leave the Restrict cross-frame scripting check box selected unless you know that you need to allow cross-frame scripting.

    Location Use these properties to specify the tab and section in which to display the IFrame Layout Figure 5-16 shows the Formatting tab of the IFrame properties page.

    Scrolling

    You can configure the scrolling type for each IFrame. Scrolling refers to adding a scroll bar within the IFrame so that users can move the page up and down within the IFrame. Figure 5-14 shows an example of an IFrame with both horizontal and vertical scroll bars. The three scrolling options are:

    • As Necessary Microsoft CRM automatically determines whether it needs to add scroll bars. If the content in the IFrame takes more vertical (or horizontal) space than the IFrame offers, Microsoft CRM adds scroll bars.

    • Always Microsoft CRM always includes horizontal and vertical scroll bars.

    • Never Microsoft CRM never includes horizontal and vertical scroll bars.

    We recommend that you leave the default option, As Necessary, selected.

    Border

    This IFrame property determines whether Microsoft CRM displays a small, one-pixel blue border around the IFrame. This border matches the style of the border that surrounds each of the data fields on the form.

    Dependencies

    If you use scripts in your IFrame that reference fields on the form, you can specify those fields as Dependent on the Dependencies tab. This will prevent users from accidentally removing dependent fields from the form.

    Being able to add IFrames to forms is one of the most exciting form customization tools available because it opens up so many customization and integration options. You can reference existing Web sites like we just showed you, or you can create entirely new custom Web pages that blend into the form so that users don't even know they're working with a custom Web page.

    • 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
    ::  Home :: Services ::  Prices ::  Request Quote
    Copyright 2005-2015, Megasolutions Ltd