Skip to content

k.site Context and Built-in Helpers ​

Site info, read-only configuration inspection, multilingual URLs, full-text search, asset cache versions, disk space metrics, and helper URLs

Execution ContextPrerequisitesTypical Use
KScript API / KView / Server scriptsCurrent site context (search.findAll requires full-text search enabled)Inspect site settings and domains, generate localized or versioned URLs, run search, and check disk usage

Quick Start ​

Inspect the active site name, culture, baseUrl, display metadata, and total disk usage in one call:

js
k.api.get(() => {
    const info = k.site.info
    const site = k.site.webSite
    return {
        name: info.name,
        displayName: site.displayName,
        currentCulture: info.culture,
        baseUrl: info.baseUrl,
        absApiUrl: info.makeAbsUrl("/api/health"),
        totalBytes: k.site.diskSpace.getSiteSize().total
    }
})

Quick Reference ​

Method / PropertyDescriptionReturns
k.site.infoActive request/site metadata, custom settings, and absolute URL builderInfoModel
k.site.webSiteRead-only site configuration and feature-flag inspection objectWebSiteInspection
k.site.settingsLookup built-in site settings by name or indexerkCoreSettings
k.site.multilingualConfigured cultures and localized URL generationMultilingual
k.site.searchSite-wide full-text search (findAll) and custom Lucene index folders (on)Search
k.site.versionVersioned URLs for images, JS, and CSS based on browser cache flagsFileVersion
k.site.diskSpaceSite repository disk usage, edit counts, and top storage itemsDiskSpace
k.site.helperSite root URL, page preview URLs, and inline-edit redirect URLsSiteHelper

Read-Only Guidance and Runtime Collection Types

  • Treat k.site.webSite as a read-only inspection object. Do not mutate its properties from runtime request scripts.
  • info.domains, search.findAll(...), and diskSpace.getSiteSize().repositorySize return iterable lists at runtime (Array.isArray(...) is false); iterate over them with for...of.

Detailed Modules ​

info and webSite (Read-Only) ​

k.site.info exposes the site's active culture, name, baseUrl, host, domains, custom settings, and URL helper; k.site.webSite provides read-only access to site feature flags and metadata.

MethodParametersReturnsDescription
makeAbsUrl(relativePath)relativePath: stringstringResolves a relative path into a full URL using the site baseUrl
updateSetting(key, value)key: string, value: stringvoidUpdates and persists a custom setting key/value pair on the site
removeSetting(key)key: stringvoidRemoves a key from the site's custom settings
setDomain(fulldomain)fulldomain: stringvoidBinds a domain to the current site (administrative scripts only)
enableSsl(fulldomain)fulldomain: stringvoidEnables SSL for a bound domain (administrative scripts only)

Returns: Site context values on read properties/URL helpers (void on configuration mutation methods)

js
k.api.get(() => {
    const info = k.site.info
    const site = k.site.webSite
    const domains = []
    if (info.domains) {
        for (const d of info.domains) {
            domains.push(d)
        }
    }
    return {
        name: info.name,
        displayName: site.displayName,
        defaultCulture: site.defaultCulture,
        currentCulture: info.culture,
        baseUrl: info.baseUrl,
        host: info.host,
        version: info.version,
        domains,
        absApiUrl: info.makeAbsUrl("/api/health")
    }
})

settings ​

Looks up built-in site configuration objects by key name via .get(name) or bracket access (k.site.settings["SettingName"]). Unrecognized setting names return null.

MemberParametersReturnsDescription
get(name)name: stringany | nullRetrieves a built-in site setting object by name
[key]key: stringany | nullIndexer access to a built-in site setting object

Returns: Setting object or null

js
k.api.get(() => {
    const missing = k.site.settings.get("nonexistent-setting-key")
    const jwtByGet = k.site.settings.get("JwtSetting")
    const jwtByIndex = k.site.settings["JwtSetting"]
    return {
        missingIsNull: missing === null || missing === undefined,
        jwtSettingName: jwtByGet ? jwtByGet.name : null,
        sameName: jwtByIndex ? jwtByIndex.name === jwtByGet?.name : false
    }
})

multilingual ​

Reads active site cultures and computes localized URLs. Note that the URL property on each item returned by currentURLs() and getURLs() uses uppercase URL.

MemberParametersReturnsDescription
currentCulture—stringActive culture code for the current request (for example, "en", "zh")
cultures—Record<string, string> | nullConfigured site cultures map (for example, { en: "English", zh: "中文" })
currentURLs()NoneSiteMultilingualInfo[]Returns localized URL entries for the current request path across all configured cultures
getURLs(relativeUrl)relativeUrl: stringSiteMultilingualInfo[]Generates localized URL entries for the specified relativeUrl
getLangUrl(relativeUrl, culture)relativeUrl: string, culture: stringstringGenerates the URL for relativeUrl in the target culture
getUrl(relativeUrl)relativeUrl: stringstringFormats relativeUrl for the active request culture

Returns: Culture code, localized URL string, or SiteMultilingualInfo[]

js
k.api.get(() => {
    const m = k.site.multilingual
    return {
        currentCulture: m.currentCulture,
        cultures: m.cultures,
        currentURLs: m.currentURLs().map((u) => ({
            key: u.key,
            name: u.name,
            URL: u.URL,
            isActive: u.isActive
        })),
        aboutEn: m.getLangUrl("/about", "en"),
        aboutCurrent: m.getUrl("/about")
    }
})

Provides both site-wide search (findAll(keyword, options?)) and isolated custom Lucene index folders (on(folderName)):

  • Site-wide search: queries the site search index when full-text search is enabled (empty keywords return an empty list; iterate with for...of).
  • Custom index folders: opens a scoped KFullTextSearch index for indexing and querying custom documents.
MethodParametersReturnsDescription
findAll(keyword, options?)keyword: string, options?: SearchOptionsSearchResult[]Queries the site-wide full-text search index (iterable list)
on(folderName)folderName: stringKFullTextSearchOpens a custom isolated Lucene index folder

Returns: SearchResult[] (iterable list) or KFullTextSearch

js
k.api.get(() => {
    const hits = k.site.search.findAll("kooboo", {
        maxCount: 5,
        includeObject: false,
        highlightPreTag: "<b>",
        highlightPostTag: "</b>",
        fragmentMaxSize: 100
    })
    const results = []
    for (const item of hits) {
        results.push({ title: item.title, url: item.url, scope: item.scope })
    }
    return { count: results.length, results }
})

Custom Lucene folder indexing (search.on(folderName)):

js
k.api.post(() => {
    const fts = k.site.search.on("products_fts")
    fts.addDocument("sku-100", "kooboo modular cms routing")
    const found = fts.findAll("routing", 10)
    const firstKey = found.scoreDocs.length ? fts.getMetaKey(found.scoreDocs[0].doc) : null

    fts.deleteDocument("sku-100")
    return {
        totalHits: found.totalHits,
        firstKey
    }
})

score vs scope field difference

Site-wide k.site.search.findAll(...) returns SearchResult items with a scope field, whereas custom Lucene k.site.search.on(folderName).findAll(keyword, top) returns Lucene TopDocs whose scoreDocs items expose doc and score (not scope).

version ​

Appends cache-busting ?version=... query parameters to static asset paths when browser caching is active on the site; otherwise returns the input URL unchanged.

MethodParametersReturnsDescription
imageVersionSrc(imgSrc)imgSrc: stringstringAppends a version query when image browser cache is enabled with imageCacheDays <= 0
jsVersionSrc(src)src: stringstringAppends a version query when JS/CSS browser cache is enabled
cssVersionSrc(src)src: stringstringAppends a version query when JS/CSS browser cache is enabled

Returns: string

js
k.api.get(() => {
    const v = k.site.version
    return {
        img: v.imageVersionSrc("/logo.png"),
        js: v.jsVersionSrc("/app.js"),
        css: v.cssVersionSrc("/site.css")
    }
})

diskSpace ​

Reports repository disk consumption and edit log counts (getSiteSize().repositorySize is an iterable list so iterate with for...of; getCommonStoreSize() returns the top 8 ICoreObject stores in storeItem plus total active repository and edit log size, while visitorLogSize is currently unused and always null).

MethodParametersReturnsDescription
getSiteSize()None{ total, repositoryEditCount, repositorySize }Reports repository byte sizes and edit counts
getCommonStoreSize()None{ storeItem, visitorLogSize, totalSize, total }Reports the top 8 ICoreObject stores and total repository + edit log size (visitorLogSize is unused and always null)

Returns: Disk space summary object

js
k.api.get(() => {
    const size = k.site.diskSpace.getSiteSize()
    const common = k.site.diskSpace.getCommonStoreSize()
    let repoCount = 0
    for (const _ of size.repositorySize) {
        repoCount++
    }
    return {
        totalBytes: size.total,
        repoCount,
        editCount: size.repositoryEditCount,
        totalSizeText: common.totalSize,
        topStores: common.storeItem.map((s) => ({
            name: s.name,
            itemCount: s.itemCount,
            sizeString: s.sizeString
        }))
    }
})

helper ​

Builds the site base URL as well as page preview and inline-editor URLs (missing pages return null).

MethodParametersReturnsDescription
siteUrl()NonestringReturns the current site base URL
pagePreviewUrl(pageId)pageId: stringstring | nullBuilds the preview URL for a page ID
pageInlineEditUrl(pageId)pageId: stringstring | nullBuilds the inline-editor URL for a page ID

Returns: string or null

js
k.api.get(() => {
    const h = k.site.helper
    const pages = k.site.pages.all()
    const pageId = pages.length ? String(pages[0].id) : ""
    return {
        siteUrl: h.siteUrl(),
        previewUrl: pageId ? h.pagePreviewUrl(pageId) : null,
        inlineEditUrl: pageId ? h.pageInlineEditUrl(pageId) : null
    }
})

TypeScript Definitions ​

Show full TypeScript definitions
ts
interface InfoModel {
  culture: string;
  name: string;
  setting: Record<string, string>;
  user: UserModel;
  baseUrl: string;
  version: number;
  domains: string[];
  host: string;
  page: Page | null;
  makeAbsUrl(relativePath: string): string;
  updateSetting(key: string, value: string): void;
  removeSetting(key: string): void;
  enableSsl(fulldomain: string): void;
  setDomain(fulldomain: string): void;
}

interface WebSiteInspection {
  readonly id: string;
  readonly name: string;
  readonly displayName: string;
  readonly defaultCulture: string;
  readonly culture: Record<string, string>;
  readonly published: boolean;
  readonly status: any;
  readonly enableMultilingual: boolean;
  readonly enableSitePath: boolean;
  readonly enableFrontEvents: boolean;
  readonly enableFullTextSearch: boolean;
  readonly enableImageBrowserCache: boolean;
  readonly imageCacheDays: number;
  readonly enableJsCssBrowerCache: boolean;
  readonly ssoLogin: boolean;
}

interface kCoreSettings {
  get(name: string): any;
  [key: string]: any;
}

interface SiteMultilingualInfo {
  key: string;
  name: string;
  URL: string;
  isActive: boolean;
}

interface Multilingual {
  currentCulture: string;
  cultures: Record<string, string> | null;
  currentURLs(): SiteMultilingualInfo[];
  getURLs(relativeUrl: string): SiteMultilingualInfo[];
  getLangUrl(relativeUrl: string, culture: string): string;
  getUrl(relativeUrl: string): string;
}

interface SearchOptions {
  highlightPreTag?: string;
  highlightPostTag?: string;
  folders?: string[];
  skipCount?: number;
  maxCount?: number;
  fragmentMaxSize?: number;
  includeObject?: boolean;
}

interface SearchResult {
  id: string;
  type: string;
  title: string;
  object: any;
  summary: string;
  url: string;
  additional: Record<string, any>;
  scope: number;
}

interface KFullTextSearch {
  addDocument(metaKey: string, body: string): void;
  deleteDocument(metaKey: string): void;
  deleteDocuments(): void;
  findAll(keyword: string, top: number): { totalHits: number; scoreDocs: { doc: number; score: number }[] };
  getMetaKey(doc: number): string;
}

interface FileVersion {
  imageVersionSrc(imgSrc: string): string;
  jsVersionSrc(src: string): string;
  cssVersionSrc(src: string): string;
}

interface DiskSpace {
  getSiteSize(): {
    total: number;
    repositoryEditCount: number;
    repositorySize: { name: string; length: number; itemCount: number }[];
  };
  getCommonStoreSize(): {
    storeItem: { name: string; itemCount: number; size: number; sizeString: string }[];
    /** Currently unused; always null */
    visitorLogSize: string | null;
    totalSize: string;
    total: number;
  };
}

interface SiteHelper {
  siteUrl(): string;
  pagePreviewUrl(pageId: string): string | null;
  pageInlineEditUrl(pageId: string): string | null;
}