template-code.php
Validates portable template markup and handles code ownership rules when content enters a reusable library.
Responsibility#
Validates portable template markup and handles code ownership rules when content enters a reusable library.
This is an implementation reference for the released 0.9.13 module. Internal PHP helpers are not a compatibility promise for third-party callers. Prefer the documented REST, Abilities, theme, and filter contracts.
Related modules#
Module constants#
const CANTATA_EDIT_TEMPLATE_CODE_GRANT_TTL = 2 * DAY_IN_SECONDS;
const CANTATA_EDIT_TEMPLATE_CODE_GRANT_USES = 16;
These values describe this release. Defined configuration constants and generated identifiers can have different ownership; do not edit stored values directly without following the corresponding workflow.
Function and method reference#
cantata_edit_template_code_catalog#
function cantata_edit_template_code_catalog(): array
The installed catalog's Custom JavaScript, read from the component files themselves:
[ slug => [ 'class' => first section class, 'code' => [ "
Implementation connections: cantata_edit_component_files, cantata_edit_element_js_validate, cantata_edit_theme_uri_for_file, cantata_edit_tokens.
Source location: includes/template-code.php:35.
cantata_edit_template_code_mac#
function cantata_edit_template_code_mac( string $owner, int $user, string $slug, string $tag, string $source, int $expires, string $nonce ): string
Internal implementation helper in this module. Its name and signature identify the operation and accepted PHP values; it is not a standalone authenticated endpoint.
Implementation connections: cantata_edit_element_js_key.
Source location: includes/template-code.php:61.
cantata_edit_template_code_grant_html#
function cantata_edit_template_code_grant_html( string $html, string $slug, string $owner, int $user = 0 ): string
Put a grant on every element of one component's HTML whose code is in the installed catalog.
Implementation connections: cantata_edit_element_js_normalize, cantata_edit_template_code_catalog, cantata_edit_template_code_mac.
Source location: includes/template-code.php:66.
cantata_edit_template_code_check#
function cantata_edit_template_code_check( string $grant, string $owner, string $tag, string $source, ?string $section_classes, int $user = 0 ): string
Check one grant for an element: '' when it is honoured, else the reason (for tests and messages).
$section_classes: the class attribute of the nearest enclosing (or own)
Implementation connections: cantata_edit_template_code_catalog, cantata_edit_template_code_mac.
Source location: includes/template-code.php:89.
cantata_edit_template_code_state#
function cantata_edit_template_code_state( string $slug ): string
What /components tells the editor about one component's code: 'none' (no Custom JavaScript), 'granted' (its code is granted per page and account) or 'developer' (its code is not grantable: it arrives "Not verified" and only a developer can apply it).
Implementation connections: cantata_edit_template_code_catalog, cantata_edit_template_code_check.
Source location: includes/template-code.php:110.
cantata_edit_template_code_grant_slug#
function cantata_edit_template_code_grant_slug( string $grant ): string
The slug a well-formed grant names ('' when malformed). Integrity is checked by cantata_edit_template_code_check().
Source location: includes/template-code.php:117.
cantata_edit_template_code_regrant#
function cantata_edit_template_code_regrant( string $submitted, string $clean, string $owner ): string
The HTML field (/sanitize) returns cleaned HTML without signatures. A component's code that arrived with a grant this account may use for this owner keeps working only if the field's result carries a grant again: for each element of $clean (same order as the submission's code elements) whose submitted grant verifies for $owner and this user (MAC, expiry, installed catalog source on this tag; placement is checked again on save, where the whole page is known), a fresh grant for the same slug is set. Nothing else gets one: planted, pasted or changed code stays unverified.
Implementation connections: cantata_edit_element_js_normalize, cantata_edit_element_js_values, cantata_edit_template_code_catalog, cantata_edit_template_code_check, cantata_edit_template_code_elements, cantata_edit_template_code_grant_slug, cantata_edit_template_code_mac, cantata_edit_template_code_strip.
Source location: includes/template-code.php:128.
cantata_edit_template_code_elements#
function cantata_edit_template_code_elements( string $html ): array
Every element with non-empty Custom JavaScript in $html, in document order (the order of cantata_edit_element_js_values() for non-empty sources): [ 'tag', 'source' (canonical), 'grant', 'section' ].
Implementation connections: cantata_edit_element_js_normalize.
Source location: includes/template-code.php:162.
cantata_edit_template_code_honoured#
function cantata_edit_template_code_honoured( string $html, string $owner, string $grant_owner = '' ): array
Per element (same order as cantata_edit_template_code_elements): true when its grant is honoured. $grant_owner: the owner the grant must have been issued for, when it differs from the owner the code will be signed for. Only Kindly's REST part save passes it ('post:<the request's page>', after its own edit_post and edit_theme_options checks): a component inserted into the header from that page keeps its code, signed for the part.
Implementation connections: cantata_edit_template_code_check, cantata_edit_template_code_elements.
Source location: includes/template-code.php:198.
cantata_edit_template_code_strip#
function cantata_edit_template_code_strip( string $html ): string
Remove every grant (stored content, revisions and anything sent back to a browser never keep one).
Source location: includes/template-code.php:214.
cantata_edit_template_code_owner#
function cantata_edit_template_code_owner( ?string $set = null ): string
The owner an AI operation is building for, so a component it inserts from the catalog gets the same grants as the section picker's (it still cannot author or change a source). Set only around one operation by its caller.
Source location: includes/template-code.php:227.
cantata_edit_template_code_with_owner#
function cantata_edit_template_code_with_owner( string $owner, callable $fn )
Run $fn with the AI owner context set, and always restore it.
Implementation connections: cantata_edit_template_code_owner.
Source location: includes/template-code.php:234.