UI5ers Buzz #34: New Event Parameter Syntax in XMLViews

[AndreasKunz]

It's 2018 and the UI5 developer world has mostly settled on using XMLViews. We have introduced them in UI5 on July 11^th, 2011, and after seven years there's probably nothing left to improve, right?

Wrong!

In addition to the new asynchronous parsing of XMLViews, we have added another pretty neat and widely useful feature to XMLViews in version 1.56 of UI5, which has just been released a week ago: a new event handler parameter syntax! While the name of this feature may be a tad long, its benefit is brevity of code. So, what exactly is it about?

The Past

For the last seven years, you could assign event handlers to control events, simply by assigning the controller method name to an attribute in the XML tag that corresponds to the event name:

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

The leading dot may surprise some of you, but in fact that's the correct way to specify a local method inside the controller. Never mind, it actually also works without that dot, as such names are first looked up in the controller, then on global level.

There are some additional options, e.g. you can also assign static functions in global objects by using multi-segment names like press="GlobalHelper.doSomething".

This was obviously good enough for creating thousands of successful apps. But it also means that when different events should do slightly different things, each event needs a separate controller method:

<Button text="-10" press=".handleMinusTen" />

<Button text="-1" press=".handleMinusOne" />

<Button text="+1" press=".handlePlusOne" />

<Button text="+10" press=".handlePlusTen" />

All these methods probably just call the same central method with slightly different parameters. Alternatively, you could have ONE common event handler method. But within that method, you would have to determine what exactly needs to be done based on the event source. Attaching custom data to the buttons might help with that, but still: It's some overhead in the code. And once dynamic data coming from models is needed, it may get even more complicated.

The Future

Enter the new event handler parameter syntax! Starting in UI5 version 1.56 you can also specify a list of parameters that are passed into the event handler:

<Button text="-10" press=".handleChange(-10)" />

The value can then be used directly in your controller method:

handleChange: function(relativeChange) {

    this.value += relativeChange;

}

How simple is that?!

You can specify JavaScript literals like strings, numbers, arrays, and objects. But wait, there's more: You can use the full power of the Expression Binding syntax. Most importantly, this means that you can simply write a binding statement and the event handler will directly get the bound data – no need to handle contexts, models and property names in your controller code:

<Button text="Display Amount" press=".displayValue(${amount})" />

(In case you wonder about the "$" character in front of the curly braces, this is how bindings are written in Expression Binding.)
Relative binding paths like the one in this example are evaluated starting from the context path of the control which fires the event. Evaluation happens at the time when the event is triggered.

That's powerful: In an environment where you are used to writing bindings anyway, you can use the same syntax, and your controller code directly gets the values to work with.

Of course, you can also use complex binding statements and all the advanced features of Expression Binding, which include operators and even function calls. We'd just recommend that you don't go overboard with those: For real logic, controller code is still the best place.

There are several static functions like sap.m.MessageBox.show(...) in UI5 that need some kind of input - and you might implement more of them in your own helper objects. Previously, you always had to implement a controller method to call them, in order to pass the needed arguments. Now they can be called directly:

<Button text="Press Me" press="sap.m.MessageBox.show('Hello')" />

Or maybe with translated text from the "i18n" model?

<Button text="Press Me" press="sap.m.MessageBox.show(${i18n>/HELLO_TEXT})" />

You just have to make sure the respective module is already loaded at the time when the XMLView is parsed by the framework.

The Details

There are some details you should keep in mind:

1. The event object, which is normally passed as the sole argument to the handler function, is no longer passed when parameters are specified. In cases where the event object is still needed, the $event placeholder can be used.


2. However, the most important use of the event object is for accessing the event parameters. They can be accessed directly, using a special model named $parameters, which leads to the slightly dollar-heavy <Button press=".handleNewValue(${$parameters>/newValue})" />


3. There is another special model: a ManagedObjectModel wrapping the event source control, available by the name $source. To access the text of the button, you can write <Button press=".showText(${$source>/text})" />


4. For those cases where the event handler function resides on a global object outside the controller, but still needs to access the controller, there is another placeholder you can use for passing the controller instance as an argument: $controller. As Binding Expressions allow calling functions, you can also use this to retrieve the value you actually want to pass, e.g. from another control inside the same View:
   <Button press=".showText($controller.byId('someInput').getValue())" />
   Again, use with moderation!

The Wrap-Up

In hindsight it's obvious that this feature is handy. But nobody noticed, and nobody asked for it. 🙂 We won't put lots of effort into re-writing all zillion XMLView code examples we have created over the years, but it's good to keep this new feature in mind when developing new apps, as it may save you some code and some hassle when implementing your XMLViews.

Oh, and it works in JSONViews, too! In case anyone cares. 😉  And in the new XMLComposite controls.

If you want to read more and see more examples, head over to the newly extended documentation for handling events in XMLViews.

Enjoy!

Andreas

Previous Post: UI5ers Buzz #33

Andreas is software developer and architect at SAP since 2005, focusing on web-based user interfaces. Member of the UI5 development team since its inception and a main driver behind open-sourcing it as OpenUI5.