[doc issue] Missing documentation to Event Buses

[biscimus]

Missing documentation to Event Buses

Hello Documentation Team,

Recently, I faced an issue trying to access controllers of child views inserted in the parent view. The concept of event buses really helped to reduce lines of code and to make the entire inter-controller-communication easier (in case there are better ways to solve this problem, please let me know). However, the event bus feature was overlooked by our team for quite some time, since there weren't any documentation pages referring to the feature, but only a single API reference page instead. There are a couple documentation pages describing how to incorporate child views using multiple targets, but no description how these child controllers should interact with each other & communicate information. Event buses also come in handy when generally dealing with publishing custom events, which is why I'm proposing a documentation page for the event bus feature.

Feedback Type (Optional)

None

Page Title on SAP Help Portal (prefilled)

No response

Page URL on SAP Help Portal (prefilled)

No response

[KvM2]

@biscimus, Thanks for your contribution - we appreciate it. Would you mind pointing out to me any related documentation and where you miss such an event bus-related documentation? Thanks!

[boghyon]

@biscimus Would it be helpful to have something like https://stackoverflow.com/a/46186706/5846045 in the documentation?

[biscimus]

@boghyon Yes something like that would be very nice!

[Thodd]

Hi @biscimus,

concerning the EventBus we have to take the overall application architecture into account.
While it is true that you can achieve an inter-controller communication quite easily, it is not always the preferred or best practice way.

We struggle with this topic, since it's highly dependent on the application structure and your needs.
We are always a bit flimsy on that topic for a reason... and the reason being: we can't recommend it wholeheartedly ;)
Less LoC doesn't necessarily mean better design, so we are a bit careful with this topic.

In general, I would recommend to use the global EventBus as sparingly as possible (if at all).

I'll give you some of my thoughts down below, as well as a concrete recommendation for UI5 apps.
But please understand that this is just my opinion. Like any design pattern, the whole topic is contentious and also a reason why we are a bit "weak" on the topic in the developer guide...
Ultimately it's highly dependent on your app and the scope of it.

Hope that help's you in your design considerations.

BR,

Thodd

---

I'll outline the architectural difficulties first:

• An EventBus is not unlike a globally shared (mutable) state. This can lead to spaghetti code when a lot of handlers need to be registered and a shared state is tracked
  • Function calls originate arbitrarily from anywhere. Consequently implementations tend to live "at the most convenient place" instead of the "most well designed place"
  • I would consider this to be a downside for significantly large applications. Especially with respect to the upcoming release of UI5 2.0, we strife for less global state too.
• Components (speaking of software components, not only UI5) might appear to be loosely coupled, but in reality are more or less tightly coupled, albeit via hidden channels
  • You should always determine the pros and cons of an EventBus structure based on this coupling behavior, see also https://connascence.io/
• An EventBus is easily misused to violate the defined lifecycle of the programming model
  • Instead of relying on the well orchestrated lifecycle events, you might want to break out because it's convenient, but ultimately what you do is "make a function call from outer space"
• Events in general should be used to signal that something has happened and not implement business logic
• the fire-and-forget nature of Events implies orchestration problems
  • Especially if you use Events to communicate between Controllers. In an asynchronous application, the instantiation order of Views/Controllers is not guaranteed. What if a Controller already fires a one-time event, but another Controller isn't already subscribe to this Event because of timing variations? You essentially open the door for race conditions.
• The EventBus is not really good with TypeScript. The events are arbitrarily defined and type checking for the Event data is not possible, it's just an object. There is no typed connection between publisher and subscriber.
  • Dedicated APIs (outlined below) have the chance to describe well defined argument and result types.

Now to the technical side of UI5:

• UI5 Components provide a separate self contained EventBus instance, this instance has no relation to the global EventBus
  • This is the preferred way to use an EventBus
  • There is less implicit coupling of arbitrary "things", as each View/Controller owned by the Component has access to it's owner Component via dependency injection.
    • This is a contract defined by us, which allows you to rely on it's stability, also in UI5 2.0.
  • Views and Controllers should normally be cohesive with the Component's purpose itself
• Inter-Component communication however is interesting, since this is a case where I could imagine an EventBus to notify other Components (not owned by you) of things happening inside your own Component, e.g. data was loaded and is available.
  • However: I would argue this should only be done when the Components are completely detached and run side-by-side. In case there is a the parent component, the same owner Component concept applies.
• An EventBus cannot cover for timing as described above (see fire-and-forget).
  • But again, in this case (which is actually pretty common), the owner Component can help orchestrate this.
  • I would prefer a Promise-based API over events here. Each Controller can access such an API and unlike an event, a Promise resolves even when "the thing has already happened". This is also allows for a nicer modern syntax with async/await instead of an event-callback hell.
    • But: Please be aware that UI5 lifecycle events should not be async functions, their return value is void and we reserve the return value for potential future use.
  • Instead of using the Component to orchestrate timing, you can also introduce cohesive business logic modules, which are dependencies of your Controllers.

[biscimus]

@Thodd Thank you for your detailed input. If the event bus is that much of a sensitive topic, isn't that even another reason to add a documentation regarding this feature?

[KlattG]

@biscimus After lengthy discussion with our developers we concluded that providing additional documentation on the event bus feature is neither necessary nor prudent at this point. We promise, however, to keep an eye on the issue and inform you if anything changes.