Skip to content

k.site.htmlBlocks ​

Multilingual HTML blocks (HtmlBlock): reading, placeholder interpolation, and updates

Execution ContextPrerequisitesTypical Use
KScript API / KView / Server scriptsCurrent site context; values resolve by request culture or explicit cultureRender 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:

js
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 / PropertyDescriptionReturns
add(name, value, culture?)Creates or updates the block value for current or target culturevoid
getOrAdd(nameOrId, defaultValue)Returns existing block untouched or creates one with defaultValueHtmlBlock
all()Returns all multilingual HTML block wrapper objects in the siteHtmlBlock[]
get(nameOrId)Retrieves the multilingual HtmlBlock wrapper objectHtmlBlock | null
getValue(nameOrId, params?)Returns current culture HTML with optional {key} substitutionstring | null
update(name, value, culture?)Updates the block value directly by name for current or target culturevoid
update(block)Saves modifications made on a retrieved HtmlBlock objectvoid
delete(nameOrId)Delete entry point (no-op at runtime on current wrapper)void

Related APIs and Console Tools

API / GuidePurpose
k.site.htmlBlocksManages reusable multilingual HTML fragments with {key} interpolation
k.labelManages 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().

MethodParametersReturnsDescription
add(name, value)name: string, value: stringvoidCreates or updates the block value for the current request culture
add(name, value, culture)name: string, value: string, culture: stringvoidWrites the HTML value for a specific culture (such as "en" or "fr")
getOrAdd(nameOrId, defaultValue)nameOrId: string, defaultValue: stringHtmlBlockReturns the existing block without overwriting it, or inserts one with defaultValue when missing

Returns: void or HtmlBlock

js
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.

MethodParametersReturnsDescription
all()NoneHtmlBlock[]Returns all multilingual HTML block objects in the site
get(nameOrId)nameOrId: stringHtmlBlock | nullRetrieves the multilingual wrapper (keys, length, getValue(), getCultureValue())
getValue(nameOrId)nameOrId: stringstring | nullReturns 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 | nullReturns 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

js
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).

MethodParametersReturnsDescription
update(name, value, culture?)name: string, value: string, culture?: stringvoidUpdates HTML content by block name for current or target culture
update(block)block: HtmlBlockvoidPersists 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

js
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 ​

ts
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;
}