الملاحظات تحرير

navigateTo (Client API reference)

  • مقالة
  • قراءة خلال 3 دقائق

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. The object definition changes depending on the type of page to navigate to: entity list, entity record, dashboard, HTML web resource, or custom page.
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

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. Invalid parameters will cause an error.

For information about passing parameters to a form, see Set column values using parameters passed to a form and Configure a form to accept custom querystring parameters.
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.
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").

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)