62 lines
2.1 KiB
Plaintext
62 lines
2.1 KiB
Plaintext
:sig
|
|
String component(String name, [DValue props], [Request& context])
|
|
|
|
:see
|
|
>ob
|
|
>component_render
|
|
>1_COMPONENT
|
|
>1_RENDER
|
|
|
|
:content
|
|
Renders another `.uce` file as a component and returns the captured output as a `String`.
|
|
|
|
`component()` resolves the target file relative to the current page and also tries the `components/` prefix automatically, mirroring the shorthand used by the starter example project.
|
|
|
|
Component props are passed in `context.props`.
|
|
|
|
Because `<?= ... ?>` HTML-escapes its value, embed component markup with `<?: component(...) ?>`, `print(component(...))`, or use `component_render(...)` for direct output.
|
|
|
|
## Named Components
|
|
|
|
When `name` contains a colon, such as `components/card:BODY`, the part after the colon selects a named component handler exported from the component file through `COMPONENT:BODY(Request& context)`.
|
|
|
|
The default handler is `COMPONENT(Request& context)`.
|
|
|
|
When `name` starts with a colon, such as `:BODY`, the target resolves against the current `.uce` file so component files can call their own named handlers without repeating the file name.
|
|
|
|
When a component unit defines `ONCE(Request& context)`, the runtime calls that hook once per request, per resolved component file, before the first `COMPONENT()` or `COMPONENT:NAME()` handler from that file runs.
|
|
|
|
## Resolution Order
|
|
|
|
- exact file name
|
|
- exact file name with `.uce`
|
|
- the same two forms under `components/`
|
|
|
|
## Common Patterns
|
|
|
|
Default component handler:
|
|
|
|
|
|
Named component handler:
|
|
|
|
|
|
Self-targeted named handler from inside the same file:
|
|
|
|
|
|
Preparing props in C++ before rendering:
|
|
|
|
|
|
Embedding returned component markup inside a literal block:
|
|
|
|
|
|
Because `<?= ... ?>` escapes HTML, use `<?: ... ?>` when inserting the returned markup from `component()`.
|
|
|
|
## Lifecycle Notes
|
|
|
|
- `INIT(Request& context)` runs once when the worker loads that unit into memory.
|
|
- `ONCE(Request& context)` runs once per request before the first component or render entrypoint from that file.
|
|
- `component()` then calls either `COMPONENT(Request& context)` or the selected `COMPONENT:NAME(Request& context)` handler.
|
|
|
|
:example
|
|
print(component("examples/sample_unit"), "\n");
|