Plugin Lifecycle

Zellij provides the zellij-tile crate to plugins to facilitate development.

The zellij-tile crate provides the ZellijPlugin trait:

#![allow(unused)]
fn main() {
pub trait ZellijPlugin: Default {
    fn load(&mut self, configuration: BTreeMap<String, String>) {}
    fn update(&mut self, event: Event) -> bool {
        false
    }
    fn pipe(&mut self, pipe_message: PipeMessage) -> bool {
        false
    }
    fn render(&mut self, rows: usize, cols: usize) {}
}
}

Lifecycle Methods

load

Will be called when the plugin is loaded, with the plugin's configuration. This is a good place to subscribe to events that are interesting for this plugin.

update

Will be called with an Event 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 this great plug post

Events that happen while a plugin is still loading are kept and delivered once it has loaded. This also works for plugins loaded in the background (eg. through load_plugins) before any user is attached to the session.

A plugin that is hidden (eg. with hide_self) is not rendered, but keeps receiving the ModeUpdate, TabUpdate, PaneUpdate and InputReceived events it is subscribed to.

pipe

Will be called when a message is sent to the plugin through a pipe (from the command line, a keybinding or another plugin). A PipeMessage whose payload is None means the pipe has ended. As with update, returning true renders the plugin.

render

Will be called either after an update or pipe 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).

This function is expected to print to STDOUT whatever the plugin would like to render inside its pane. For more information, see plugin ui rendering.

Registering a plugin

After implementing the trait on a struct, we'll need to use the register_plugin macro on it:

#![allow(unused)]
fn main() {
struct MyPlugin {
}

impl ZellijPlugin for MyPlugin {
}

register_plugin!(MyPlugin);
}

Zellij will then instantiate the plugin (using the Default implementation) and call it as needed.

Shared plugins

Normally, every pane that shows a plugin runs its own instance of it. A shared plugin is a plugin where a single instance serves many panes. This saves memory and lets the plugin keep one state for all of them - the built-in zellij:bars plugin, which draws the tab bar, the status bar and the compact bar of every tab, is a shared plugin.

Each pane (or background load) that uses a shared plugin is a slot. All slots that load the same plugin location with the same value for the instance configuration key (or without one) belong to the same instance. The instance is loaded with the configuration of its first slot, and is unloaded when its last slot is closed.

A shared plugin implements the ZellijSharedPlugin trait and is registered with register_shared_plugin!:

#![allow(unused)]
fn main() {
pub trait ZellijSharedPlugin: Default {
    fn load(&mut self, configuration: BTreeMap<String, String>) {}
    fn slot_added(&mut self, slot: Slot) {}
    fn slot_removed(&mut self, slot_id: SlotId) {}
    fn client_connected(&mut self, client_id: ClientId) {}
    fn client_disconnected(&mut self, client_id: ClientId) {}
    fn update(&mut self, event: Event, context: EventContext) -> RenderResponse {
        RenderResponse::Nothing
    }
    fn pipe(&mut self, pipe_message: PipeMessage, context: EventContext) -> RenderResponse {
        RenderResponse::Nothing
    }
    fn render(&mut self, rows: usize, cols: usize, slot_id: SlotId, client_id: ClientId) {}
}
}
MethodCalled when
loadThe instance is loaded, once
slot_addedA pane or background load starts using this instance. The Slot carries its id, kind and configuration
slot_removedA slot's pane is closed
client_connected / client_disconnectedA user attaches to or leaves the session
updateAn event the instance is subscribed to arrives. context.slot_id is set for events tied to one pane (Key, Mouse, PastedText, Visible, PermissionRequestResult and PluginConfigurationChanged), and context.client_id when the user the event came from is known
pipeA pipe message arrives, with the same kind of context
renderOne slot needs to be drawn for one user. It is called once per slot and user that can see it

Instead of a bool, update and pipe return a RenderResponse: Nothing, All (every slot for every user), Client(client_id) (every slot as seen by that user) or Slots(slot_ids).

Commands that act on "this plugin's pane" (eg. set_selectable, hide_self, set_self_collapsed or set_live_view) only work inside render and slot_added, where Zellij knows which slot is meant. Anywhere else they fail with an error; use the slot commands (eg. set_selectable_slot(slot_id, ...)) instead.

#![allow(unused)]
fn main() {
use std::collections::BTreeMap;
use zellij_tile::prelude::*;

#[derive(Default)]
struct State {
    slots: BTreeMap<SlotId, Slot>,
    modes: BTreeMap<ClientId, InputMode>,
}

register_shared_plugin!(State);

impl ZellijSharedPlugin for State {
    fn load(&mut self, _configuration: BTreeMap<String, String>) {
        request_permission(&[PermissionType::ReadApplicationState]);
        subscribe(&[EventType::ModeUpdate]);
    }
    fn slot_added(&mut self, slot: Slot) {
        set_selectable(false);
        self.slots.insert(slot.id, slot);
    }
    fn slot_removed(&mut self, slot_id: SlotId) {
        self.slots.remove(&slot_id);
    }
    fn update(&mut self, event: Event, context: EventContext) -> RenderResponse {
        match event {
            Event::ModeUpdate(mode_info) => match context.client_id {
                Some(client_id) => {
                    self.modes.insert(client_id, mode_info.mode);
                    RenderResponse::Client(client_id)
                },
                None => RenderResponse::Nothing,
            },
            _ => RenderResponse::Nothing,
        }
    }
    fn render(&mut self, _rows: usize, _cols: usize, slot_id: SlotId, client_id: ClientId) {
        let label = self
            .slots
            .get(&slot_id)
            .and_then(|slot| slot.configuration.get("label").cloned())
            .unwrap_or_default();
        println!("{} {:?}", label, self.modes.get(&client_id));
    }
}
}