RESTful table

Summary

An editable CRUD table bound to a REST endpoint: GET to load, POST to create, PUT to update, DELETE to remove. Entries must carry an id; server responses may echo the stored entry, and when they do the echoed values win — so server-computed fields come back into the row. Layers on .soma-table: click a row to edit it inline, the footer row creates, per-row actions appear on hover or keyboard focus.

When to use

Examples

Endpoint contract

The component speaks plain fetch with JSON both ways (Content-Type and Accept: application/json). All URLs come from resources:

Failure semantics: a non-2xx on the list GET (the initial load or a .reload()) renders a "Failed to load" row with the status message; a failed write (POST/PUT/DELETE) leaves the form row in place with nothing applied locally. The operator's input is not lost, and no event fires. Empty response bodies are fine (they parse to null — no echo).

Server-echo semantics

After a create or update the row is rebuilt from { …localValues, …serverEcho }: whatever the server returns overrides what was typed. That is how a created entry gets its server-assigned id (without it, edit and delete cannot target the row), and how server-computed fields (normalised names, timestamps, derived state) land back in the table without a reload. An endpoint that echoes nothing works too; the table then shows the values as typed.

Keyboard

HTML

Author an empty table. The component builds header, rows and forms (there is nothing else to write by hand):

<table id="devices"></table>

<script>
  Soma.restfulTable('#devices', {
    resources: {
      all:  '/api/devices',   // GET list — a URL, or fn(callback)
      self: '/api/devices',   // base for POST / PUT/{id} / DELETE/{id}
    },
    columns: [
      { id: 'name', header: 'Name' },
      { id: 'ip',   header: 'IP address', allowEdit: false },
      { id: 'state', header: 'State',
        readView: (value) => `<span class="soma-badge">${value}</span>` },
    ],
    allowCreate: true, allowEdit: true, allowDelete: true,
  });
</script>

CSS classes

All added by the component alongside .soma-table; listed for theming reference.

JavaScript

Constructor + options

Instance methods

Events

All four are bubbling CustomEvents dispatched on the table element. This component has no .on() helper — listen with plain addEventListener, on the table or delegated higher up:

const table = document.querySelector('#devices');

table.addEventListener('soma-restfultable-row-added', (e) => {
  Soma.toast({ body: `Created "${e.detail.entry.name}"`, appearance: 'success' });
});

// The events bubble — one document-level listener can audit every table:
document.addEventListener('soma-restfultable-row-removed', (e) => {
  console.log('removed', e.detail.entry.id, 'from', e.target.id);
});

resources.all as a function (for auth headers, envelope unwrapping, or a non-HTTP source):

Soma.restfulTable('#devices', {
  resources: {
    all: (callback) => {
      fetch('/api/devices?site=prague', { headers: { Authorization: token } })
        .then((res) => res.json())
        .then((page) => callback(page.items));   // hand back the entries ARRAY
    },
    self: '/api/devices',
  },
  columns: [{ id: 'name', header: 'Device' }],
});

Tuning the create flow — top insertion, focus retention, and custom empty text (the "Rapid entry" demo above):

Soma.restfulTable('#tags', {
  resources: { all: '/api/tags', self: '/api/tags' },
  columns: [
    { id: 'name', header: 'Tag' },
    { id: 'color', header: 'Color' },
  ],
  createPosition: 'top',   // new entries land first in the list
  autoFocus: true,         // focus returns to the create row after each add
  noEntriesMsg: 'No tags yet — add the first below.',
});

The live examples above, exactly as this page wires them (the fetch stub stands in for a real REST backend):

// Demo backend: an in-memory store behind a fetch stub — the component
// speaks plain fetch, so point `resources` at your real endpoint instead.
const store = [
  { id: 1, name: 'switch-core-1', ip: '10.0.0.11', site: 'Seattle', state: 'healthy' },
  { id: 2, name: 'switch-edge-4', ip: '10.0.0.24', site: 'Denver', state: 'degraded' },
];
// … window.fetch stub answering GET/POST/PUT/DELETE on /api/devices
//   and /api/tags …

// readView output is raw HTML — escape anything user-supplied.
const esc = (s) => {
  const div = document.createElement('div');
  div.textContent = s == null ? '' : String(s);
  return div.innerHTML;
};
const STATE_BADGE = {
  healthy: 'soma-badge-success',
  degraded: 'soma-badge-warning',
  failing: 'soma-badge-danger',
};

Soma.restfulTable('#rt-demo', {
  resources: { all: '/api/devices', self: '/api/devices' },
  columns: [
    { id: 'name', header: 'Device' },
    { id: 'ip', header: 'IP address' },
    { id: 'site', header: 'Site', allowEdit: false },
    { id: 'state', header: 'State',
      readView: (value) => `<span class="soma-badge ${STATE_BADGE[value] || ''}">${esc(value)}</span>` },
  ],
});

// Rapid entry: create at the top, keep focus in the create row.
Soma.restfulTable('#rt-top', {
  resources: { all: '/api/tags', self: '/api/tags' },
  columns: [
    { id: 'name', header: 'Tag' },
    { id: 'color', header: 'Color' },
  ],
  createPosition: 'top',
  autoFocus: true,
  noEntriesMsg: 'No tags yet — add the first below.',
});

// Read-only variant: same component, all write switches off; the list
// comes from fn(callback) instead of a URL.
const ro = Soma.restfulTable('#rt-readonly', {
  resources: { all: (cb) => cb(store) },
  columns: [
    { id: 'name', header: 'Device' },
    { id: 'ip', header: 'IP address' },
    { id: 'site', header: 'Site' },
    { id: 'state', header: 'State' },
  ],
  allowCreate: false, allowEdit: false, allowDelete: false,
});
document.querySelector('#rt-reload').addEventListener('click', () => ro.reload());

Localisation

The generated button labels (Edit, Delete, Update, Add, Cancel), the assistive operations-column header and the default loading/empty messages are localised via Soma.i18n: the restfulTable.edit / .delete / .update / .add / .cancel / .operations / .loading / .noEntries keys. Override strings (or switch locale) BEFORE the table initialises — strings are read at render time:

Soma.i18n({
  'restfulTable.add': 'Create',
  'restfulTable.noEntries': 'Nothing here yet',
});
Soma.restfulTable('#devices', { /* … */ });

See i18n for locale packs and the full API. Per-instance, noEntriesMsg / loadingMsg win over the localised defaults.