k.site.formValues
Query, create, update, and delete form submission records (FormValue)
| Execution Context | Prerequisites | Typical Use |
|---|---|---|
| KScript API / Server scripts | Current site context; adding records requires a target formId | Read, store, update, and delete site FormValue submissions |
Quick Start
Create a base record with add({ name, formId }), retrieve it from all(), assign keys on values, and persist with update():
js
k.api.post(() => {
const name = "submission-" + Date.now()
const formId = k.request.form.formId
k.site.formValues.add({ name, formId })
const created = k.site.formValues.all().find((x) => x.name === name)
created.values["email"] = k.request.form.email
created.values["topic"] = k.request.form.topic
k.site.formValues.update(created)
const saved = k.site.formValues.get(created.id)
return { id: String(saved.id), values: saved.values }
})Quick Reference
| Method / Property | Description | Returns |
|---|---|---|
all() | Returns all stored form submission records | FormValue[] |
get(nameOrId) | Retrieves a form submission record by GUID id | FormValue | null |
add(formValue) | Creates a base submission record (avoid nested values here) | void |
update(formValue) | Persists changes to values and record metadata | void |
delete(nameOrId) | Deletes a form submission record by id | void |
getLogs(nameOrId) | Returns null because form values do not keep change logs | ChangeLog[] | null |
getByLog(logId) | Restores a log version when available | FormValue | null |
Runtime Notes
- Do not pass a nested
valuesobject directly tok.site.formValues.add({ name, formId, values: { ... } }), which throws a type-conversion error when binding nested fields. Instead, create the record withadd({ name, formId }), retrieve it fromall(), assign entries onitem.values["field"], and callupdate(item). FormValuegenerates a random GUIDid; use thatidwithget(id)anddelete(id).- Form submissions are not versioned in the change log;
getLogs(id)returnsnull.
Detailed Methods
all() / get()
List all form submission records or retrieve one by its GUID id.
| Method | Parameters | Returns | Description |
|---|---|---|---|
all() | None | FormValue[] | Returns all stored form submission records |
get(nameOrId) | nameOrId: string | FormValue | null | Retrieves a form submission record by id |
Returns: FormValue[] or FormValue | null
js
k.api.get(() => {
const items = k.site.formValues.all()
return {
count: items.length,
latest: items.slice(0, 5).map((item) => ({
id: String(item.id),
name: item.name,
formId: String(item.formId),
values: item.values
}))
}
})add() and update()
Create the base record first, populate values, and persist via update().
| Parameter | Type | Required | Description |
|---|---|---|---|
formValue | { name?: string; formId: string } / FormValue | Yes | Pass name and formId to add(); assign values entries then pass to update() |
Returns: void
js
k.api.post(() => {
const item = k.site.formValues.get(k.request.form.id)
if (!item) return { found: false }
item.values["status"] = "reviewed"
k.site.formValues.update(item)
return { updated: true }
})delete() and getLogs()
Delete a submission by id or check log behavior.
| Method | Parameters | Returns | Description |
|---|---|---|---|
delete(nameOrId) | nameOrId: string | void | Deletes the form submission record by id |
getLogs(nameOrId) | nameOrId: string | ChangeLog[] | null | Returns null because form values do not store repository change logs |
getByLog(logId) | logId: number | FormValue | null | Looks up a log version when available |
Returns: void / ChangeLog[] | null / FormValue | null
js
k.api.post(() => {
const id = k.request.form.id
k.site.formValues.delete(id)
return { deleted: !k.site.formValues.get(id) }
})TypeScript Definitions
ts
interface FormValuesRepository {
all(): FormValue[];
get(nameOrId: string): FormValue | null;
add(formValue: { name?: string; formId: string }): void;
update(formValue: FormValue): void;
delete(nameOrId: string): void;
getLogs(nameOrId: string): ChangeLog[] | null;
getByLog(logId: number): FormValue | null;
}
interface FormValue {
id: string;
formId: string;
name: string;
values: Record<string, string>;
creationDate: Date;
lastModified: Date;
lastModifyTick: number;
}