Navigation - Joyfill Documentation

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

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 Format	Description
`"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()
    }
}

Property	Default	Description
`open`	`false`	When `true`, automatically opens the row form modal for table/collection rows
`animate`	`true`	Whether to animate the scroll
`focus`	`false`	When `true`, triggers the SDK’s `onFocus` event for the target field or cell. For text, number, and barcode cells this also opens the keyboard.

NavResponse

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
    }
}

Response	Description
`Success`	The target exists, is supported, and is visible
`Failure`	The 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}")
        }
    }
)

Event	Trigger
`onBlur` with `PageEvent`	Emitted when navigating away from a page
`onFocus` with `PageEvent`	Emitted when navigating to a page

PageEvent Properties:

Property	Type	Description
`page`	`Page`	The page object that gained or lost focus
`pageId`	`String`	The page ID

​Overview

​Path-Based Navigation

​GotoConfig

​NavResponse

​Page Change Events

Overview

Path-Based Navigation

GotoConfig

NavResponse

Page Change Events