Xrm.Page.ui quickForms (client-side reference)

Article
12/12/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The Xrm.Page.ui.quickForms collection provides methods to access all the quick view controls and its constituent controls on the Microsoft Dynamics 365 forms when using the new form rendering engine (also called "turbo forms"). A quick view control is a quick view form added to a main form in Microsoft Dynamics 365 that enables you to view information about a related entity record within the main form. Data in constituent controls in a quick view control cannot be edited. For more information about quick view controls and quick view forms, see TechNet: Create and edit quick view forms

Note

This feature was introduced in CRM Online 2016 Update 1 and CRM 2016 Service Pack 1 (on-premises).

This topic is only applicable if you are using the new forms rendering engine in Dynamics 365. If you are using the legacy form rendering (also called "refresh forms") in Dynamics 365, you can access the quick view control and its constituent controls using the standard control object; see Xrm.Page.ui control (client-side reference).

Important

With the deprecation announcement of the legacy forms in Dynamics 365, you must soon plan to use the new forms rendering engine if you are using the legacy form rendering. As there is a difference between how you access the quick view controls in the legacy and new forms rendering, you must update and test your existing code targeting the quick view controls to use the methods described in this topic when you switch to the new form rendering engine. For more information about the deprecation of legacy form rendering, see Removal of legacy form rendering option

In This Topic

quickForms collection methods

quickForms object methods

quickForms collection methods

The quickForms collection provides access to all the quick view controls on a form. The quickForms collection supports all the standard methods of the collections in Dynamics 365. See Collections (client-side reference)

The following example demonstrates how to retrieve a quick view control instance in the quickForms collection using the get method by specifying either the index value (integer) or name (string) of the quick view control instance as the argument.

quickViewControl = Xrm.Page.ui.quickForms.get(arg)

quickForms object methods

A quickForms object represents a quick view control instance. The following methods are supported for the quick view control instances on a form.

getControl
getControlType
getName
getParent
getVisible
Label methods
isLoaded
refresh

getControl

Gets the constituent controls in a quick view control.

quickViewControl.getControl()

You can access a single control in the constituent controls collection by passing an argument as either the name or the index value of the constituent control in a quick view control. For example: quickViewControl.getControl("firstname") or quickViewControl.getControl(0)

Return Value
Type: Object collection if you use the method without any argument; object if you use the method with an argument.
Remarks
After you have retrieved a constituent control in a quick view control, you can use any of the methods supported for a Dynamics 365 control on the constituent control that does not alter the constituent control data. This is because constituent controls in a quick view control are read only. For example, you can use: quickViewControl.getControl(0).getAttribute() For more information about methods supported for a Dynamics 365 control, see Xrm.Page.ui control (client-side reference)

Important

The getAttribute or any data related methods on a constituent control might not work on the main form OnLoad event because the quick view form that its bound to might not have loaded completely when the main form has loaded. You must use the isLoaded method for the quick view control instance to help you determine if the bounded quick view form has loaded completely. More information: isLoaded

Also, the way you retrieve constituent controls in a quick view control on forms using the new form rendering engine is different from the legacy forms. So, if you are using legacy forms and have code targeting constituent controls in a quick view control, you must update your code when you decide to use the new form rendering engine in Dynamics 365.

getControlType

Returns a string value that categorizes quick view controls.

quickViewControl.getControlType()

For a quick view control, the method returns quickform.

For a constituent control in a quick view control, the method returns the actual category of the control. For more information about possible return values, see getControlType.

getName

Returns the name assigned to the quick view control.

quickViewControl.getName()

Return Value
Type: String. The name of the quick view control.

getParent

Returns a reference to the section object that contains the control.

Control Types: all.

quickViewControl.getParent()

Return Value
Type:Xrm.Page.ui section (client-side reference) object.

getVisible

Returns a value that indicates whether the quick view control is currently visible.

Note

If the containing section or tab for this control isn’t visible, this method can still return true. To make certain that the control is actually visible; you need to also check the visibility of the containing elements.

quickViewControl.getVisible()

Return Value
Type: Boolean. True if the quick view control is visible; otherwise, false.

Label methods

Get or change the label for a quick view control using the getLabel and setLabel methods.

getLabel

Returns the label for the quick view control.

quickViewControl.getLabel()

Return Value
Type: String. The label of the quick view control.

setLabel

Sets the label for the quick view control.

quickViewControl.setLabel("label")

Arguments
Type: String. The new label of the quick view control.

isLoaded

Returns whether the data binding for the constituent controls in a quick view control is complete.

quickViewControl.isLoaded()

Return Value
Type: Boolean. True is the data binding for a constituent control is complete, otherwise false.
Remarks
The data binding for the constituent controls in a quick view control may not be complete during the main form OnLoad event because the quick view form that the control is bound to may not have loaded completely. As a result, using the getAttribute or any data-related methods on a constituent control might not work. The isLoaded method for the quick view control helps determine the data binding status for constituent controls in a quick view control.

The following sample code demonstrates how you can use the isLoaded method to check the binding status, and then retrieve the value of the attribute that a constituent control in a quick view control is bound to.

function getAttributeValue() {
    var quickViewControl = Xrm.Page.ui.quickForms.get("<QuickViewControlName>");
    if (quickViewControl != undefined)
    {
        if (quickViewControl.isLoaded())
        {
            // Access the value of the attribute bound to the constituent control
            var myValue = quickViewControl.getControl(0).getAttribute().getValue();
            console.log(myValue);
            return;
        }
        else
        {
            // Wait for some time and check again
            setTimeout(getAttributeValue, 10);
        }
    }
    else
    {
        console.log("No data to display in the quick view control.");
        return;
    }    
}

refresh

Refreshes the data displayed in a quick view control.

quickViewControl.refresh()

Xrm.Page.ui quickForms (client-side reference)

In This Topic

quickForms collection methods

quickForms object methods

getControl

getControlType

getName

getParent

getVisible

Label methods

getLabel

setLabel

isLoaded

refresh

See Also

Additional resources