125 lines
3.9 KiB
Markdown
125 lines
3.9 KiB
Markdown
---
|
|
description: A rendered UI component (markdown or HTML).
|
|
tags: glossary
|
|
---
|
|
The `${lua expression}` syntax can be used to implement custom widgets. If the Lua expression evaluates to a simple string, it will live preview as that string rendered as markdown. However, if the expression returns a `widget.new`-generated result value, you can do some fancier stuff.
|
|
|
|
# Widget types
|
|
To render a widget, call `widget.new` with any of the following keys:
|
|
|
|
* `markdown`: Renders the value as markdown
|
|
* `html`: Renders an HTML string or DOM element as a widget
|
|
* `display`: Render the value either `inline` or as a `block` (defaults to `inline`)
|
|
* `cssClasses`: Array of CSS class names to add to the widget container
|
|
|
|
# Convenience functions
|
|
For common cases, use these shortcuts instead of `widget.new` directly:
|
|
|
|
| Function | Description |
|
|
|---|---|
|
|
| `widget.markdown(md)` | Inline markdown widget |
|
|
| `widget.markdownBlock(md)` | Block-level markdown widget |
|
|
| `widget.html(html)` | Inline HTML widget |
|
|
| `widget.htmlBlock(html)` | Block-level HTML widget |
|
|
|
|
# Markdown widgets
|
|
The simplest widget type renders markdown:
|
|
|
|
```lua
|
|
${widget.markdown("**Bold** and *italic* text")}
|
|
```
|
|
|
|
For block-level content (like lists or tables), use `widget.markdownBlock`:
|
|
|
|
```lua
|
|
${widget.markdownBlock("## A heading\n* Item 1\n* Item 2")
|
|
```
|
|
|
|
# HTML and DOM widgets
|
|
For full control over the rendered output, use HTML widgets with the [[Space Lua/DOM|DOM builder API]]:
|
|
|
|
```space-lua
|
|
function marquee(text)
|
|
return widget.html(dom.marquee {
|
|
class = "my-marquee",
|
|
onclick = function()
|
|
editor.flashNotification "You clicked me"
|
|
end,
|
|
text
|
|
})
|
|
end
|
|
```
|
|
|
|
We can combine this with some [[Space Style]] to style it:
|
|
|
|
```space-style
|
|
.my-marquee {
|
|
color: purple;
|
|
}
|
|
```
|
|
|
|
Now, let's use it (try clicking):
|
|
${marquee "Finally, marqeeeeeee!"}
|
|
|
|
# Built-in widgets
|
|
The standard library provides several pre-built widgets in the `widgets` table:
|
|
|
|
## Buttons
|
|
* `widgets.button(text, callback)` — a simple button that runs the callback when clicked
|
|
* `widgets.commandButton(commandName)` — a button for a command (button text is the command name)
|
|
* `widgets.commandButton(text, commandName)` — a button for a command with custom text
|
|
* `widgets.commandButton(text, commandName, args)` — a button for a command with arguments
|
|
|
|
Example:
|
|
${widgets.button("Hello", function()
|
|
editor.flashNotification "Hi there!"
|
|
end)}
|
|
|
|
${widgets.commandButton("System: Reload")}
|
|
|
|
## Sub-pages widget
|
|
* `widgets.subPages(pageName?)` — renders a list of sub-pages (pages with the given prefix). Defaults to the current page.
|
|
|
|
## Top and bottom widgets
|
|
These render automatically on every page and can be configured:
|
|
|
|
* **Table of contents** — shows a table of contents at the top of the page
|
|
* **Linked mentions** — shows pages that link to the current page at the bottom
|
|
* **Linked tasks** — shows incomplete tasks that mention the current page at the top
|
|
|
|
Configure them in your [[^Library/Std/Config]] page:
|
|
|
|
```lua
|
|
-- Disable TOC altogether
|
|
config.set("std.widgets.toc.enabled", false)
|
|
-- Only render a TOC when there's >= 5 headers
|
|
config.set("std.widgets.toc.minHeaders", 5)
|
|
-- Disable linked mentions
|
|
config.set("std.widgets.linkedMentions.enabled", false)
|
|
-- Disable linked tasks
|
|
config.set("std.widgets.linkedTasks.enabled", false)
|
|
```
|
|
|
|
# Embed widgets
|
|
The `embed` namespace provides widgets for embedding external content:
|
|
|
|
* `embed.youtube(url)` — embeds a YouTube video
|
|
* `embed.peertube(url)` — embeds a PeerTube video
|
|
* `embed.vimeo(url)` — embeds a Vimeo video
|
|
|
|
# Creating custom top/bottom widgets
|
|
You can add your own widgets to the top or bottom of every page by listening to the rendering events:
|
|
|
|
```lua
|
|
event.listen {
|
|
name = "hooks:renderTopWidgets",
|
|
run = function(e)
|
|
return widget.new {
|
|
markdown = "This appears at the top of every page!"
|
|
}
|
|
end
|
|
}
|
|
```
|
|
|
|
See also: [[Space Lua/DOM]], [[API/widget]], [[API/dom]]
|