Repository navigation
Missing documentation for event type names in SDK #415
Description
Hi,
Ever since 1.115 my team is having issues setting the correct type on events, There seems to be no up-to-date documentation or clear Types indaction;
For example before 1.115, this was correct:
XML:
<dragDropConfig>
<dnd:DropInfo drop="onDropFile"/>
</dragDropConfig>
Controller
onDropFile(event: Event) {
const browserEvent = event.getParameter("browserEvent") as DragEvent;
if (browserEvent.dataTransfer.files) {
const files = browserEvent.dataTransfer.files;
this.attachFiles(files);
}
}
After 1.115 this is no longer correct, but according to the documentation this is correct: https://ui5.sap.com/1.116.0/#/api/sap.ui.core.dnd.DropInfo%23events/drop
If we try to do it the suggested way according to the release notes we get ( I think this:
Controller
onDropFile(event: DropInfo$DropEvent) {
const browserEvent = event.getParameter("browserEvent") as DragEvent;
if (browserEvent.dataTransfer.files) {
const files = browserEvent.dataTransfer.files;
this.attachFiles(files);
}
}
However there isn't any combination that works with DragEvent, and without documentation this just becomes a guesing game.
Is there something we are missing or is the documentation just not up-to-date?
Activity
akudev commentedon Sep 4, 2023
Hi Eric,
There are several aspects to this ticket and I'll try to address all of them:
1.) Just to explain the overall motivation (even though it might be clear to you already, anyway):
event.getParameter("xyz")is no longer correct wheneventis simply typed assap.ui.base.Event. Yes, this is true and intended and a good thing that is in line with what you expect from TypeScript, even though - as often in TypeScript - it forces you to write a bit more or express things in a more precise way. Being able to put in any string without any check and then getting something back that is typed asanywas a typing gap in the UI5 types. Now each event type knows which parameters it has and how they are typed. This means you get the existing parameter names as suggestions and won't accidentally mis-type them or use parameters that don't exist. Plus the result already has the correct type. This is exactly what TypeScript is used for. And as the base typeEventdoes not have parameter "xyz", TypeScript will let you know that accessing it is wrong. So this new behavior is definitely intended.2.) The following code does not work and this is a bug:
The "browserEvent" parameter is typed as UI5 Event, hence TypeScript complains about the cast to the browser's
DragEvent(because "the types do not sufficiently overlap"). The parameter should rather already be typed asDragEvent, which would make the typecast in the application code unneeded. I'm not sure whether this is a bug in the documentation of theDropInfo'sDropevent or in the type generation: the DropInfo indeed documents it asEvent, notsap.ui.base.Event, and in the code editor it is understood as browser event. Somewhere along the way it is turned into a UI5 event, though. We need to investigate and fix, but for the time being you can write:With this, the subsequent access to the
dataTransferproperty will work just fine.3.) For the rest I'm not totally clear what you mean: "[no] combination that works with DragEvent, and without documentation"...
Do you refer to the not-working cast to
DragEventI explained above? Or to another issue related to aDrag*event ofDropInfoorDragInfo? What exactly would be the "missing documentation"? Is this complaint related to the composed names of the events not being in the UI5 API documentation or to something else?EricVanEldik commentedon Sep 4, 2023
Thank you @akudev for the explination, for point 3: I was refering to problem above and the documentation in https://ui5.sap.com/1.116.0/#/api/sap.ui.core.dnd.DropInfo%23events/drop not matching the type indication.
I understand what you try to achieve with the changes in 1.115, but without proper documentation a piece of code like
onDescriptionSearch(event: SearchField$LiveChangeEvent) {is hard to find the proper type, since there is no refference in the documenation to LiveChangeEvent being the type that is outputed when using livechange.akudev commentedon Sep 4, 2023
Ok,... for problem 2.) a fix is on its way already.
The more general problem, to rephrase it, is that the type names for the events are not documented anywhere, making it hard to know them, right?
On the one hand we hoped that the consistent
<ControlName>$<EventName>Eventway how the event type names are constructed would make it easy to come up with them. E.g. for https://ui5.sap.com/1.116.0/#/api/sap.ui.core.dnd.DropInfo%23events/drop it would be the control/class name first ("DropInfo"), then a dollar sign, then the event name ("Drop") and then the constant string "Event", which makes itDropInfo$DropEvent.On the other hand I see why it would be better to simply have it explicitly written in the documentation.
The challenges for this are:
These challenges don't make the request invalid - it totally makes sense for better TypeScript support - , but harder to implement, hence this is not a thing that will happen quickly.
Where it currently says
oControlEvent [sap.ui.base.Event](https://ui5.sap.com/1.116.0/api/sap.ui.base.Event)it should probably sayDropInfo$DropEvent. But then the "getSource" and the parameters listed below should rather go to the other linked page whereDropInfo$DropEventis defined. This would make usage harder for everyone. Maybe a short-term alternative would be to use the "Description" column, which is so far unused, to mention the TypeScript type for the event, without a link to a dedicated page for this type? The effort would be limited if we just apply a copy of the event name generation algorithm locally.[-]Missing documentation[/-][+]Missing documentation for event type names in SDK[/+]EricVanEldik commentedon Sep 5, 2023
A reference in the documentation would be a plus, however I think you explination with example allready clear enough (for me).
It was just bad luck that the second method I tried to correct was the one that was bugged.
[FIX] DropInfo: correct the type of d&d related browser events
akudev commentedon Sep 5, 2023
Bug is fixed with UI5/openui5@43e032c for the 1.119 types.
The general event name issue is still open.