Sys.Screen
Sys.Screen navigates the End user’s browser: to another Screen, back and forward in the browser history, or to any URL. It also opens a Screen as a dialog and closes the open dialog with a result.
Screens are passed as screen definitions, which you reach through This.$Screens.<ScreenName> (see Screen).
Availability: Client
Functions
Section titled “Functions”navigateToScreen()
Section titled “navigateToScreen()”navigateToScreen<P extends object>(screen: ScreenDefinition<P, {}>, params: P, options?: ScreenNavigationOptions): void;Opens a Screen in the main window, passing its path parameters as URL query parameters.
| Parameter | Type | Description |
|---|---|---|
screen | ScreenDefinition<P, {}> | The Screen to open, from This.$Screens.<ScreenName>. A Screen of another Module is opened under its qualified name <ModuleId>.<ScreenName>. |
params | P | Values for the Screen’s path parameter variables. Pass {} if the Screen has none. |
options | ScreenNavigationOptions | Optional. Navigation options. |
ScreenNavigationOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
askIfDirtyForm | boolean | Optional | If true, the End user is asked to confirm leaving when a form on the current Screen has unsaved changes. Default: false, which discards unsaved changes without asking. |
Lowgile always reloads the target Screen, even if it is the Screen that is already open.
Returns: void · Availability: Client
navigateBack()
Section titled “navigateBack()”navigateBack(steps?: number): void;Goes back in the browser history, like the browser’s back button.
| Parameter | Type | Description |
|---|---|---|
steps | number | Optional. Number of history entries to go back. Default: 1. |
Returns: void · Availability: Client
navigateForward()
Section titled “navigateForward()”navigateForward(steps?: number): void;Goes forward in the browser history, like the browser’s forward button.
| Parameter | Type | Description |
|---|---|---|
steps | number | Optional. Number of history entries to go forward. Default: 1. |
Returns: void · Availability: Client
openUrl()
Section titled “openUrl()”openUrl(url: string, inNewWindow: boolean | string): void;Opens a URL, either in the current window or in a new one.
| Parameter | Type | Description |
|---|---|---|
url | string | The URL to open. |
inNewWindow | boolean | string | false replaces the current page with the URL. true opens it in a new browser window or tab. A string opens it in the browser window with that name (for example '_blank' or a name of your own), so later calls with the same name reuse that window. |
Returns: void · Availability: Client
openDialogAndGetResponse()
Section titled “openDialogAndGetResponse()”openDialogAndGetResponse<R, P extends object = {}, I extends object = {}, O extends Record<string, any> = Record<string, any>>(screen: ScreenDefinition<P, I, O>, data: P & I, closeOnOutput: string, options?: ScreenDialogOptions): Promise<R>;Opens a Screen as a dialog and waits until the dialog closes.
| Parameter | Type | Description |
|---|---|---|
screen | ScreenDefinition<P, I, O> | The Screen to show in the dialog, from This.$Screens.<ScreenName>. |
data | P & I | Values for the Screen’s input variables. |
closeOnOutput | string | Name of a Screen output. When the dialog Screen triggers this output, the dialog closes and the promise resolves with the output’s data. |
options | ScreenDialogOptions | Optional. Size, position and behaviour of the dialog. |
ScreenDialogOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
disableClose | boolean | Optional | If true, the End user can’t close the dialog with the Escape key or by clicking outside it. |
hasBackdrop | boolean | Optional | Whether a backdrop covers the page behind the dialog. |
height | string | Optional | Height of the dialog, as a CSS value such as '400px'. |
width | string | Optional | Width of the dialog, as a CSS value such as '600px'. |
maxHeight | string | number | Optional | Maximum height. A number is in pixels. |
minHeight | string | number | Optional | Minimum height. A number is in pixels. |
maxWidth | string | number | Optional | Maximum width. A number is in pixels. |
minWidth | string | number | Optional | Minimum width. A number is in pixels. |
panelClass | string | string[] | Optional | CSS class or classes added to the dialog panel. |
position | { top?: string; bottom?: string; left?: string; right?: string; } | Optional | Position of the dialog on the page, as CSS values. By default the dialog is centred. |
The promise resolves with undefined if the dialog closes any other way: through cancelDialog(), the Escape key, or a click outside the dialog. closeDialogAndReturn() resolves it with the value passed to it.
This.$Screens.<ScreenName>.openAsDialog(inputData, outputName, options) does the same and types the result as the data of the named output.
const result = await Sys.Screen.openDialogAndGetResponse( This.$Screens.MyDialogScreen, { myInput: 'some value' }, 'myOutput', { width: '600px', disableClose: true },)if (result !== undefined) { // the dialog triggered myOutput}Note
Only the Screen’s input variables are taken from data. Path parameter values in data are ignored: in a dialog, path parameter variables keep the values of the page behind it.
Returns: Promise<R> · Availability: Client
closeDialogAndReturn()
Section titled “closeDialogAndReturn()”closeDialogAndReturn(result: any): void;Closes the most recently opened dialog that is still open, and resolves its openDialogAndGetResponse() promise with result. If no dialog is open, nothing happens and an error is written to the browser console.
| Parameter | Type | Description |
|---|---|---|
result | any | The value the dialog returns. |
Returns: void · Availability: Client
cancelDialog()
Section titled “cancelDialog()”cancelDialog(): void;Closes the most recently opened dialog that is still open, and resolves its openDialogAndGetResponse() promise with undefined.
Returns: void · Availability: Client
MainScreenClass
Section titled “MainScreenClass”interface MainScreenClass { $canBeMainScreen: true;}Marks a Screen class that can be shown as the main Screen of a page. Every Screen class Lowgile compiles has a static $canBeMainScreen property set to true, so it matches this type. No Sys function takes this type; use it to type your own code.
Availability: Client
DialogScreenClass
Section titled “DialogScreenClass”interface DialogScreenClass { $canBeDialogScreen: true;}Marks a Screen class that can be shown in a dialog. Every Screen class Lowgile compiles has a static $canBeDialogScreen property set to true, so it matches this type. No Sys function takes this type; use it to type your own code.
Availability: Client
Related
Section titled “Related”- Screen
- Sys.App
- Screen concepts
- Sys API overview