dialog
The
dialog
UI component appears as a blocking overlay that provides information or confirms destructive behavior. They often prompt users to make a decision.Version compatibility
dialog
was introduced in version 4.58.0 of the JourneyApps Runtime.This
dialog
component is generated from the view's XML. For dialogs triggered from JavaScript/TypeScript, see the journey.dialog documentation.Known limitation
A
dialog
can currently not be shown upon entering a view (e.g. by calling it from the init()
or resume()
function).There are 3 main use cases for
dialog
. These are described in more detail below.- 1.
- 2.
- 3.
A simple
dialog
displays information to the user and does not require the user to make a decision, thus can be dismissed by selecting the primary button, hitting the Esc
key or back button.Tip
Use simple dialogs sparingly as they are interruptive. Rather, less obtrusive notifications can be used.
Example
main.view.xml
<dialog id="success-dialog" title="Success" subtext="You have been successfully enrolled."/>
main.js
function onEnrollment() {
component.dialog({id: "success-dialog"}).show();
}

A confirmation
dialog
gives the user the ability to provide final confirmation of a decision before committing to it. If the user confirms a choice, it’s carried out. Otherwise, the user can dismiss the dialog by selecting the secondary button.Example
main.view.xml
<dialog id="reset-settings" title="Reset settings?" submit-text="Reset"
subtext="Would you like to reset your app to its default settings"
on-submit="$:resetSettings(true)" on-cancel="$:resetSettings(false)"/>
main.js
function showResetSettings() {
component.dialog({id: "reset-settings"}).show();
}
function resetSettings(ok){
if (ok) {
// Logic here
} else {
// Other logic here
}
}

A composition dialogs allows developers to embed other UI components inside it, therefore offering a wide range of input options.
To embed a UI component to the
dialog
, add it inside a body
tag. Refer to the syntax for more detail.Example:
main.view.xml
<!-- XML -->
<dialog id="dialog-input" title="Stock: {$:getStockTitle()}">
<body>
<text-input label="Capture stock Qty" bind="stock" required="true" />
</body>
<button-group>
<button label="Cancel" color="negative" on-press="$:onCancel()" validate="false"/>
<button label="Save" on-press="$:onSubmit()" validate="true"/>
</button-group>
</dialog>
main.js
// JS
function getStockTitle(){
return view.cur_item.name;
}
function onCancel() {
// Logic for when the user selects Cancel
}
function onSubmit() {
// Logic for when the user selects Save
}

Required
<dialog id="task-complete" title="Task complete" />
The
id
attribute is required to target a particular dialog to call show()
or hide()
on it.<dialog id="task-complete" title="Task complete"/>
function onTaskComplete() {
component.dialog({id: "task-complete"}).show();
}
function onTaskUploadFail() {
component.dialog({id: "task-complete"}).hide();
}
See also:
Optional
Default: unset
<dialog id="login-dialog" title="Login successful"/>
A
dialog
's title
communicates its purpose to the user.Titles should:
- Contain a brief, clear statement or question
- Summarize the dialog's content
- Avoid the following:
- apologies (“Sorry for the interruption”)
- alarm (“Warning!”)
- ambiguity (“Are you sure?”)
<dialog id="task-complete" title="Task complete" />
function onTaskComplete() {
component.dialog({id: "task-complete"}).show();
}
Optional
Type:
boolean
Default:
true
<dialog id="discard-dialog" title="Unsaved changes"
subtext="You have unsaved changes, are you sure you want to discard?" auto-hide="false" >
By default the dialog will automatically hide when the user selects any of its buttons. To override this behavior, specify
auto-hide="false"
.When specifying
auto-hide="false"
, you are responsible for hiding the dialog using component.dialog({id:'myId'}).hide()
.<dialog id="tc-dialog" title="Terms and conditions" subtext="Do you agree to these Ts and Cs?"
auto-hide="false"
on-submit="$:agree(true)" on-cancel="$:agree(false)"
submit-text="Agree" cancel-text="Disagree">
function showTsAndCs() {
component.dialog({id: "tc-dialog"}).show();
}
function agree(predicate){
if (predicate){
component.dialog({id: "tc-dialog"}).hide();
// Other success logic here
} else {
var ok = confirmDialog('By not agreeing to these terms, you void your warranty.\n
Are you sure?');
if (ok) {
component.dialog({id: "tc-dialog"}).hide();
// Other logic here
}
// The dialog will not hide and the user may change their selection
}
}
Optional
Default: unset
Triggered when: The secondary button on a confirmation dialog is selected.
Event parameter: Empty by default. Can be a user-defined variable or field.
Return value:
undefined
, or the user-defined variable or fieldmain.view.xml
<dialog id="use-location" title="Use location Service?" subtext="The app requires access to your location"
on-submit="$:useLocation(true)" on-cancel="$:useLocation(false)"/>
main.js
function askLocation() {
component.dialog({id: "use-location"}).show();
}
function useLocation(ok){
if (ok) {
// Logic for on-submit here
} else {
// Logic for on-cancel here
}
}
Specifying
on-cancel
will change the dialog to a confirmation dialog, with a secondary and primary button.Optional
Default: unset
Triggered when: The primary button (for simple dialogs) or submit button (for multi-button dialogs) on a dialog is selected.
Event parameter: Empty by default. Can be a user-defined variable or field.
Return value:
undefined
, or the user-defined variable or field.on-submit
will not trigger when a simple dialog is dismissable by selecting on the backdrop or the user pressing Esc key.Optional
Type:
string
Default: The default submit (primary) button text is
OK
and for confirmation dialogs the default cancel button text is Cancel
. These will be translated by default.<dialog id="tc-dialog" title="Terms and agreements" subtext="Do you agree to these Ts and Cs?" submit-text="Agree" cancel-text="Disagree">
The
submit-text
and cancel-text
attributes allows for changing the default text on the dialog.Be as specific as possible with button copy to avoid ambiguity. Instead of "Yes", rather repeat the action that a button will trigger - for example "Discard", "Save" or "Reset"
<dialog id="tc-dialog" title="Terms and agreements" subtext="Do you agree to these Ts and Cs?"
on-submit="$:agree(true)" on-cancel="$:agree(false)"
submit-text="Agree" cancel-text="Disagree">
function showTsAndCs() {
component.dialog({id: "tc-dialog"}).show();
}
function agree(ok){
if (ok) {
// Logic here
} else {
// Other logic here
}
}
Optional
Type:
string
Default: unset
<dialog
id="task-added"
title="Job added"
subtext="Your job with job-id:{$:getJobId()}\nwas added successfully"
/>
Subtext provides more detail to the user about the purpose of the dialog. The
subtext
attribute can be a format string and it also supports newline characters.<dialog id="task-added" title="Job added" subtext="Your job with job-id:{$:getJobId()}\nwas added successfully"/>
function onTaskAdded() {
component.dialog({id: "task-added"}).show();
}
function getJobId() {
return view.currentJob.id_code;
}
The following component methods are available when an
id
is assigned to the component and component.dialog({id:'my-id'})
is called from JS/TS:Programmatically scroll until the component is visible in the view.
Last modified 9mo ago