Customize Entity Forms
This topic describes how to customize entity forms. Forms can be customized in three ways:
- Form Editor
- Use the form editor in the application to customize forms. For more information about how to use the customization capabilities of the application, see the application Help.
FormXml contains the data that defines the form. There are two ways you can access the FormXml:
The customizations.xml file exported with an unmanaged solution contains definitions for entity forms. You can edit the FormXml and import the solution.
FormXml is stored in the SystemForm entity. You can programmatically retrieve and update the FormXml using this entity. For more information, see Form XML Reference.
- The customizations.xml file exported with an unmanaged solution contains definitions for entity forms. You can edit the FormXml and import the solution.
- Form Scripts
- At runtime, you can work with the form by using Xrm.Page.ui.
The most appropriate way to customize the form depends on your requirements. This topic provides an overview with references to performing tasks using the form editor, FormXml, and form scripts.
In This Topic
In the form editor, click the Form Properties button to change the following groups of properties:
Within events you can specify form libraries and event handlers.
- Form Libraries
- You can specify up to 50 JScript Web resources as script libraries with functions that can be called in the form. Each of the libraries are defined by using <Library> (FormXml) elements. Each of the libraries is loaded in the order they are found in the <formLibraries> (FormXml) element.
- Event Handlers
- The form has two events: Onload and Onsave. For each event you can define up to 50 event handlers. The following FormXml elements are used to specify events: <events> (FormXml), <event> (FormXml), <Handlers> (FormXml), <Handler> (FormXml). You can add and remove functions for the form OnSave event at run-time using the Xrm.Page.data.entity addOnSave and removeOnSave methods. Because code in a function may depend on specific field values in the form, you should register any dependent fields used in a function. Each event has a list of <dependency> (FormXml) elements representing fields that cannot be removed from the form because they are referenced by function for that event.
- Specify a name and description for the form. These are added by using the <LocalizedName> (FormXml) and <Description> (FormXml) elements for the form. You can hide the navigation area by unchecking the Show navigation items check box. This corresponds to the <form> (FormXml) element shownavigationbar attribute.
- You can specify which custom query string parameters you will enable to be passed to a form. These are stored in the <querystringparameter> (FormXml) element. For more information, see Configure a Form to Accept Custom Querystring Parameters.
- Non-Event Dependencies
- Each event has an area where dependencies may be recorded that are specific to that event. External dependencies are not related to a specific form or field event. For example, if you are setting the default value of a field by using a query string to open a form for a new record, or if the target of an IFRAME or a Web resource reads data from the form.
The form managed property “Customizable” is stored in the <IsCustomizable> (FormXml) element.
Use the <webresource> (FormXml) to specify JScript and CSS Web resources to be loaded with the form separately from any form libraries. You will be able to call functions that are contained in these libraries. However, they will not be available to be associated directly with form or field events and no dependencies to form fields can be set.
Major Form Elements
The major visible elements of the form are displayed in the following diagram:
- Entity Icon
- You can change the icons used for custom entities. This data is part of the entity definition instead of the form. For more information about how to change entity icons, see Modify Icons for an Entity.
- Header and Footer
- The header and the footer provide an area to display read-only data. These areas of the form cannot be accessed by using form scripting. If no fields are included in these areas they will not display in the form. The <header> (FormXml) and <footer> (FormXml) elements in the FormXML are very similar to <section> (FormXml) elements.
- Form Assistant
The form assistant provides help when you set the values of lookup fields. Improved capabilities to filter data returned in the lookup dialog box means that the form assistant is usually not required. For Microsoft Dynamics CRM 2011, the form assistant has been turned off for all except three entity forms:
Service Activity (serviceappointment)
enablerelatedinformationattribute to false. The form assistant is not available using form scripting.
- Case (incident)
- Form Selector
- When an entity has more than one form defined for it and the user belongs to security roles that enable them to view more than one form, the form selector is displayed instead of the form label. When an entity form loads the <DisplayConditions> (FormXml), data for all available forms is evaluated to determine which form to display and which forms to enable for selection. For more information, see Manage Role Based Forms. With form scripts, use the navigate method to change the form being viewed.
The navigation area typically allows for navigation to lists of related records. You can add, remove or reorganize the lists of related entities displayed in this area using the form editor.
You can also include links to URLs or Web resources by adding navigation links using the form editor.
The <Navigation> (FormXml) node controls what is displayed in the navigation area. For each group in the navigation area there is a corresponding <NavBarArea> (FormXml) node that controls the title label for the group. The default titles can be changed but additional groups cannot be added. Each of the items that appear in the groups are defined either by <NavBarByRelationshipItem> (FormXml) or <NavBarItem> (FormXml) elements. Both of these elements contain attributes to control how the navigation item is displayed. By editing the formXML for the NavBarItem element you can control whether the navigation link will be displayed when the user is working offline or when they use specific Microsoft Dynamics CRM clients. Editing the <NavBar> (FormXml) container will let you control whether the items should be displayed for the create or update forms using the ValidForCreate and ValidForUpdate parameters.
Form scripts can access the navigation items using the Xrm.Page.ui.navigation.items Collection. Each item contains methods to show or hide the item, get or set the label and set focus on the item.
Tip Because the lists or pages are displayed in the same frame as record data, it is not always the best solution because users cannot view record data at the same time. An alternative is to define a subgrid in a section of a form.
- Ribbon Area
The form editor does not let you customize the ribbon area. The ribbon controls displayed for a specific form are defined in three layers:
For more information, see Customize the Ribbon.
- All Entities: An entity template defines a default set of form ribbon controls for all entities.
This is the ribbon you will see in a new custom entity where the ribbon hasn’t been modified.
- Per Entity: Changes to the default form ribbon definition can be defined for an entity that will appear in all forms for that entity.
- Per Form: An individual form can contain changes to the default entity form ribbon definition in the <RibbonDiffXml> (FormXml) element.
Note While the ribbon provides capabilities to retrieve data from a form or grid, the only capability to interact with the ribbon using form scripting is the Xrm.Page.ui.refreshRibbon method.
- All Entities: An entity template defines a default set of form ribbon controls for all entities.
- A tab can contain any number of sections in the tab columns. Sections allow for grouping and layout of controls within them. The <sections> (FormXml) element contains the section definitions in a tab column element. With form scripts the Xrm.Page.ui tab.sections Collection provides access to sections within each tab.
- Each form can include up to 100 tabs. Tabs are a vertical stack separating the body of the form. Tabs may be expanded or collapsed. Navigation links under the form selector provide access to tabs. The body of the form will scroll to display the selected tab. The <tabs> (FormXml) element contains the definitions of all the tabs in the form. The Xrm.Page.ui.tabs Collection provides access to the tabs with form scripting.
Form Body Elements
You can use form scripting to perform the following actions on all form body elements except spacers:
Determine if an element is visible and show or hide it using getVisible and setVisible methods.
Retrieve or change the label for the element by using getLabel and setLabel methods.
Set focus on the element by using the setFocus method.
Retrieve the containing element by using the getParent method.
The following elements can be added to the form body using the form editor:
- Customizers use the form editor to add fields to a form. Each field represents an entity attribute. The form editor allows for each field to be added to the form more than one time. Each instance of a field on the form represents a control. The appearance and behavior of the control is defined by the type and formatting option of the attribute as well as display and formatting properties set on each control by using the form editor. Therefore, you can apply different display and formatting properties to separate instances of the same field, but the behavior controlled by the attribute definition cannot be changed. The <control> (FormXml) element is the container for all controls. Lookup controls can accept several parameters to control their behavior. For more information, see <parameters> (FormXml). Each field has an OnChange event. In the Form editor field properties dialog box you can associate a function from a JScript library to handle the OnChange event. The OnChange event represents a change in data so the event actually occurs in the Xrm.Page.data.entity.attribute that corresponds with the control after the control loses focus (the onblur event). Adding an OnChange event to any field will apply it to all instances of that field in the form. You can add or remove a function for the OnChange event at run-time by using the Xrm.Page.data.entity attribute addOnChange and removeOnChange methods. For more information, see Field OnChange Event Each field contains a <events> (FormXml) node with information about the OnChange event pipeline for the control. For more information, see Use Execution Context and the Form Event Pipeline.
- An IFRAME is a control that provides an HTML IFRAME in the form. The form editor provides the ability to set properties that correspond to the regular IFRAME properties as well as properties specific to Microsoft Dynamics CRM. For more information, see Use an IFRAME and Web Resource Controls on a Form. IFRAMEs have an OnReadyStateComplete event that can be used in form scripting to detect when the content of the IFRAME has finished loading. For more information, see IFRAME OnReadyStateComplete Event. The IFRAME control is available in the Xrm.Page.ui.controls Collection but it is not associated with an attribute. The getAttribute method will return null. An IFRAME is a <control> (FormXml) element that has a specific classid attribute value. It accepts several parameters that are specified in the IFRAME properties. For more information aboutthe parameters for the IFRAME control, see <parameters> (FormXml).
- The notes control can only be added to a form one time when the entity has an entity relationship with the Annotation entity. The notes control is available in the Xrm.Page.ui.controls Collection but it is not associated with an attribute. The getAttribute method will return null. There are no events associated with the notes control.
- Each section can be assigned a name. You have the option to display the name on the form or include a separator line at the top of the section, underneath the name. A section may have up to four columns. You can control the width available for control labels to be displayed in the section as well as how labels for controls in the section should be aligned. The <section> (FormXml) element contains attributes that define the behavior of the section as well as <labels> (FormXml) and <rows> (FormXml) that control the text displayed and layout.
- The spacer element is provided in the form editor to better control layout in a section. Spacers cannot be accessed by using form scripts. When the <cell> (FormXml) element that usually contains a control has a userspacer attribute set to true, the cell is rendered without anything in it.
- The sub-grid control allows for definition of an in-line control where you can display a list of records, a chart, or both. The user can interact with the sub-grid using options specified by using the form editor. These options are set in FormXML using parameters. For more information aboutvalid parameters for the sub-grid element, see <parameters> (FormXml). The sub-grid control is available in the Xrm.Page.ui.controls Collection but it is not associated with an attribute. The getAttribute method will return null. The sub-grid control has a refresh method that will refresh data displayed in the sub-grid. The first four sub-grids can be populated with data in a form when it loads. If more than four sub-grids exist on a form, the remaining sub-grids require some user or form script action to retrieve data. This is for performance optimization.
- Each tab can be assigned a name. You have the option to display the name on the form or include a separator line at the top of the tab, underneath the name. A tab can have one or two columns. When two columns are specified the width of each column is a percentage of the width of the tab. Using form scripting, you can detect and set the expanded or collapsed state of the tab by using the getDisplayState and setDisplayState methods respectively. Tabs have a TabStateChange event that occurs whenever the display state of the tab changes. For more information, see Tab TabStateChange Event.
- Web Resource
- The Web resource element displays a form enabled Web resource to be displayed in the page. A form-enabled Web resource includes Web Page (HTML) Web Resources, Image (JPG, PNG, GIF, ICO) Web Resources, or Silverlight (XAP) Web Resources. An HTML Web resource is like an IFRAME except that the target of the control is always a Web resource, which does not support the OnReadyStateComplete event. Image and Silverlight Web resources are embedded directly in the form. The Web resource also has a property to pass custom parameter data. When the Web resource represents an image, there are properties to set the alignment and size of the image. You can include a Silverlight Web resource directly in a form. If you add an HTML Web resource that contains a Silverlight Web resource inside of it you must uncheck the restrict cross frame checkbox in the HTML Web resource properties dialog box Parameters passed to a Web resource are the same as those passed to an IFRAME but also some additional parameters. For more information, see <parameters> (FormXml) and Sample: Pass Multiple Values to a Web Resource Through the Data Parameter.
ReferenceForm XML Schema
ConceptsDesign Considerations for Different Form Presentations
Create New Entity Forms
Manage Role Based Forms
Change Form Navigation
SystemForm (System Dashboard) Entity Messages and Methods
SystemForm (System Dashboard) Entity Metadata
SystemForm (System Dashboard) Entity OptionSet Attribute Metadata
Other ResourcesCustomize Microsoft Dynamics CRM
Form XML Reference
Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online
Send comments about this topic to Microsoft.
© 2012 Microsoft Corporation. All rights reserved.