Document.goToByIdAsync method (JavaScript API for Office v1.1)

JavaScript API for Office v1.1

Goes to the specified object or location in the document.

Last modified: August 11, 2014

Introduced in Office.js version

1.1

Available in requirement sets

Not in a set

Office.context.document.goToByIdAsync(id, goToType, [,options], callback);

id

Type: string or number

The identifier of the object or location to go to. Required.

goToType

Type: GoToType

The type of the location to go to. Required.

options

Type: object

Specifies the following optional parameters.

asyncContext

Type: array, boolean, null, number, object, string, or undefined

A user-defined item of any type that is returned in the AsyncResult object without being altered. Optional.

callback

Type: function

A function that is invoked when the callback returns, whose only parameter is of type AsyncResult. Optional.

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

In the callback function passed to the goToByIdAsync method, you can use the properties of the AsyncResult object to return the following information.

Property

Use to...

AsyncResult.value

Return the current view.

AsyncResult.status

Determine the success or failure of the operation.

AsyncResult.error

Access an Error object that provides error information if the operation failed.

AsyncResult.asyncContext

Access your user-defined object or value, if you passed one as the asyncContext parameter.

PowerPoint doesn't support the goToByIdAsync method in Master Views.

Go to a binding by id (Word and Excel)

The following example shows how to:

  • Create a table binding using the addFromSelectionAsync method as a sample binding to work with.

  • Specify that binding as the binding to go to.

  • Pass an anonymous callback function that returns the status of the operation to the callback parameter of the goToByIdAsync method.

  • Display the value on the app's page.

function gotoBinding() {
    //Create a new table binding for the selected table.
    Office.context.document.bindings.addFromSelectionAsync("table",{ id: "MyTableBinding" }, function (asyncResult) {
    if (asyncResult.status == "failed") {
              showMessage("Action failed with error: " + asyncResult.error.message);
           }
           else {
              showMessage("Added new binding with type: " + asyncResult.value.type +" and id: " + asyncResult.value.id);
           }
    });

    //Go to binding by id.
    Office.context.document.goToByIdAsync("MyTableBinding", Office.GoToType.Binding, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

Go to a table in a spreadsheet (Excel)

The following example shows how to:

  • Specify a table by name as the table to go to.

  • Pass an anonymous callback function that returns the status of the operation to the callback parameter of the goToByIdAsync method.

  • Display the value on the app's page.

function goToTable() {
    Office.context.document.goToByIdAsync("Table1", Office.GoToType.NamedItem, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

Go to the currently selected slide by id (PowerPoint)

The following example shows how to:

  • Get the id of the currently selected slide using the getSelectedDataAsync method.

  • Specify the returned id as the slide to go to.

  • Pass an anonymous callback function that returns the status of the operation to the callback parameter of the goToByIdAsync method.

  • Display the value on the app's page.

function gotoSelectedSlide() {
    //Get currently selected slide's id
    Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            var firstSlideId = slideRange.slides[0].id;
            showMessage(JSON.stringify(asyncResult.value));
        }
    });
    //Go to slide by id.
    Office.context.document.goToByIdAsync(firstSlideId, Office.GoToType.Slide, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

Go to slide by index (PowerPoint)

The following example shows how to:

  • Specify the index of the first, last, previous, or next slide to go to.

  • Pass an anonymous callback function that returns the status of the operation to the callback parameter of the goToByIdAsync method.

  • Display the value on the app's page.

function goToSlideByIndex() {
    var goToFirst = Office.Index.First;
    var goToLast = Office.Index.Last;
    var goToPrevious = Office.Index.Previous;
    var goToNext = Office.Index.Next;

    Office.context.document.goToByIdAsync(goToNext, Office.GoToType.Index, function (asyncResult) {
        if (asyncResult.status == "failed") {
            showMessage("Action failed with error: " + asyncResult.error.message);
        }
        else {
            showMessage("Navigation successful");
        }
    });
}

App types

Content apps, Task pane apps

Supported clients

Excel 2013 SP1, Excel Online, Word 2013 SP1, PowerPoint 2013 SP1

Library

Office.js

Namespace

Office

Show:
© 2014 Microsoft