UserScript / Browser Extension integration guide

## Important considerations !!! warning Do not assume you're the only integration A user may have multiple UserScripts or Browser Extensions enabled for MangaBaka, please only append to the various DOM elements and do not stop events for bubbling up to other listeners. Avoid setting the `.innerHTML` attribute or call `.setHTMLUnsafe()` and other "replace everything" attributes and functions !!! !!! hint Easly see integration points in the browser You can add `?outline_browser_extension_elements=1` to any page to show a red border outline of where the various integration (including hidden ones). Hovering the element will show a native browser tooltip with the name !!! ## Event API (recommended) The event API allow for real-time reation to changes in the MangaBaka DOM without polling for it. Events are emitted once an element is added to the DOM - or if it changes - meaning events will fire before the full DOM is completely done rendering, allowing for more native feeling and can help avoid layout shifting. Further more, events are asynchronous, allowing for more concurrent processing to happen. !!! tip Events may trigger more than once This can be due to user actvity on the page (e.g. navigating, changing a library entry and so on), make sure to handle this accordingly. The `element_id` will remain the same between events. !!! !!! caution About the `event.details` object The object may contain internal MangaBaka state, and can change at any time, and without warning. All keys in `ev.detail` should be considered optional Make sure your code is defensive against missing keys or changed value types when using it. !!! ### `mb:page:ready` Is emitted once the page is done rendering. You can subscribe to it like this ```js document.addEventListener('mb:page:ready', (v) => { console.log('mb:page:ready', v) }) ``` The `v.detail` object contains the following keys * `name` (`String`) static value of `page` * `user` (`Object`) basic user information (user id, nickname, username, etc.) - null or omitted when user is not signed in to MangaBaka * `list_config` (`Object`) the "list settings" for the current page ### `mb:element:ready` Is emitted for *every* DOM element that is marked with `data-browser-extension-injection` attribute, as they become available (or change) in the DOM. You can subscribe to it like this ```js document.addEventListener('mb:element:ready', (v) => { console.log('mb:element:ready', v) }) ``` The `v.detail` object contains the following keys * `name` (`string`) The name of the element (e.g. `ratings`, `links`, etc.) * `element_id` (`string`) The DOM ID of the element that is ready (```document.querySelector(`#${v.details.element_id}`)```) * `series` (`V1_Series_Default `) The Series (`default` level of details) data that the element is attached to * `library_series` (`Object`) The same data as `/v1/my/library/{series_id}` minus the nested `Series` key * `user` (`Object`) basic user information (user id, nickname, username, etc.) - null or omitted when user is not signed in to MangaBaka * `list_config` (`Object`) the "list settings" for the current page, this may be different between events on the same page ## DOM API The MangaBaka website uses the HTML data attribute `data-browser-extension-injection` to signal where extensions can safely inject data into the website. You can see the elements by running `document.querySelectorAll("[data-browser-extension-injection]")` in your developer console or by adding `?outline_browser_extension_elements=1` to any page URL. Using these attributes detaches our general DOM / styling from your integration, making it over all more reliable for everyone. Some elements may have `class="hidden"`, meaning they won't be shown to the user by default, make sure to remove this class from the element if you inject into them. ## Feedback, bugs and new integration points Please come by our Discord server (link in left menu) if you have issues, good ideas for new integration points, or found a bug