CustomEvent: communicate subcribed to event without meta tag defined

[humitos]

It would be good if we can communicate to the user they are subscribed to the readthedocs-addons-data-ready but they haven't defined the meta[name=readthedocs-addons-api-version] tag which is mandatory to make usage of the Read the Docs data event.

Reference: https://github.com/readthedocs/addons/pull/64/files#r1331997049

[humitos]

I had an idea about this during the weekend and I think it could be good. I'm writing it down here to receive some feedback and consider implementing it.

When triggering readthedocs-addons-data-ready instead of passing the raw JSON object, we could pass an instance of a class we control, e.g (AddonsData). This class requires calling .initialize() to be able to access the JSON object with the addons data. After that, the user can access AddonsData.config which contains the full JSON data

This allows us to perform anything we need inside the .initialize() method:

• tell users that they need to define the meta HTML tag
• communicate anything new we need in the future
• raise exceptions to block the usage of the JSON data if any validation is no passed
• eventually hit an API to log who is using this custom event (?)
• ... and any other requirement we may have in the future

In other words, I'm suggesting to pass an instance of a class we control and enforce users to call a method before making usage of the data. I think this solves the problem I already raised but also gives us the flexibility in the future to communicate with users. @agjohnson what do you think?

[humitos]

The usage from a user's perspective would like this:

document.addEventListener("readthedocs-addons-data-ready", function(event) {
    const addons = event.detail;

    // Accessing `addons.data` at this point without initializing it will fail.
    // It will raise an exception at this point communicating what happened.

    // So, we require users calling `addons.initialize()` here.
    addons.initialize();
    
    // Then, the user can access to the data and do whatever they need.
    const config = addons.data;

    ....
});

[agjohnson]

I think I get what you're aiming for, this seems like a good way to solve the issue above. I would agree that providing a richer data structure in some way would help us now, and probably in the future too.

We could also pass the user a callback function if we don't see the need for additional class methods/etc.

That is:

document.addEventListener("readthedocs-addons-data-ready", function(event) {
    const fn = event.detail;
    const config = fn();
    ...
});

This is maybe a more an expected pattern in JS but the two seem functionally the same.

[humitos]

We could also pass the user a callback function if we don't see the need for additional class methods/etc.

Yeah, I was suggesting a class since seems more flexible for future scenarios --but I've never done this, so I'm not sure if it's a good idea or not.

This is maybe a more an expected pattern in JS but the two seem functionally the same.

Does this pattern have a name I can Google for?¹ Do you have a link at hand where I can read more about this?

Footnotes

1. I thought I was inventing something revolutionary here, but it seems it already exists 😝 ↩

[agjohnson]

Does this pattern have a name I can Google for?

Good question. Maybe "callback" is the closest? This feels maybe similar to how a JSONP callback might work, just with an event added in instead of a named function.

[humitos]

I implemented an approach that I like in #287