docs: add a guide for using Components

[Fevol]

This is a preliminary PR for adding a guide on how to use the Component class for managing lifecycles and events.

This guide aims to give developers a tool to avoid common mistakes made during plugin development, including:

• Adding event listeners on window, document, view, ..., but not removing them up when the plugin/view/... is unloaded
• Instantiating resources from libraries, WASM or classes, but never deallocating them
• Attaching elements to the DOM, without removing them
• Creating a Component for a MarkdownRenderer.render call, but never attaching it to a parent Component

Any input would be very welcome:

• Location (is this guide in a discoverable location?)
• Title (does the title make sense, should the document be split up?)
• Examples (do they make sense, are they correct, ...)
• Etc...

[liamcain]

I'm not sure this is a good example for plugins. Usually Components should not be calling load/unload themselves. If they are properly attached to a parent, then the parent Component is responsible for loading and unloading

[Fevol]

I've removed this example for now. The main idea behind this is that you can fully unload and re-load the component, and everything will be handled properly.

[liamcain]

This example is awkward since onResize is undefined and its very easy to mess up removeEventListener (if you don't pass in the exact instance, it won't be properly removed).

[Fevol]

I am not sure if there is a different, but still simple, example that can be used for this. For now, I have changed the example such that onResize is a method on the class.

[liamcain]

This seems a little awkward since the example with onload and onunload is already using functions of Component.

[Fevol]

I think for the purposes of this example, that is fine. The main point to demonstrate here is that explicitly registering something to the Component is safer, rather than handling the loading/unloading yourself (be it in a Plugin, a custom class that you manage the lifecycle of, etc...). The Plugin just happens to be the most well known construction for this 😅

What do you think of:

While this works fine, you need to remember to remove your listener in the onunload call. Obsidian fortunately offers a better and simpler methods to register events via the Component system:

[joethei]

The Obsidian native approach for these would be:

new ButtonComponent(this.containerEl).setButtonText('Click me!').onClick(() => {
	new Notice('Button clicked!');
});

// keyboard events
this.scope = new Scope(this.app.scope); //this does not need to be unloaded, Obsidian takes care of it
this.scope.register(['Ctrl'], 's', () => {
	new Notice('Shortcut pressed!');
})

[Fevol]

I intentionally chose this construction with button and window to showcase the parallels for registering listeners, and the difference in how long these listeners would live for.

Do you think this should be added as a separate example? Or maybe as an additional note clarifying that there is a more correct implementation available using Obsidian API's.

[liamcain]

This is great! Very informative, and easy to follow.

[joethei]

we might want to mention that using the plugin / app instance as the compoent is a bad idea here.

[liamcain]

I think the current phrasing is clear enough. Here's my attempt to add more info:

Instead, you should pass a component that has a clearly defined lifecycle, one that will be loaded and unloaded at an appropriate time. Both Plugin and View are components; however, View is a more appropriate choice since its lifespan matches with the MarkdownRenderer. We can simply pass the View instance itself via this:

Might a bit wordy though...

[Fevol]

I hadn't even considered that people might use plugin or app... (is App a component though?) Regardless, I think this is an useful addition.

[Fevol]

Added the suggestion!