Addressing the Event Handler

Depending on the syntax of its name, the event handler will be looked up by this name in different locations:

• Names starting with a dot ('.') are always assumed to represent a method in the controller. They are resolved by removing the leading dot and reading the property with the resulting name from the controller instance. These names are relative to the view/controller. For example, press=".myLocalHandler" is resolved by attachPress(oController["myLocalHandler"], oController);

  Note

  This syntax is by intention consistent to the complex binding syntax for formatter functions.

• Names defined in a core:require statement can be used to access static functions of the required modules. For example, press= "Util.handler" sets the static handler function of the required Util module as press handler for the respective control. For more information, see Require Modules in XML View and Fragment.

• Names containing a dot at a later position are assumed to represent:

  • Static functions from the modules which are loaded through the XML view required modules (See Require Modules in XML View and Fragment)

  • Global functions if the function cannot be resolved within the XML view require modules and are resolved by calling ObjectPath.get with the full name. For example, name press= "some.global.handler" is resolved by calling attachPress(ObjectPath.get("some.global.handler"), oController);.

    Note

    The use of globals is not recommended and they should be replaced, see Require Modules in XML View and Fragment.

• Names without dot are interpreted as a relative name; if nothing is found, they are interpreted as an absolute name. This variant is only supported for backward compatibility.

  Note

  This legacy syntax is not supported for control properties of type function.

The "this" Context

As long as no event handler parameters are specified and regardless of where the function was looked up, it will be executed with the controller as the context object (this). This is also true for global event handlers and makes the implementation of generic global handlers easier that may need an easy way back to the controller/view in which they are actually used, for example, to call createId or byId. This should make the development of global event handlers more consistent with controller local event handlers.

Therefore, the following declaration is equivalent to a call of controller.doSomething() when the button is pressed:

<Button text="Press Me" press=".doSomething"/>

Passing Parameters

In XMLViews and JSONViews (deprecated as of UI5 version 1.120) it is also possible to directly specify the parameters that should be passed into the event handler function. These parameters then are passed instead of the event object. The syntax mimics the JavaScript syntax for function calls:

<Button text="Press Me" press=".doSomething('Hello World')"/>

Any JavaScript literals including objects and arrays can be passed:

<Button text="Press Me" press=".doSomething('string', 0, 5.5, {key1: 'value1', key2: 'value2'}, ['value1', 'value2'])"/>

It is also possible to access model properties. The syntax to be used is the one used within Expression Binding – binding paths are enclosed in ${…} :

<Button text="Press Me" press=".doSomething(${products>unitPrice})"/>

The binding context from which relative binding paths are resolved is the context of the control which triggers the event. This means that for a control in a table row, relative binding paths like the one above, always pass the data from the table row where the event occurred. This is very convenient, because it is no longer required to find out the data element to which the table row is bound.

Complex binding syntax can also be used (to add formatters, types etc.), as well as all expressions allowed by Expression Binding:

<Button text="Press Me" press=".doSomething(${path: 'products>unitPrice', formatter: '.formatPrice'})" />
<Button text="Press Me" press=".doSomething(10 * ${products>unitPrice})" />
<Button text="Press Me" press=".doSomething(${products>type} === 'Laptop')" />

Formatters are resolved the same way as the event handlers: a leading dot means the formatter is member of the controller.

There are two special named models available in event handlers to make accessing certain values easier:

The first one is named $parameters and contains the event parameters:

<Select change=".doSomething(${$parameters>/selectedItem})" />

Here the event parameter selectedItem is passed into the event handler.

The other one is named $source and is a ManagedObjectModel which wraps the control firing the event:

<Button text="Press Me" press=".doSomething(${$source>/text})" />

Here the text of the pressed button is passed into the event handler.

There are also two special values which can be used as parameters.

The first special value is named $event and represents the original event object. This event object is no longer passed to event handlers, once parameters are specified. This is because of the $parameters model, which provides access to the event parameters, and it is not needed in most cases. However, when access to the event object is still needed in the event handler, it can be explicitly passed:

<Button text="Press Me" press=".doSomething($event)" />

This leads to the same result as specifying .doSomething without any parameters, but further parameters can of course be given.

The second special value is $controller. As described above, as soon as parameters are specified, the this context inside the event handler function is always the object on which this function is defined. However, sometimes it is still required to access the controller even in a handler function which is NOT defined in the controller, but on some other helper object. In this case, the controller can be explicitly passed as one of the parameters:

<Button text="Press Me" press=".doSomething($controller)" />