Merge pull request #233 from dj95/main

Extend plugin documentation

docs/src/plugin-aliases.md

@@ -23,5 +23,19 @@ Aliases can be added to this block or changed to swap the default built-in plugi
 
 When swapping the default aliases for custom plugins, it's important that these plugins implement the basic contract Zellij (and indeed, other plugins) expect of them. The following sections describe the contract for each default alias.
 
+Here's an example on how to use the plugin alias in a layout:
+
+```javascript
+layout {
+  default_tab_template {
+    children
+    pane size=1 borderless=true {
+      plugin location="compact-bar"
+    }
+  }
+}
+```
+
 ### A note about cwd
+
 When an alias defined a `cwd` for its plugin (such as the filepicker example above), Zellij will add the `caller_cwd` configuration parameter with the cwd of the focused pane in addition to the configured cwd above, instead of overriding the configured cwd of the plugin. This is so that plugins may provide a nicer user experience to their users and still have the desired cwd configuration of the alias.

docs/src/plugin-lifecycle.md

@@ -21,6 +21,12 @@ Will be called when the plugin is loaded, this is a good place to [subscribe](./
 ### update
 Will be called with an [`Event`](./plugin-api-events.md) if the plugin is subscribed to said event. If the plugin returns `true` from this function, Zellij will know it should be rendered and call its `render` function.
 
+Since events are used for asynchronous communication between Zellij and the plugin, they do not follow
+a specific order. This means, that a plugin could receive certain events (like `ModeUpdate`) before the
+`PermissionRequestResult` event is received. Therefore the plugin should ensure, that dependencies within
+the plugin logic between certain events are handled correctly. An example for waiting for the `PermissionRequestResult`
+can be found in the [Common Snippets](./plugin-development-common-snippets.md).
+
 ### render
 Will be called either after an `update` that requested it, or when the plugin otherwise needs to be re-rendered (eg. on startup, or when the plugin is resized). The `rows` and `cols` values represent the "content size" of the plugin (this will not include its surrounding frame if the user has pane frames enabled).