MyJackfruit

Help
Browse topics · For developers

For developers

← Back to Why is the graph not a table?

How do I render a view and edit its cells?

Short answer

Open the view with GET https://id.gilb.com/base/view/<view id>, then send one changed value to POST /base/cell, each with a DPoP token.

Before you start

You may read the view, and you may write the record whose value you change. Your app holds a person's sign-in token and its key.

Words used here (7)
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
sign-in token
A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
saved view
A saved view is a record that holds a search and how to draw its result, so each opening shows what the search finds now.
field
A field is one named fact on a record, such as its title or a due date; its name comes from GilbVeda.
record's address
A record's address is the web address that names one record for good: it never changes and is never given to another record.
agent
An agent is your AI following one written procedure, its standing instructions, for one kind of work.
GilbPlatform
GilbPlatform is the service that keeps people's and organisations' data in vaults, each at its own web address.
Steps
  1. Open the view.

    Send this request with Authorization: DPoP followed by the token, and a new DPoP proof:
    GET https://id.gilb.com/base/view/<view id>

    More about this

    A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449). A saved view is a record that holds a search; each time it is opened, it shows what the search finds now, as an HTML table, only the records you may read. The table has a column for the address (@id), one for the type (@type) and one for each field. A cell that holds text, a number or true or false is marked editable: its cell, a td, carries data-entity, the record's address, and data-attribute, the field's name, such as a:title. Nothing on the page sends an edit; your app does, in step 2. With no rows the table says No rows (none match, or none readable by this principal).

  2. Send the changed value to POST /base/cell.

    Send entity, attribute, value, the new value, and agent as JSON to the host of the vault the record is in, with the token and a new proof:
    POST https://<name>.gilb.com/base/cell

    More about this

    All four fields are needed and no others are taken. agent names who makes the change; GilbPlatform writes your own address there instead, unless you are the platform owner, who runs GilbPlatform. Only that one field changes: the record's other fields stay. The answer is 200 with entity, attribute, value, the value as stored, and changed, false when the value was already that. A record you may not read answers 404 NotFound, the same as one that is not there; one you may read but not write answers 403.

Deeper

Also asked:

How do I show records as a table view and edit a cell? Open a saved view with GET https://id.gilb.com/base/view/<view id>, which shows its records as an HTML table, then send one changed value to POST /base/cell.

A view opens only on https://id.gilb.com, and only a view record saved in GilbPlatform's own vault there: GET /base/view/<view id> reads the record https://id.gilb.com/base/e/<view id>. On any other host the same request answers 404 NotFound for every id, so a view record kept in your own vault cannot be opened this way. GilbApp does not use this route. A plain Bearer token, with no proof, counts as no one here and on /base/cell. /lws, /files and many /base routes, such as /base/search, take it with no proof; the routes that sign in, trade tokens, register an app or run the AI chat do not.

Add ?format=jsonld to get the view record itself instead of the table: a:viewShows, its search; a:viewTarget, how it is drawn; and a:viewFacet, a field to group by, if it has one. Only table is built: a view whose target is dashboard or 3d shows a note saying so, then the table. Add ?as_of=<a date and time> to read the view as it was saved then; the rows are still today's. Send the time in ISO 8601, the standard form such as 2026-11-11T15:00:00Z; a value that cannot be read as a date and time answers 400 Invalid as_of '<what you sent>' — expected ISO-8601.. A query name other than format, as_of and as (as is accepted and has no effect) answers 400 querystring must NOT have additional properties, and a format other than html or jsonld answers 400 querystring/format must be equal to one of the allowed values.

POST /base/cell takes no If-Match. It reads the record, sets your one value and writes the record back whole, so a change someone else makes to another field of the same record in that moment can be undone. To change a record safely, use the If-Match write of the app API; the answer on writing only if nothing changed shows how.

The Developer Guide, GilbPlatform's guide for people who build apps on it, has no chapter on this yet; this answer is written from GilbPlatform's code.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/view.ts:1-41 (route header: GET /base/view/:id html|jsonld|as_of; POST /base/cell read-modify-write; read gate 404, write gate 403), :61-69 (query schema format html|jsonld, as_of, as; additionalProperties false), :73-83 (cell body entity, attribute, value, agent required; additionalProperties false), :101-104 (view entity = https://<ownerHost>/base/e/<id>), :106-112 (400 Invalid as_of ... expected ISO-8601.), :115 and :215 (authenticatedPrincipal: DPoP only), :132-134 (any Host but the owner host: non-disclosure 404), :141-154 (jsonld = the view entity's own document), :157-177 (HTML table), :222-229 (unreadable 404 No resource at ...), :234-237 (read current facts, set one), :245-260 (write gate; ingestState), :262-267 (200 {entity, attribute, value, changed}); src/read/view.ts:14-25 (two gates; rows only what the caller may read), :42-50 (as_of reads the definition only; rows at current state), :128-160 (a:viewShows, a:viewTarget, a:viewFacet); src/view-vocab.ts (targets table | dashboard | 3d; only table built); src/render/table.ts:83-87 (editable = text, number, boolean), :152-186 (columns @id, @type, slugs; td class cell-editable data-entity data-attribute; no hx-post on the td), :186 (No rows (none match, or none readable by this principal).), :218-233 (deferral notice, then the table); src/auth/principal.ts:197-249 (a DPoP credential, else no one), :269-280 (writeRequirer); src/write/ingest.ts:1415-1436 (a non-owner's agent is forced to its own principal); src/lws/crud.ts:33-34 and :372-374 (POST /base/cell still reads outside its transaction); src/server/app.ts:790 (registered), :244-256 (4xx body error and message). Public reads, no token, 2026-11-11: https://id.gilb.com/base/view/<made-up id> 404 HTML No view at https://id.gilb.com/base/view/...; with ?format=jsonld 404 {error:NotFound,message:No resource at ...}; https://appbuilder.gilb.com/base/view/<made-up id> 404 JSON (not the HTML page: a non-owner host); ?as_of=notadate 400 Invalid as_of 'notadate' — expected ISO-8601.; ?pod=x 400 querystring must NOT have additional properties. GilbApp ebd9415e (https://gilb.com/app/version.json read 2026-11-11): the code at ebd9415e has no base/view (GilbApp does not use the route; view.ts:125 says the same). Not checked on production: a view with rows, POST /base/cell (no write sent). Glosses shared word for word: DPoP proof, Bearer sentence. No Developer Guide chapter covers views (published chapters read 2026-11-11).

For developers

curl

open-view.sh

# Open a saved view as an HTML table, then read the view record itself.
curl -s "https://id.gilb.com/base/view/<view id>" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/view/<view id>>"
curl -s "https://id.gilb.com/base/view/<view id>?format=jsonld" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/view/<view id>>"

curl

edit-cell.sh

# Change one value of one record. Send it to the host of the vault the record is in.
curl -s "https://<name>.gilb.com/base/cell" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for POST https://<name>.gilb.com/base/cell>" \
  -H "Content-Type: application/json" \
  -d '{"entity":"<record address>","attribute":"a:title","value":"<new title>","agent":"<your address>"}'
# 200: {"entity":"<record address>","attribute":"a:title","value":"<new title>","changed":true}

TypeScript

edit-cell.ts

// Change one value through POST /base/cell. makeProof builds a new DPoP proof for one request.
type MakeProof = (method: string, url: string) => Promise<string>;

export interface CellAnswer {
  entity: string;
  attribute: string;
  value: unknown;
  changed: boolean;
}

export async function editCell(
  vaultHost: string, // such as "https://<name>.gilb.com", the host of the record's vault
  token: string,
  makeProof: MakeProof,
  cell: { entity: string; attribute: string; value: string | number | boolean; agent: string },
): Promise<CellAnswer> {
  const url = `${vaultHost}/base/cell`;
  const res = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `DPoP ${token}`,
      DPoP: await makeProof("POST", url),
      "Content-Type": "application/json",
    },
    body: JSON.stringify(cell),
  });
  if (res.status === 404) throw new Error("no such record, or you may not read it");
  if (res.status === 403) throw new Error("you may read this record but not write it");
  if (!res.ok) throw new Error(`cell edit answered ${res.status}`);
  return (await res.json()) as CellAnswer;
}

Checked against GilbApp d529620.