Design Studio SDK: Examples for Binding Events to ZTL Scripts

I just want to bring two examples for binding ZTL events to BIAL script, listed in the blog from Reiner:

and discussed in the threads:

Design Studio 1.4 SDK - What is the correct approach for binding events to script methods for UI5-based components?

The examples are commited in the community repository in prototypes area, under:

The example is based on the question from Mustafa, how to automatically place the title from application name.

Basics

The events are send to the server, but not directly at the place where the call is located - and by this, you cannot expect that the next line in Java Script is already processed with the new values. The normal process sequence is still applied, the init method in the component and the update method in the component will be executed, then - if the event is directly placed in the update method - the event will be send to the server and again the update method will be executed. This can basically lead to endless loop, if the called method in ZTL will always change the component properties. if not, the loop will be broken by the current implementation of delta handling in design studio SDK.

The automatic bound events to private methods are positioned for user interaction of the component which does not require special code done by the developer (as the code is not dependent on other components in the application). For pushing some information to the component the implicit event "onBeforeRender" should be used.

Example 1.

Use of the onBeforeRender event linked to a method.

extension of contribution.xml:

<property   id="onBeforeRender"   title="Set Application Name"   type="ScriptText"     visible="false"/> <property   id="appName"   title="Application Name"   type="String"   visible="false"/>
and...<defaultValue property="onBeforeRender">this.private_beforeRender();</defaultValue>

extension of contribution.ztl:

// @Visibility(private)  void private_beforeRender() {*    // APPLICATION.createInfoMessage("Name: " + APPLICATION.getInfo().name);      this.appName = "OnBeforeRender: " + APPLICATION.getInfo().name;  *}

extension in java script file:

  afterDesignStudioUpdate: function() {       // Set the logo text to the appName property filled by the onSetAppName event script     this.setLogoText(this.getAppName());  }

Example 2.

Use of implicit event which is triggered after initial rendering of the component.

extension of contribution.xml:

  <property     id="onSetAppName"     title="Set Application Name"     type="ScriptText"     visible="false"/>   <property     id="appName"     title="Application Name"     type="String"     visible="false"/> 
and...<defaultValue property="onSetAppName">this.private_setAppInfoName();</defaultValue>

extension of contribution.ztl:

/* Sets the value of the invisible property appName to the application name */   // @Visibility(private)  void private_setAppInfoName() {*  // APPLICATION.createInfoMessage("Name: " + APPLICATION.getInfo().name);     this.appName = "Event: " + APPLICATION.getInfo().name;  *}

extension in java script file:

afterDesignStudioUpdate: function() {  // Set the logo text to the appName property filled by the onSetAppName event script   this.setLogoText(this.getAppName());  // Raise the onSetAppName event to execute the script for getting the application name   this.fireDesignStudioEvent("onSetAppName");
}

Pros & Contras.

For this use case - fill in some information automatically on first rendering, example 1 is better, because:

it is triggered on the server "before render"
does not require additional roundtrip

Example 2 is positioned to an user action event which does not need to be coded by the application designer, therefore for this scenario it is not the best way, because:

it triggers additional request after first rendering which causes second rendering of the component.

Learning

the triggering of implicit events cannot be made in "initDesignStudio" method, those can be made ideally on user action, but implicitly also in "afterDesignStudioUpdate"
there is a bug in DS 1.4 SP0 (correction will be delivered in SP1) and the marker "@Visibility(private)" is not working at all (the method is not visible)
example 2 with the event would cause an endless loop, which is not occurring only because in this case the value is not changing and DS 1.4 supports delta rendering (is checking if the values have changed)

Code Example