SubNode

SubNode renders another node endpoint inside the current node tree.

Use it when one part of a page must load, reload or react independently from its parent.

Good candidates are relation tables, expensive widgets and nested workflows that should refresh without rebuilding the whole parent page.

new SubNode(
    endpoint: $resource->getFieldTableEndpoint($model->getKey(), 'roles'),
    reloadParentOnFormSuccess: true,
    nodeRequestData: ['model_id' => $model->getKey()],
    id: 'roles_table'
);

Why it exists

Normal child nodes are serialized with the parent response. A SubNode only serializes a pointer to another endpoint. React then requests that endpoint and renders the returned node.

That keeps heavy or interactive sections separate: relation tables, modal forms, widgets and nested workflows can reload without rebuilding the whole page.

Request data

nodeRequestData is always sent with requests to the subnode endpoint.

Use it for stable context such as parent model IDs or mode flags. Do not use it for data that should be validated from the form payload.

Form success flow

When a form inside the subnode succeeds, the frontend can:

• close or open overlays through closeOverlayOnFormSuccess and openOverlayOnFormSuccess;
• refetch globals with reloadGlobalsOnFormSuccess;
• navigate with navigateUrlOnFormSuccess;
• reload another node with reloadNodeByIdOnFormSuccess;
• reload the parent with reloadParentOnFormSuccess.

If the subnode has an onFormSuccess() listener, the frontend stores a temporary state key named:

{subnode_id}_form_success_event

Then it reloads the parent node. During the next backend node request, SubNode reads that state and calls:

$subNode->onFormSuccess(function (
    NodeManager $manager,
    SubNodeFormSuccessEventState $state
) {
    $payload = $state->getPayload();
    $responseData = $state->getResponseData();
});

Use this when the parent PHP layout must react to the child form result.

Generic events

Custom frontend nodes inside a subnode can emit a generic node event. If the subnode has an onEvent() listener, the state key is:

{subnode_id}_event

The backend receives it as SubNodeEventState.

$subNode->onEvent(function (NodeManager $manager, SubNodeEventState $state) {
    // React to the child event and update node state.
});

Endpoint conflict guard

The constructor rejects an endpoint that equals the current URL ending. That prevents a subnode from recursively loading the page that is already rendering it.

If that endpoint is intentional, add query parameters so the URL is no longer identical.

IDs matter

Give important subnodes a stable id.

The ID is used for form-success state, generic event state and external reloads. Without a stable ID, the default is based on the endpoint.