navigateScreen
navigateScreen action allows users to transition to a specific screen or page within the app, facilitating seamless navigation and enhancing user interaction with different sections of the application.
Like any other action, navigateScreen may be called in YAML or in the JS code.
Properties
Property | Type | Description |
---|---|---|
name | string | Enter the Name or ID of your Screen |
inputs | object | Specify the key/value pairs to pass into the next Screen |
options | object | see properties |
onNavigateBack | action | triggers when users returns back to a screen it previously visited using navigateScreen |
transition | Map | Screen transition , Screen transition example |
Screen Transition
Animate screen transition from one to another.
Property | Type | Description |
---|---|---|
type | string | transition type |
alignment | string | transition alignment |
duration | integer | duration of transition in millisecond |
transition-type
name |
---|
fade |
rightToLeft |
leftToRight |
topToBottom |
bottomToTop |
scale |
rotate |
size |
rightToLeftWithFade |
leftToRightWithFade |
leftToRightPop |
rightToLeftPop |
topToBottomPop |
bottomToTopPop |
transition-alignment
name |
---|
topLeft |
topCenter |
topRight |
centerLeft |
center |
centerRight |
bottomLeft |
bottomCenter |
bottomRight |
properties-options
Property | Type | Description |
---|---|---|
replaceCurrentScreen | boolean | If true, the new screen will replace the current screen on the navigation history. Navigating back from the new screen will skip the current screen. |
clearAllScreens | boolean | If true, clear out all existing screens in the navigation history. This is useful when navigating to a Logout or similar page where users should not be able to go back to the prior screens. |
closeToasts | boolean | Determines whether toasts (temporary messages) should be closed automatically. Default is true . |
Example: Calling navigateScreen - Detailed Examples for YAML and JS
View:
title: "Action: navigateScreen"
styles:
scrollableView: true
Column:
styles: { gap: 16, padding: 24 }
children:
- Markdown:
text: You can navigate to another screen using action `navigateScreen`
- Button:
label: Navigate to Home
onTap:
navigateScreen:
name: Home
- Markdown:
text: You can navigateScreen from code blocks using `ensemble.navigateScreen('ScreenName');`.
- Button:
label: Navigate to Home using code
onTap:
executeCode:
body: |
//@code
ensemble.navigateScreen('Home');
- Divider
- Markdown:
text: |
#### Pass inputs
You have the option of passing inputs to the target screen.
- TextInput:
id: messageInput
label: Message to pass
value: Hello there
- Button:
label: Navigate and pass inputs
onTap:
navigateScreen:
name: "Action: navigateScreen inputs demo"
inputs:
message: ${messageInput.value}
- Button:
label: Navigate and pass inputs using code
onTap:
executeCode:
body: |
//@code
ensemble.navigateScreen({
"name": "Action: navigateScreen inputs demo",
"inputs": {
"message": messageInput.value
}
});
- Divider
- Markdown:
text: |
#### options: clearAllScreens
By default, Ensemble retains your previous screens. On browser, user can press back button and get the previous view.
When you need to remove all the previous screens from the history stack, as in a logout scenario, use `clearAllScreens: true`.
- Button:
label: Navigate and clear all screen history
onTap:
navigateScreen:
name: Home
options:
clearAllScreens: true
- Divider
- Markdown:
text: |
#### options: replaceCurrentScreen
Sometimes when navigating to a new screen, you may not want the user to go back to the current screen. An example is after logging in, hitting back should not take the user back to the login screen. Use the flag `replaceCurrentScreen: true` to remove the current screen from the history stack.
- Button:
label: Navigate to new screen and replace the current screen
onTap:
navigateScreen:
name: Home
options:
replaceCurrentScreen: true
You can try complete example here (opens in a new tab)
Example: Calling navigateScreen in Javascript
//navigating to a screen without any options
ensemble.navigateScreen('My Screen');
//navigating to a screen with options
ensemble.navigateScreen({name: 'My Screen',options: {replaceCurrentScreen: true}}
onNavigateBack
We can also make use of onNavigateBack in our navigateScreen action to achieve certain goals like calling an API when returning to screen, updating something which was modified on visited screen etc.
Example Below is only a snippet from a use case where we can perform any action inside the onNavigateBack event. We can call an API or update any particular parameter we want
navigateScreen:
name: "${booking.completion_status == 'confirmed' ? 'ConfirmedTrip' : 'ConfirmTripRequest'}"
inputs:
booking: ${booking}
onNavigateBack: |-
ensemble.debug("got back")
Another example where using in context of a button we are updating certain local storage items inside the context of the onNavigateBack
- Button:
label: Categories
styles:
outline: true
padding: 0
labelStyle:
fontSize: 12
color: 4288060321
endingIcon:
name: chevron_right
color: 4288060321
size: 16
onTap: null
navigateScreen:
name: Spending
onNavigateBack: |-
//@code
getCategoriesAggregate(ensemble.storage.timeSpan);
Note: here we are chaining actions onTap -> navigateScreen -> onNavigateBack etc. Also getCategories(...) is a function used to update certain local storage items.
- We can also pass data from the visited screen to current screen using navigateBack action. let see an example for that as well.
View:
header:
title: Home
body:
Button:
label: Checkout Ensemble Kitchen Sink
onTap:
navigateBack:
data: # optional, can be simple or complex
var1: 1
var2: "s t r i n g"
on visited screen using navigateBack we pass certain variables which can be accessed on previous screen using onNavigateBack event.
View:
header:
title: Home
body:
Button:
label: Checkout Ensemble Kitchen Sink
onTap:
navigateScreen:
name: nextScreen
onNavigateBack: |-
//@code
console.log("navigated back to main screen");
console.log(event.data);
Screen Transition Example
View:
header:
title: Screen Transition
body:
Button:
label: Navigate transition
onTap:
navigateScreen:
name: <write-your-screen-name-here>
transition:
type: rotate
duration: 1000
alignment: center