plainleaf/website/API/event.md

#api/syscall

The Event API provides functions for working with SilverBullet's event bus system, allowing communication between different parts of the application.

Notable events to listen to:

• page:click - Fired when a user clicks somehwere in the page.
• editor:complete - Fired when the editor requests code completion.
• editor:pageSaving - Fired when the editor is saving a page.
• editor:pageSaved - Fired when the editor has saved a page.
• editor:pageCreating - Fired when the editor is creating a new page.
• editor:pageModified - Fired when the editor modifies a page.
• editor:documentSaving - Fired when the editor is saving a document.
• editor:documentSaved - Fired when the editor has saved a document.
• cron:secondPassed - Fired every second.
• hooks:renderTopWidgets - Fired when rendering top widgets.
• hooks:renderBottomWidgets - Fired when rendering bottom widgets.
• system:ready - Fired when all plugs are loaded.

Event Operations

event.listen(listenerDef)

Register an event listener.

event.listen {
  name = "my-event",
  run = function(e)
    print("Data", e.data)
  end
}

event.dispatch(eventName, data, timeout)

Triggers an event on the SilverBullet event bus. Event handlers can return values, which are accumulated and returned to the caller.

Example:

-- Simple event dispatch
event.dispatch("custom.event", {message = "Hello"})

-- Event dispatch with timeout and response handling
local responses = event.dispatchEvent("data.request", {id = 123}, 5000)
for _, response in ipairs(responses) do
    print(response)
end

event.listEvents()

Lists all events currently registered (listened to) on the SilverBullet event bus.

Example:

local events = event.listEvents()
for _, eventName in ipairs(events) do
    print("Registered event: " .. eventName)
end