Skip to content

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

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.

ParameterTypeDescription
screenScreenDefinition<P, {}>The Screen to open, from This.$Screens.<ScreenName>. A Screen of another Module is opened under its qualified name <ModuleId>.<ScreenName>.
paramsPValues for the Screen’s path parameter variables. Pass {} if the Screen has none.
optionsScreenNavigationOptionsOptional. Navigation options.

ScreenNavigationOptions fields

FieldTypeRequiredDescription
askIfDirtyFormbooleanOptionalIf 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(steps?: number): void;

Goes back in the browser history, like the browser’s back button.

ParameterTypeDescription
stepsnumberOptional. Number of history entries to go back. Default: 1.

Returns: void · Availability: Client

navigateForward(steps?: number): void;

Goes forward in the browser history, like the browser’s forward button.

ParameterTypeDescription
stepsnumberOptional. Number of history entries to go forward. Default: 1.

Returns: void · Availability: Client

openUrl(url: string, inNewWindow: boolean | string): void;

Opens a URL, either in the current window or in a new one.

ParameterTypeDescription
urlstringThe URL to open.
inNewWindowboolean | stringfalse 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<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.

ParameterTypeDescription
screenScreenDefinition<P, I, O>The Screen to show in the dialog, from This.$Screens.<ScreenName>.
dataP & IValues for the Screen’s input variables.
closeOnOutputstringName of a Screen output. When the dialog Screen triggers this output, the dialog closes and the promise resolves with the output’s data.
optionsScreenDialogOptionsOptional. Size, position and behaviour of the dialog.

ScreenDialogOptions fields

FieldTypeRequiredDescription
disableClosebooleanOptionalIf true, the End user can’t close the dialog with the Escape key or by clicking outside it.
hasBackdropbooleanOptionalWhether a backdrop covers the page behind the dialog.
heightstringOptionalHeight of the dialog, as a CSS value such as '400px'.
widthstringOptionalWidth of the dialog, as a CSS value such as '600px'.
maxHeightstring | numberOptionalMaximum height. A number is in pixels.
minHeightstring | numberOptionalMinimum height. A number is in pixels.
maxWidthstring | numberOptionalMaximum width. A number is in pixels.
minWidthstring | numberOptionalMinimum width. A number is in pixels.
panelClassstring | string[]OptionalCSS class or classes added to the dialog panel.
position{ top?: string; bottom?: string; left?: string; right?: string; }OptionalPosition 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(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.

ParameterTypeDescription
resultanyThe value the dialog returns.

Returns: void · Availability: Client

cancelDialog(): void;

Closes the most recently opened dialog that is still open, and resolves its openDialogAndGetResponse() promise with undefined.

Returns: void · Availability: Client

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

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