Skip to main content
This document describes how to programmatically navigate to pages, fields, table/collection rows, and individual cells within a form using the goto API on DocumentEditor.

​
Overview

The goto method enables programmatic navigation to specific locations within a form. This is useful for:
  • Guiding users to required fields after validation
  • Implementing custom navigation flows
  • Deep linking to specific form sections
  • Auto-scrolling to specific fields
  • Opening a specific table or collection row in its row form (modal)
  • Focusing a specific cell within a table or collection row

​
Path-Based Navigation

Navigate using a slash-separated path string. Up to four segments are supported. 
// Navigate to a page
editor.goto("page_123")

// Navigate to a field on a page
editor.goto("page_123/fieldPos_456")

// Navigate to a row on a table/collection field on a page
editor.goto("page_123/fieldPos_456/row_1")

// Navigate to a row and open the row form modal
editor.goto("page_123/fieldPos_456/row_1", GotoConfig(open = true))


// Navigate to a specific cell in a table or collection row
editor.goto("page_123/fieldPosition_456/row_789/column_012", GotoConfig(open: true, focus: true))
Path FormatDescription
"pageId"Navigate to the top of the specified page
"pageId/fieldPositionId"Navigate to the page and scroll to the field
"pageId/fieldPositionId/rowId"Navigate to the page, scroll to the table/collection field, and select the row. Use GotoConfig(open = true) to also open the row form modal.
"pageId/fieldPositionId/rowId/columnId"Navigate to the page, scroll to the table/collection field, select the row, and target a specific column/cell. Use GotoConfig(focus: true) to auto-focus the cell.
Important: Use fieldPositionId from page.fieldPositions[]._id, not fieldId from document.fields[]._id. Using the wrong ID will cause navigation to fail.
For row-level paths, the field must be a table or collection type. The rowId must match an existing row’s ID in that field’s value; otherwise goto returns .failure. For column-level paths, the columnId must match an existing visible column in the field; otherwise goto returns .failure (but still navigates to the row).

​
GotoConfig

Navigation behavior is configured via GotoConfig. Pass it as the second argument to goto. 
/**
 * Configuration for [DocumentEditor.goto] navigation.
 *
 * @param open If true, automatically open row form when navigating to a row.
 *             Only applies to table/collection row navigation; ignored otherwise.
 * @param animate Whether to animate the scroll. Defaults to true.
 */
class GotoConfig(
    val open: Boolean = false,
    val focus: Boolean = false,
    val animate: Boolean = true
) {
    companion object {
        val default = GotoConfig()
    }
}
PropertyDefaultDescription
openfalseWhen true, automatically opens the row form modal for table/collection rows
animatetrueWhether to animate the scroll
focusfalseWhen true, triggers the SDK’s onFocus event for the target field or cell. For text, number, and barcode cells this also opens the keyboard.
The goto method returns a NavResponse indicating success or failure. 
val response = editor.goto("page_123/fieldPos_456")

when (response) {
    is NavResponse.Success -> {
        // Navigation succeeded - target exists and is visible
    }
    is NavResponse.Failure -> {
        // Navigation failed - target doesn't exist, is hidden, or unsupported
    }
}
ResponseDescription
SuccessThe target exists, is supported, and is visible
FailureThe target does not exist, is hidden, or has an unsupported field type
Failure reasons include:
  • Page does not exist
  • Page is hidden (due to conditional logic)
  • Field position does not exist
  • Field is hidden (due to conditional logic)
  • Field type is unsupported (file, unknown)
  • Row is hidden
  • Row does not exist
  • Column is hidden
  • Column does not exist

​
Page Change Events

Page changes triggered by goto() are emitted through the onBlur and onFocus callbacks. When the user navigates from one page to another (either via goto() or manual navigation), the callbacks receive a ComponentEvent.PageEvent: 
Form(
    editor = editor,
    onBlur = { event ->
        if (event is ComponentEvent.PageEvent) {
            // User left this page
            println("Left page: ${event.pageId}")
        }
    },
    onFocus = { event ->
        if (event is ComponentEvent.PageEvent) {
            // User arrived at this page
            println("Arrived at page: ${event.pageId}")
        }
    }
)
EventTrigger
onBlur with PageEventEmitted when navigating away from a page
onFocus with PageEventEmitted when navigating to a page
PageEvent Properties:
PropertyTypeDescription
pagePageThe page object that gained or lost focus
pageIdStringThe page ID