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 Context | Prerequisites | Typical Use |
|---|---|---|
| KScript API / KView / Server scripts | Current 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:
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 / Property | Description | Returns |
|---|---|---|
k.site.info | Active request/site metadata, custom settings, and absolute URL builder | InfoModel |
k.site.webSite | Read-only site configuration and feature-flag inspection object | WebSiteInspection |
k.site.settings | Lookup built-in site settings by name or indexer | kCoreSettings |
k.site.multilingual | Configured cultures and localized URL generation | Multilingual |
k.site.search | Site-wide full-text search (findAll) and custom Lucene index folders (on) | Search |
k.site.version | Versioned URLs for images, JS, and CSS based on browser cache flags | FileVersion |
k.site.diskSpace | Site repository disk usage, edit counts, and top storage items | DiskSpace |
k.site.helper | Site root URL, page preview URLs, and inline-edit redirect URLs | SiteHelper |
Read-Only Guidance and Runtime Collection Types
- Treat
k.site.webSiteas a read-only inspection object. Do not mutate its properties from runtime request scripts. info.domains,search.findAll(...), anddiskSpace.getSiteSize().repositorySizereturn iterable lists at runtime (Array.isArray(...)isfalse); iterate over them withfor...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.
| Method | Parameters | Returns | Description |
|---|---|---|---|
makeAbsUrl(relativePath) | relativePath: string | string | Resolves a relative path into a full URL using the site baseUrl |
updateSetting(key, value) | key: string, value: string | void | Updates and persists a custom setting key/value pair on the site |
removeSetting(key) | key: string | void | Removes a key from the site's custom settings |
setDomain(fulldomain) | fulldomain: string | void | Binds a domain to the current site (administrative scripts only) |
enableSsl(fulldomain) | fulldomain: string | void | Enables SSL for a bound domain (administrative scripts only) |
Returns: Site context values on read properties/URL helpers (void on configuration mutation methods)
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.
| Member | Parameters | Returns | Description |
|---|---|---|---|
get(name) | name: string | any | null | Retrieves a built-in site setting object by name |
[key] | key: string | any | null | Indexer access to a built-in site setting object |
Returns: Setting object or null
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.
| Member | Parameters | Returns | Description |
|---|---|---|---|
currentCulture | — | string | Active culture code for the current request (for example, "en", "zh") |
cultures | — | Record<string, string> | null | Configured site cultures map (for example, { en: "English", zh: "中文" }) |
currentURLs() | None | SiteMultilingualInfo[] | Returns localized URL entries for the current request path across all configured cultures |
getURLs(relativeUrl) | relativeUrl: string | SiteMultilingualInfo[] | Generates localized URL entries for the specified relativeUrl |
getLangUrl(relativeUrl, culture) | relativeUrl: string, culture: string | string | Generates the URL for relativeUrl in the target culture |
getUrl(relativeUrl) | relativeUrl: string | string | Formats relativeUrl for the active request culture |
Returns: Culture code, localized URL string, or SiteMultilingualInfo[]
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")
}
})search
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
KFullTextSearchindex for indexing and querying custom documents.
| Method | Parameters | Returns | Description |
|---|---|---|---|
findAll(keyword, options?) | keyword: string, options?: SearchOptions | SearchResult[] | Queries the site-wide full-text search index (iterable list) |
on(folderName) | folderName: string | KFullTextSearch | Opens a custom isolated Lucene index folder |
Returns: SearchResult[] (iterable list) or KFullTextSearch
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)):
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.
| Method | Parameters | Returns | Description |
|---|---|---|---|
imageVersionSrc(imgSrc) | imgSrc: string | string | Appends a version query when image browser cache is enabled with imageCacheDays <= 0 |
jsVersionSrc(src) | src: string | string | Appends a version query when JS/CSS browser cache is enabled |
cssVersionSrc(src) | src: string | string | Appends a version query when JS/CSS browser cache is enabled |
Returns: string
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).
| Method | Parameters | Returns | Description |
|---|---|---|---|
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
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).
| Method | Parameters | Returns | Description |
|---|---|---|---|
siteUrl() | None | string | Returns the current site base URL |
pagePreviewUrl(pageId) | pageId: string | string | null | Builds the preview URL for a page ID |
pageInlineEditUrl(pageId) | pageId: string | string | null | Builds the inline-editor URL for a page ID |
Returns: string or null
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
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;
}