71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
---
|
||
description: A named signal that plugs and Lua scripts can listen to and react to.
|
||
tags: glossary
|
||
---
|
||
SilverBullet has its own event bus that allows different parts of the system to communicate. Events are the foundation for much of SilverBullet's extensibility — features like [[Service]], [[Virtual Pages]], widgets, and custom indexing are all built on top of events.
|
||
|
||
# Subscribing to events
|
||
Use `event.listen` to subscribe to an event:
|
||
|
||
```lua
|
||
event.listen {
|
||
name = "editor:pageLoaded",
|
||
run = function(e)
|
||
print("Loaded page: " .. e.data.name)
|
||
end
|
||
}
|
||
```
|
||
|
||
The `run` callback receives an event object with a `data` field containing event-specific information. To see what data an event provides, add a `print` call and check the [[Log|logs]].
|
||
|
||
# Dispatching events
|
||
You can dispatch your own custom events:
|
||
|
||
```lua
|
||
event.dispatch("my-custom-event", {message = "Hello!"})
|
||
```
|
||
|
||
Other scripts can then listen for `my-custom-event`.
|
||
|
||
# Built-in events
|
||
Here is a list of built-in events triggered by SilverBullet's core:
|
||
|
||
## Editor events
|
||
* `editor:init`: Editor has initialized
|
||
* `editor:pageLoaded`: A page has been loaded in the editor
|
||
* `editor:pageReloaded`: A page was reloaded (e.g. after being changed on disk)
|
||
* `editor:pageSaving`: A page is about to be saved
|
||
* `editor:pageSaved`: A page has been saved
|
||
* `editor:pageCreating`: A page is being created (can return content — used by [[Virtual Pages]])
|
||
* `editor:pageModified`: A change was made to the document (fires in real-time)
|
||
* `editor:documentSaving`: A document (non-page file) is about to be saved
|
||
* `editor:documentSaved`: A document was saved
|
||
* `editor:modeswitch`: Toggled between [[Vim]] mode and normal mode
|
||
* `editor:fold`: Code was folded in the editor
|
||
* `editor:unfold`: Code was unfolded in the editor
|
||
|
||
## Interaction events
|
||
* `page:click`: User clicked a location on the page
|
||
* `editor:complete`: Editor completion triggered — return completion results to extend [[Completion]]
|
||
* `slash:complete`: Slash completion triggered — return completion results
|
||
* `editor:lint`: Lint request — return errors to show in the editor
|
||
|
||
## System events
|
||
* `page:index`: A page has changed and needs to be indexed (used by [[Object]] indexing)
|
||
* `plugs:loaded`: Plugs were loaded
|
||
* `cron:secondPassed`: One second has passed (useful for implementing periodic behavior)
|
||
|
||
## Widget events
|
||
* `hooks:renderTopWidgets`: Top widgets requested to render — return widgets to display above the page content
|
||
* `hooks:renderBottomWidgets`: Bottom widgets requested to render — return widgets to display below the page content
|
||
|
||
# All subscribed events
|
||
Here’s a dynamically generated list of events that this SilverBullet instance has subscribed to, to give a sense of what’s there:
|
||
${query[[
|
||
from event.listEvents()
|
||
where not _:startsWith("service:")
|
||
order by _
|
||
]]}
|
||
|
||
See [[API/event]] for the full API reference.
|