k.site.htmlBlocks
Multilingual HTML blocks (HtmlBlock): reading, placeholder interpolation, and updates
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
| KScript API / KView / Server scripts | Current site context; values resolve by request culture or explicit culture | Render reusable multilingual HTML snippets with {key} placeholders |
Quick Start
Add default and French values for an HTML block, ensure a fallback block with getOrAdd(), and render with {who} interpolation:
k.api.post(() => {
const name = "site-notice"
k.site.htmlBlocks.add(name, "<p>Welcome, {who}</p>")
k.site.htmlBlocks.add(name, "<p>Bienvenue, {who}</p>", "fr")
const fallback = k.site.htmlBlocks.getOrAdd("footer-note", "<p>Default Footer</p>")
return {
notice: k.site.htmlBlocks.getValue(name, { who: "Kooboo" }),
footer: fallback.getValue()
}
})Quick Reference
| Method / Property | Description | Returns |
|---|---|---|
add(name, value, culture?) | Creates or updates the block value for current or target culture | void |
getOrAdd(nameOrId, defaultValue) | Returns existing block untouched or creates one with defaultValue | HtmlBlock |
all() | Returns all multilingual HTML block wrapper objects in the site | HtmlBlock[] |
get(nameOrId) | Retrieves the multilingual HtmlBlock wrapper object | HtmlBlock | null |
getValue(nameOrId, params?) | Returns current culture HTML with optional {key} substitution | string | null |
update(name, value, culture?) | Updates the block value directly by name for current or target culture | void |
update(block) | Saves modifications made on a retrieved HtmlBlock object | void |
delete(nameOrId) | Delete entry point (no-op at runtime on current wrapper) | void |
Related APIs and Console Tools
| API / Guide | Purpose |
|---|---|
k.site.htmlBlocks | Manages reusable multilingual HTML fragments with {key} interpolation |
k.label | Manages lightweight multilingual text labels |
| HTML Blocks (CMS Console) | Edits and deletes HTML blocks in the Kooboo console |
Runtime Caveat
- Calling
k.site.htmlBlocks.delete(nameOrId)leaves the record intact in the current runtime because deletion on the multilingual wrapper does not resolve the stored item key. Manage permanent removals in the Console HTML Blocks view rather than generating disposable blocks dynamically.
Detailed Methods
add() and getOrAdd()
Write HTML block values for the current or explicit culture, or initialize a default block only if missing with getOrAdd().
| Method | Parameters | Returns | Description |
|---|---|---|---|
add(name, value) | name: string, value: string | void | Creates or updates the block value for the current request culture |
add(name, value, culture) | name: string, value: string, culture: string | void | Writes the HTML value for a specific culture (such as "en" or "fr") |
getOrAdd(nameOrId, defaultValue) | nameOrId: string, defaultValue: string | HtmlBlock | Returns the existing block without overwriting it, or inserts one with defaultValue when missing |
Returns: void or HtmlBlock
k.api.post(() => {
const block = k.site.htmlBlocks.getOrAdd("announcement", "<p>All systems operational</p>")
return {
keys: block.keys,
value: block.getValue()
}
})get() / getValue() / all()
Retrieve multilingual block wrappers or render the HTML string for the current culture.
| Method | Parameters | Returns | Description |
|---|---|---|---|
all() | None | HtmlBlock[] | Returns all multilingual HTML block objects in the site |
get(nameOrId) | nameOrId: string | HtmlBlock | null | Retrieves the multilingual wrapper (keys, length, getValue(), getCultureValue()) |
getValue(nameOrId) | nameOrId: string | string | null | Returns the HTML string for the current culture (or fallback value), or null if the block is not found |
getValue(nameOrId, params) | nameOrId: string, params: Record<string, any> | string | null | Returns the current culture (or fallback) HTML with {key} placeholders replaced from params |
Culture Fallback Behavior
When a block exists but the requested culture is missing, block.getValue(), block.getCultureValue(culture), and k.site.htmlBlocks.getValue(nameOrId) do not strictly return null. If another value exists on the block, Kooboo falls back in order to the empty key "", a culture key starting with the requested prefix, or the first non-null culture value (block.getValue() / getCultureValue() return null only when no non-null values exist). Check block.keys if you need to test whether a specific culture key is explicitly present.
Returns: HtmlBlock[], HtmlBlock | null, or string | null
k.api.get(() => {
const block = k.site.htmlBlocks.get("site-notice")
return {
totalBlocks: k.site.htmlBlocks.all().length,
keys: block ? block.keys : [],
currentValue: block ? block.getValue() : null,
frValue: block ? block.getCultureValue("fr") : null,
rendered: k.site.htmlBlocks.getValue("site-notice", { who: "Developer" })
}
})update()
Supports updating by name (for the current or specified culture) as well as modifying an object returned by get() and passing it to update(block).
| Method | Parameters | Returns | Description |
|---|---|---|---|
update(name, value, culture?) | name: string, value: string, culture?: string | void | Updates HTML content by block name for current or target culture |
update(block) | block: HtmlBlock | void | Persists the full Values snapshot captured when block was fetched |
update(block) persists a full Values snapshot
get() returns a cloned snapshot of all language values at fetch time. Calling update(block) overwrites the entire stored Values dictionary with that snapshot—so if you perform name-based update(name, ...) calls after fetching block, saving the stale block reverts them. Always re-fetch get() before mutating and passing block to update(block).
Returns: void
k.api.post(() => {
// Option 1: update by name (current culture or target culture)
k.site.htmlBlocks.update("site-notice", "<p>Notice updated</p>")
k.site.htmlBlocks.update("site-notice", "<p>Annonce mise a jour</p>", "fr")
// Option 2: re-fetch the latest object, mutate it, and save (avoids overwriting Option 1 with a stale snapshot)
const block = k.site.htmlBlocks.get("site-notice")
if (!block) return { updated: false }
block.setCultureValue("fr", "<p>Updated via object (FR)</p>")
k.site.htmlBlocks.update(block)
return {
current: k.site.htmlBlocks.getValue("site-notice"),
fr: k.site.htmlBlocks.get("site-notice")?.getCultureValue("fr")
}
})TypeScript Definitions
interface HtmlBlockRepository {
all(): HtmlBlock[];
get(nameOrId: string): HtmlBlock | null;
getValue(nameOrId: string): string | null;
getValue(nameOrId: string, params: Record<string, any>): string | null;
getOrAdd(nameOrId: string, defaultValue: string): HtmlBlock;
add(name: string, value: string): void;
add(name: string, value: string, culture: string): void;
add(block: Partial<HtmlBlock> & { name: string; value?: string }): void;
update(name: string, value: string): void;
update(name: string, value: string, culture: string): void;
update(block: HtmlBlock): void;
delete(nameOrId: string): void;
}
interface HtmlBlock {
name: string;
keys: string[];
length: number;
getValue(): string | null;
getCultureValue(culture: string): string | null;
setValue(value: string): void;
setCultureValue(culture: string, value: string): void;
}