Client API

Everything an app calls at runtime comes through one interface: z2ui5_if_client, handed to the app as client on every roundtrip. This page is that interface, generated from its source at the release named in the nav bar: every method with its parameters, types and defaults, every cs_* constant structure, and the documentation written in the source itself. What is printed here is what your install has — not what main already promises.

The interface is deliberately small and deliberately stable: obsolete methods stay in it so existing apps keep compiling, and they are marked as such below, each one naming its replacement. How the pieces fit together — the lifecycle, binding, events — is what the Tutorial and the Cookbook explain; this page is the contract they explain it against.

Generated from z2ui5_if_client at release 1.143.0 — 37 methods, 4 constant structures. The same reference as one JSON document: client-api.json.

App lifecycle

check_on_event

Parameter	Type	Default	Description
val	clike	optional

Returns abap_bool.

check_on_init

Returns abap_bool.

check_on_navigated

Returns abap_bool.

Main view

view_destroy

view_display

Display the MAIN view. A new main view is a new screen, so an open popup and popover go with it - re-open one in the same roundtrip if it is meant to survive ( the frontend builds MAIN first, then the popup ).

Parameter	Type	Default	Description
val	clike
switch_default_model_anno_uri	clike	optional
switch_default_model_path	clike	optional

view_model_update obsolete

obsolete - does NOTHING. An event round-trip that changes bound data pushes the model AUTOMATICALLY: the framework compares the model state before and after main( ) and, when it differs, sends it to every open view slot (see z2ui5_cl_ui5_handler=>main_end). A handler can therefore no longer render stale by forgetting a call, and there is nothing left for this method to do. It stays in the interface so existing apps keep compiling - remove the calls at your leisure.

Nested views

nest_view_display

Parameter	Type	Default	Description
val	clike
id	clike
method_insert	clike
method_destroy	clike	optional

nest_view_destroy

nest_view_model_update obsolete

obsolete - does NOTHING, see view_model_update. A nested view inherits the MAIN view's model anyway, and that model is pushed automatically

nest2_view_display

Parameter	Type	Default	Description
val	clike
id	clike
method_insert	clike
method_destroy	clike	optional

nest2_view_destroy

nest2_view_model_update obsolete

obsolete - does NOTHING, see view_model_update. A nested view inherits the MAIN view's model anyway, and that model is pushed automatically

Popups and popovers

popup_display

Parameter	Type	Default	Description
val	clike

popup_model_update obsolete

obsolete - does NOTHING, see view_model_update. The automatic push reaches the POPUP slot too, so an open popup refreshes on its own

popup_destroy

popover_model_update obsolete

obsolete - does NOTHING, see view_model_update. The automatic push reaches the POPOVER slot too, so an open popover refreshes on its own

popover_display

Parameter	Type	Default	Description
xml	clike
by_id	clike

popover_destroy

Data binding

_bind

Parameter	Type	Default	Description
val	data
path	abap_bool	abap_false
view	clike	cs_view-main	obsolete - inactive, not passed on internally
custom_mapper	REF TO z2ui5_if_ajson_mapping	optional	obsolete - still evaluated, but do not use in new code. Both hand an app a reference to the bundled AJSON library (src/00/01), which is a MIRRORED copy of an external project, not a contract this framework owns: an app implementing z2ui5_if_ajson_mapping / _filter binds itself to whatever that mirror looks like today. Everything they were reached for has a declarative counterpart on this method now - omit_initial / omit_initial_paths drop initial fields, json splices a JSON node - and the ABAP side can shape the value before it is bound
custom_filter	REF TO z2ui5_if_ajson_filter	optional
tab	data	optional
tab_index	i	optional
switch_default_model	abap_bool	abap_false
omit_initial	abap_bool	abap_false	keep INITIAL fields out of the serialized model instead of sending them as `` / 0. An ABAP field is never absent - it is initial - so by default every field reaches the client as an explicit value, which overrides the UI5 property default the original view relies on (and an enum-typed property rejects the empty string outright). Set it when a bound template's rows fill different subsets of the same properties.
omit_initial_paths	string_table	optional	the same omission SCOPED to the listed fields (upper-cased column names, the last path segment). Use it when the blanket flag is too coarse: an abap_false that MUST reach the client is itself initial, so omit_initial would drop it and the control would fall back to its own default - list the numeric/enum columns instead and leave the booleans.
json	abap_bool	abap_false	the bound string already CONTAINS JSON - splice it into the model as a JSON node instead of sending it as a quoted string. For a control property that must receive an OBJECT, which no typed ABAP value can be (a sap.ui.integration Card manifest: its keys sap.app/sap.card are not valid ABAP field names, and a string is read as a manifest URL). Outbound only - see z2ui5_cl_ui5_srv_model.

Returns string.

_bind_edit obsolete

obsolete - alias of _bind with identical behaviour, please use _bind. custom_mapper_back / custom_filter_back are still accepted for source compatibility but are no longer evaluated.

Parameter	Type	Default	Description
val	data
path	abap_bool	abap_false
view	clike	cs_view-main	obsolete - inactive, not passed on internally
custom_mapper	REF TO z2ui5_if_ajson_mapping	optional
custom_mapper_back	REF TO z2ui5_if_ajson_mapping	optional
custom_filter	REF TO z2ui5_if_ajson_filter	optional
custom_filter_back	REF TO z2ui5_if_ajson_filter	optional
tab	data	optional
tab_index	i	optional
switch_default_model	abap_bool	abap_false

Returns string.

Events and frontend actions

_event

Register a backend event and return the handler expression for a view attribute (press = client->_event( SAVE )). s_ctrl carries the optional event flags: check_allow_multi_req sends the event while another roundtrip is still running, check_prevent_default cancels the control's built-in default for this event (oEvent.preventDefault(), e.g. a sap.tnt NavigationListItem press that must not select the item) before the roundtrip - the event is still sent, so the backend stays in charge of what happens instead. That flag is baked per WIRE at render time; prevent_default_expr is the same veto decided per FIRING - a client expression evaluated when the event fires, so one wire can protect one row/column and let the rest through (${$parameters>/column}.getId().indexOf('COL_DATE') >= 0). It wins over the flag when both are set.

Parameter	Type	Default	Description
val	clike	optional
t_arg	string_table	optional
s_ctrl	z2ui5_if_types=>ty_s_event_control	optional

Preferred parameter: val — a positional call passes it.

Returns string.

_event_client obsolete

obsolete - use follow_up_action( ), which is the same call in the same position now. Since follow_up_action( ) has a RETURNING parameter, a call whose result is CONSUMED - the view-attribute form v = client->follow_up_action( val = ... t_arg = ... ) - takes its IF result IS SUPPLIED branch straight to get_event_client( ), which is this method's entire body: the identical roundtrip-free wire, byte for byte. One method therefore both schedules a frontend action and wires one, and this one is a second name for half of it.

The one difference is follow_up_action( )'s leading CASE, which claims cs_event-set_nav_routing / set_push_state / set_app_state_active before that branch. Those three are backend-side navigation options rather than frontend handlers, so wiring one into a view attribute never dispatched anything here either.

It stays in the interface so existing apps keep compiling - rename the calls at your leisure.

Parameter	Type	Default	Description
val	clike
view	clike	cs_view-main
t_arg	string_table	optional

Returns string.

follow_up_action

Schedule a frontend action to run after the backend response is processed. Two ways to call it: pass a frontend event as val (e.g. cs_event-set_title) with its arguments in t_arg and the framework builds the event call; or pass a raw JavaScript expression as val (without t_arg) to run it as-is. The control/binding calls are frontend events too; their t_arg is positional (an empty argument between filled ones keeps its slot as ): cs_event-control_by_id - call a method on a control resolved by id: t_arg = id, method, params. Any public control method works unless it is on the frontend denylist (methods that would break framework invariants). The named per-aggregation mutators are on the allowed side of that line - addItem, removeItem, removeAllItems, destroyContent - and only the GENERIC reflection variants that take the member name as an argument are denied (addAggregation, removeAllAggregation, setAssociation, ...). The view is passed as the separate view parameter (default cs_view-main resolves the id across all open views; pass cs_view-popup/popover/... to scope the lookup to that view). Two entries are NOT UI5 methods but frontend capabilities in method form: `css` sets ONE whitelisted CSS declaration on the control's own DOM node (t_arg = id, `css`, property, value) - for a value the control has no property for at all, e.g. the width of a sap.m.Page; prefer a bound property wherever one exists. `toggleBy` opens/closes a popup anchored to a control (t_arg = id, `toggleBy`, anchor id). An association setter (setSelectedSection, setSelectedItem) clears the association when its argument is EMPTY. Wherever an argument takes a CONTROL ID, it also takes an aggregation ITEM, addressed positionally as `<id>/<aggregation>/<index>` (`carousel/pages/2`, 0-based). A control cloned from an aggregation template has no id the backend can spell - UI5 mints it from the template id, the parent id and the index, and the parent id carries the view prefix assigned at runtime - so this is the only way to reach one. It is the equivalent of the UI5 controller idiom `oCarousel.setActivePage( oCarousel.getPages()[ i ] )`. A plain id (no slashes) resolves exactly as before. cs_event-control_global - call a whitelisted method on a global object (MESSAGE_TOAST, MESSAGE_BOX, BUSY_INDICATOR, THEMING, POPUP, INVISIBLE_MESSAGE, FORMATTING): t_arg = object, method, params. POPUP-setWithinArea confines every popup to the control whose id is passed (sap.ui.core.Popup.setWithinArea, needs UI5 >= 1.89) instead of to the window; an EMPTY argument releases the restriction again. INVISIBLE_MESSAGE-announce reads a text out to a screen reader without rendering it (sap.ui.core.InvisibleMessage, needs UI5 >= 1.78): t_arg = text, mode (Polite, default, or Assertive). It is a singleton, so there is no control id - this is the only way to announce a change the backend made. FORMATTING-setCustomCurrencies registers currency codes the standard sap.ui.model.type.Currency does not know, or overrides their digit count (sap.ui.core.Formatting, needs UI5 >= 1.120): t_arg = JSON object, e.g. {"BGN4":{"digits":4}}. It REPLACES the whole registration - addCustomCurrency ADDS a single code to it instead (t_arg = code, JSON object). Reaching for the wrong one is silent: an app that registers currencies as it loads more data and calls setCustomCurrencies drops what it registered before, and the symptom is a wrong digit count in a table, never an error. cs_event-smart_variant_init - run the initialise( ) handshake sap.ui.comp variant management needs (a controller would call oSmartVariantManagement.initialise( fnCallback, oPersonalizableControl )). Without it the control keeps no personalizable control, saving a view fails inside sap.ui.fl and stored variants are never loaded: t_arg = SmartVariantManagement id, personalizable control id (optional, default: the first control that registered itself). The action waits for that registration, which the smart controls do once their OData metadata has loaded. cs_event-filter_bar_variant_init - wire a classic sap.ui.comp.filterbar.FilterBar to a SmartVariantManagement: t_arg = SmartVariantManagement id, FilterBar id. A SmartFilterBar knows its own fields and registers itself (see smart_variant_init above); a classic FilterBar does not, so a list report normally hand-writes the same controller boilerplate - registerFetchData / registerApplyData / registerGetFiltersWithValues, addPersonalizableControl( ) with a PersonalizableInfo, and a change handler per filter field that marks the variant as modified. This action does all of it, so saving, selecting and restoring a variant works without a single line of JavaScript. The restored values reach the backend through the binding of the filter fields, no extra roundtrip needed. cs_event-keyboard_shortcut - bind a key combination to a named backend event, the declarative equivalent of a sap.ui.core.CommandExecution shortcut: t_arg = combination, event name. The combination is spelled like the UI5 one (`Ctrl+S`, `Ctrl+Shift+D`, `F2`; ctrl/shift/alt/meta in any order, cmd/command/option/control accepted as aliases). Pressing it fires the event exactly like a button press and suppresses the browser's own default for the combination. Registering the same combination again rebinds it; an empty event name removes it. The registrations belong to the running app and are dropped when another app takes over. An optional THIRD t_arg SCOPES the shortcut: the scoped registration wins while its scope is OPEN and the unscoped one applies otherwise, which is how a UI5 CommandExecution in a Popover's dependents shadows the page-level one for the same command. A scope is either a view slot (cs_view-popover/popup/nested/nested2/main) or the ID OF A CONTROL that can be open or closed - a Popover/Dialog declared in the view and opened with control_by_id openBy, which never enters a framework slot. A control scope beats a slot scope (it is the more specific statement), then the innermost open slot wins. An empty event name removes the registration of THAT scope only. cs_event-binding_call - apply a declarative filter/sorter to an aggregation binding, the client-side equivalent of the UI5 controller pattern getBinding('items').filter(...); the model data stays untouched: t_arg = id, aggregation, method, params. method `filter`: params = path, operator, value1, value2 (empty values clear the filter); method `sort`: params = path, descending, group (abap_bool as `X`/). Each of these events also works roundtrip-free when WIRED IN THE VIEW: write the same call where its result is consumed ()->a( n = press v = client->follow_up_action( val = ... t_arg = ... ) )) and the action runs in the browser without a server call. That is what the obsolete _event_client( ) did, and the only thing it did.

Parameter	Type	Default	Description
val	string
view	clike	cs_view-main
t_arg	string_table	optional

Returns string.

Reading the request

get

Returns z2ui5_if_types=>ty_s_get.

get_event

The name of the event that triggered this roundtrip - empty when no event is being handled (e.g. on the initial call). Shortcut for get( )-event, made for the dispatcher idiom CASE client->get_event( ).

Returns string.

get_event_arg

Parameter	Type	Default	Description
v	i	1

Returns string.

Messages

message_box_display

Parameter	Type	Default	Description
text	any
type	clike	information
title	clike	optional
styleclass	clike	optional
onclose	clike	optional
actions	string_table	optional
emphasizedaction	clike	optional
initialfocus	clike	optional
textdirection	clike	optional
icon	clike	optional
details	clike	optional
closeonnavigation	abap_bool	abap_true
dependenton	clike	optional
contentwidth	clike	optional

message_toast_display

Parameter	Type	Default	Description
text	clike
duration	clike	optional
width	clike	optional
my	clike	optional
at	clike	optional
of	clike	optional
offset	clike	optional
collision	clike	optional
onclose	clike	(empty)
autoclose	abap_bool	abap_true
animationtimingfunction	clike	optional
animationduration	clike	optional
closeonbrowsernavigation	abap_bool	abap_true
class	clike	optional

App navigation

get_app

Parameter	Type	Default	Description
id	clike	optional

Returns REF TO z2ui5_if_app.

_event_nav_app_leave

Returns string.

nav_app_leave

Parameter	Type	Default	Description
app	REF TO z2ui5_if_app	optional
event	clike	optional
r_data	data	optional

Preferred parameter: app — a positional call passes it.

Returns string.

nav_app_call

Parameter	Type	Default	Description
app	REF TO z2ui5_if_app

Returns string.

check_app_prev_stack

Returns abap_bool.

get_app_prev

Returns REF TO z2ui5_if_app.

Session and app state

set_session_stateful

Parameter	Type	Default	Description
val	abap_bool	abap_true

set_app_state_active

Parameter	Type	Default	Description
val	abap_bool	abap_true

set_push_state

Parameter	Type	Default	Description
val	string	optional

Constants

The values an app compares against or passes on: cs_event names every frontend action, cs_view the view slots, cs_device what get( ) reports about the device, cs_nav_mode the routing modes.

cs_device

Constant	Value
cs_device-system-phone	phone
cs_device-system-tablet	tablet
cs_device-system-desktop	desktop
cs_device-system-combi	combi
cs_device-browser-chrome	cr
cs_device-browser-firefox	ff
cs_device-browser-safari	sf
cs_device-browser-edge	ed
cs_device-os-windows	win
cs_device-os-macintosh	mac
cs_device-os-linux	linux
cs_device-os-ios	ios
cs_device-os-android	android
cs_device-orientation-portrait	portrait
cs_device-orientation-landscape	landscape

cs_event

Constant	Value
cs_event-popup_close	POPUP_CLOSE
cs_event-popover_close	POPOVER_CLOSE
cs_event-set_size_limit	SET_SIZE_LIMIT
cs_event-set_odata_model	SET_ODATA_MODEL
cs_event-cross_app_nav_to_ext	CROSS_APP_NAV_TO_EXT
cs_event-cross_app_nav_to_prev_app	CROSS_APP_NAV_TO_PREV_APP
cs_event-clipboard_copy	CLIPBOARD_COPY
cs_event-set_title	SET_TITLE
cs_event-set_favicon	SET_FAVICON
cs_event-set_focus	SET_FOCUS
cs_event-scroll_to	SCROLL_TO
cs_event-scroll_into_view	SCROLL_INTO_VIEW
cs_event-start_timer	START_TIMER
cs_event-system_logout	SYSTEM_LOGOUT
cs_event-keyboard_set_mode	KEYBOARD_SET_MODE
cs_event-keyboard_shortcut	KEYBOARD_SHORTCUT
cs_event-open_new_tab	OPEN_NEW_TAB
cs_event-location_reload	LOCATION_RELOAD
cs_event-set_title_launchpad	SET_TITLE_LAUNCHPAD
cs_event-download_b64_file	DOWNLOAD_B64_FILE
cs_event-urlhelper	URLHELPER
cs_event-clipboard_app_state	CLIPBOARD_APP_STATE
cs_event-store_data	STORE_DATA
cs_event-play_audio	PLAY_AUDIO
cs_event-smart_variant_init	SMART_VARIANT_INIT
cs_event-filter_bar_variant_init	FILTER_BAR_VARIANT_INIT
cs_event-control_by_id	CONTROL_BY_ID	Control
cs_event-control_global	CONTROL_GLOBAL	Control
cs_event-binding_call	BINDING_CALL	Control
cs_event-bind_element	BIND_ELEMENT	Control
cs_event-set_app_state_active	SET_APP_STATE_ACTIVE	experimental
cs_event-set_push_state	SET_PUSH_STATE	experimental
cs_event-set_nav_routing	SET_NAV_ROUTING	experimental
cs_event-image_editor_popup_close	IMAGE_EDITOR_POPUP_CLOSE	obsolet
cs_event-nav_container_to	NAV_CONTAINER_TO	obsolet
cs_event-nest_nav_container_to	NEST_NAV_CONTAINER_TO	obsolet
cs_event-nest2_nav_container_to	NEST2_NAV_CONTAINER_TO	obsolet
cs_event-popup_nav_container_to	POPUP_NAV_CONTAINER_TO	obsolet
cs_event-popover_nav_container_to	POPOVER_NAV_CONTAINER_TO	obsolet
cs_event-z2ui5	Z2UI5	obsolet
cs_event-wizard_set_next_step	WIZARD_SET_NEXT_STEP	obsolet

cs_view

Constant	Value
cs_view-main	MAIN
cs_view-nested	NEST
cs_view-nested2	NEST2
cs_view-popup	POPUP
cs_view-popover	POPOVER

cs_nav_mode

Hash-based app routing modes (see set_nav_routing). The mode decides how much of the running app the URL hash carries, and therefore what the browser Back/Forward buttons (and a reload / bookmark) restore: default - no routing: the hash is left untouched, exactly as before this feature. Back/Forward leave the abap2UI5 page (framework default). fresh - route '#/app/<CLASS>' (class only): Back/Forward/reload/bookmark start the app FRESH (a clean instance, no preserved input). keep - route '#/app/<CLASS>/<DRAFT>' (class + server draft): the exact preserved state is restored (all user input), falling back to a fresh start once the draft has expired.

Constant	Value
cs_nav_mode-default	DEFAULT
cs_nav_mode-fresh	FRESH
cs_nav_mode-keep	KEEP

Types

ty_s_name_value

Field	Type
n	string
v	string

ty_t_name_value

Defined as STANDARD TABLE OF ty_s_name_value WITH EMPTY KEY.