110 lines
3.0 KiB
Plaintext
110 lines
3.0 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:
|
|
|
|
```cpp
|
|
DValue props;
|
|
props["title"] = "Status";
|
|
|
|
<><?: component("workspace/panel", props, context) ?></>
|
|
```
|
|
|
|
Named component handler:
|
|
|
|
```cpp
|
|
DValue props;
|
|
props["title"] = "System";
|
|
props["body"] = "Healthy";
|
|
|
|
print(component("components/card:BODY", props, context));
|
|
```
|
|
|
|
Self-targeted named handler from inside the same file:
|
|
|
|
```cpp
|
|
COMPONENT(Request& context)
|
|
{
|
|
<>
|
|
<section class="card">
|
|
<?: component(":BODY", context.props, context) ?>
|
|
</section>
|
|
</>
|
|
}
|
|
|
|
COMPONENT:BODY(Request& context)
|
|
{
|
|
<>
|
|
<p><?= context.props["body"] ?></p>
|
|
</>
|
|
}
|
|
```
|
|
|
|
Preparing props in C++ before rendering:
|
|
|
|
```cpp
|
|
DValue props;
|
|
props["items"][0] = "alpha";
|
|
props["items"][1] = "beta";
|
|
props["items"][2] = "gamma";
|
|
|
|
String html = component("components/list", props, context);
|
|
print(html);
|
|
```
|
|
|
|
Embedding returned component markup inside a literal block:
|
|
|
|
```cpp
|
|
<>
|
|
<div class="panel">
|
|
<?: component("components/card", props, context) ?>
|
|
</div>
|
|
</>
|
|
```
|
|
|
|
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.
|
|
|
|
## Related Concepts
|
|
|
|
- PHP: reusable template partials or helper-rendered view fragments returned as strings
|
|
- JavaScript / Node.js: component render helpers, especially patterns that return markup as a string
|