navigateTo (Client API reference)

Artigo
11/30/2022

Navigates to the specified table list, table record, HTML web resource, or custom page.

Note

This method is supported only on Unified Interface.

Syntax

Xrm.Navigation.navigateTo(pageInput,navigationOptions).then(successCallback,errorCallback);

Parameters

Name	Type	Required	Description
pageInput	Object	Yes	Input about the page to navigate to. See pageInput parameter
navigationOptions	Object	No	Options for navigating to a page: whether to open inline or in a dialog. If you don't specify this parameter, page is opened inline by default.
`successCallback`	function	No	A function to execute on successful navigation to the page when navigating inline and on closing the dialog when navigating to a dialog.
`errorCallback`	Function	No	A function to execute when the operation fails.

pageInput parameter

The object definition changes depending on the type of page to navigate to: entity list, entity record, dashboard, HTML web resource, or custom page.

Entity list

The entity list object contains the following values.

Name	Type	Description
`pageType`	String	Specify `entitylist`.
`entityName`	String	The logical name of the table to load in the list control.
`viewId`	String	(Optional) The ID of the view to load. If you don't specify it, navigates to the default main view for the table.
`viewType`	String	(Optional) Type of view to load. Specify `savedquery` or `userquery`.

Entity record

The entity record object contains the following values.

Name	Type	Description
`pageType`	String	Specify `entityrecord`.
`entityName`	String	Logical name of the table to display the form for.
`entityId`	String	(Optional) ID of the table record to display the form for. If you don't specify this value, the form will be opened in create mode.
`createFromEntity`	Lookup	(Optional) Designates a record that will provide default values based on mapped column values. The lookup object has the following String properties: entityType, id, and name (optional).
`data`	Object	(Optional) A dictionary object that passes extra parameters to the form. The parameters can be table columns with default values that are set on new forms (see Set column values using parameters passed to a form), or custom parameters that are accessed on the form using `formContext.data.attributes` (see Configure a form to accept custom querystring parameters, and formContext.data). Invalid parameters will cause an error.
`formId`	String	(Optional) ID of the form instance to be displayed.
`isCrossEntityNavigate`	Boolean	(Optional) Indicates whether the form is navigated to from a different table using cross-table business process flow.
`isOfflineSyncError`	Boolean	(Optional) Indicates whether there are any offline sync errors.
`processId`	String	(Optional) ID of the business process to be displayed on the form.
`processInstanceId`	String	(Optional) ID of the business process instance to be displayed on the form.
`relationship`	Object	(Optional) Define a relationship object to display the related records on the form. See relationship.
`selectedStageId`	String	(Optional) ID of the selected stage in business process instance.
`tabName`	String	(Optional) Sets the focus on the tab of the form.

Relationship object

The relationship object, used in the Entity record, contains the following values.

Name	Type	Description
`attributeName`	String	Name of the column used for relationship.
`name`	String	Name of the relationship.
`navigationPropertyName`	String	Name of the navigation property for this relationship.
`relationshipType`	Number	Relationship type. Specify one of the following values: 0:OneToMany, 1:ManyToMany.
`roleType`	Number	Role type in relationship. Specify one of the following values: 1:Referencing, 2:AssociationEntity.

Dashboard

The dashboard object contains the following values.

Name	Type	Description
`pageType`	String	Specify `dashboard`.
`dashboardId`	String	The ID of the dashboard to load. If you don't specify the ID, navigates to the default dashboard.

HTML web resource

The HTML web resource object contains the following values.

Name	Type	Description
`pageType`	String	Specify `webresource`.
`webresourceName`	String	The name of the web resource to load.
`data`	String	(Optional) The data to pass to the web resource.

Custom page

The Custom page object contains the following values.

Name	Type	Description
`pageType`	String	Specify `custom`.
`name`	String	The logical name of the custom page to open.
`entityName`	String	(Optional) The logical name of the table to be made available in the custom page via `Param("entityName")`.
`recordId`	String	(Optional) ID of the table record to be made available in the custom page via `Param("recordId")`.

navigationOptions parameter

The navigationOptions object contains the following values.

Name	Type	Description
`target`	Number	Specify `1` to open the page inline; `2` to open the page in a dialog. Also, rest of the values (width, height, and position) are valid only if you have specified 2 in this value (open page in a dialog). Note: Entity lists can only be opened inline; entity records and web resources can be opened either inline or in a dialog.
`width`	Number or Object	(Optional) The width of dialog. To specify the width in pixels, just type a numeric value. To specify the width in percentage, specify an object of type SizeValue with the following properties: - `value`: The numerical value of type Number. - `unit`: The unit of measurement of type String. Specify `%` or `px`. Default value is `px`.
`height`	Number or Object	(Optional) The height of dialog. To specify the height in pixels, just type a numeric value. To specify the width in percentage, specify an object of type SizeValue with the following properties: - value: The numerical value of type Number. - unit: The unit of measurement of type String. Specify `%` or `px`. Default value is `px`.
`position`	Number	(Optional) Specify `1` to open the dialog in center; `2` to open the dialog on the far side. Default is `1` (center).
`title`	String	(Optional) The dialog title on top of the center or side dialog.

Return Value

Returns a promise. The value passed when the promise resolves is dependent on the target:

inline: Promise resolves right away, and does not return any value.
dialog: Promise resolves when the dialog is closed. An object is passed only if the pageType = entityRecord and you opened the form in create mode. The object has a savedEntityReference array with the following properties to identify the table record created:
- entityType: The logical name of the table.
- id: A string representation of a GUID value for the record.
- name: The primary column value of the record displayed or created.

Example

Example 1: Open account list

var pageInput = {
    pageType: "entitylist",
    entityName: "account"
};
Xrm.Navigation.navigateTo(pageInput).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Example 2: Open an existing account record within a dialog

var pageInput = {
    pageType: "entityrecord",
    entityName: "account",
    entityId: "5a57f2c3-5672-ea11-a812-000d3a339706" //replace with actual ID
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Example 3: Open an account form in the create mode within a dialog

var pageInput = {
    pageType: "entityrecord",
    entityName: "account"    
};
var navigationOptions = {
    target: 2,
    height: {value: 80, unit:"%"},
    width: {value: 70, unit:"%"},
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success(result) {
            console.log("Record created with ID: " + result.savedEntityReference[0].id + 
            " Name: " + result.savedEntityReference[0].name)
            // Handle dialog closed
    },
    function error() {
            // Handle errors
    }
);

Example 4: Open an HTML web resource in a dialog

var pageInput = {
    pageType: "webresource",
    webresourceName: "new_sample_webresource.htm"
};
var navigationOptions = {
    target: 2,
    width: 500, // value specified in pixel
    height: 400, // value specified in pixel
    position: 1
};
Xrm.Navigation.navigateTo(pageInput, navigationOptions).then(
    function success() {
            // Run code on success
    },
    function error() {
            // Handle errors
    }
);

Xrm.Navigation
Navigating to and from a custom page (preview)

Compartilhar via

navigateTo (Client API reference)

Syntax

Parameters

pageInput parameter

Entity list

Entity record

Relationship object

Dashboard

HTML web resource

Custom page

navigationOptions parameter

Return Value

Example

Example 1: Open account list

Example 2: Open an existing account record within a dialog

Example 3: Open an account form in the create mode within a dialog

Example 4: Open an HTML web resource in a dialog

Comentários

Recursos adicionais

Compartilhar via

navigateTo (Client API reference)

Syntax

Parameters

pageInput parameter

Entity list

Entity record

Relationship object

Dashboard

HTML web resource

Custom page

navigationOptions parameter

Return Value

Example

Example 1: Open account list

Example 2: Open an existing account record within a dialog

Example 3: Open an account form in the create mode within a dialog

Example 4: Open an HTML web resource in a dialog

Related articles

Comentários

Recursos adicionais