navigateTo (Client API reference)
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 |
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 asavedEntityReference
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
}
);
Related articles
Xrm.Navigation
Navigating to and from a custom page (preview)