Using Custom Tables on Your Storefront

A published table can be shown on storefront pages with the Noir Custom Table component, or read
by theme JavaScript through a read-only storefront API.

Publishing a table

Tables are private by default. The storefront cannot read a private table, and asking for one returns
the same answer as a table that does not exist, so nobody can discover which tables a store has.

To publish a table, set it to Public in its storefront visibility setting in the admin (see
Managing Custom Tables in the Shopranos Admin). Publishing and unpublishing take up to 5 minutes
to reach the storefront.


Who can read it	Anyone visiting the store, signed in or not.
What they can read	Every record and every field of the table.
What they cannot do	Create, change or delete anything. The storefront is read-only.

There is no field-level visibility: publishing a table publishes all of it. Never publish cost
prices, supplier terms, personal data or anything else you would not put on a public page.

The Custom Table component (Noir)

Add the Custom Table component to a page in the page builder and configure it:

Setting	What it does
Custom table	The table to show. Only published tables are offered; a table that has since been unpublished or deleted is shown as "(not published)" or "(not found)".
Title field	The field whose value heads each entry. Only required fields are offered, so every record has a title. Leave it empty and each entry is headed by the translated Untitled text instead.
Layout	List, a responsive card grid, or Accordion, one collapsible entry per record. Accordion needs a Title field.
Records per page	Defaults to 25, up to 100. A pager appears when the table holds more records.
Sort by / Sort direction	Orders the records by one field. Only fields that are both required and queryable are offered. Without one, the newest records come first.
Filter by page entity	No filter shows the whole table. Current product, Current brand, Current category and Current collection show only the records linked to the entity being viewed. A page without that entity shows nothing.
Fields	The fields shown under the title, in order, each with an optional translated label. Leave it empty to show every field.

The component's model and template are documented in
Noir › Components › CustomTable.

How it behaves:

Server-rendered. Records are in the page HTML, so they are indexed by search engines and the
page does not flash empty while loading.

Never breaks the page. If the table is private, unknown or temporarily unreachable, the
component renders nothing.

Labels fall back to the field name, tidied up: wash_temp is shown as "Wash temp". Set a label
when that reads badly.

Yes / No values are translated into the shopper's language, and empty values are left out.

A sort that is no longer valid is ignored. If the sort field is later made optional or
non-queryable, the records are shown in the default order. Choose a valid field to restore sorting.

Paging is a normal page load with the page number in the URL, so every page can be indexed,
bookmarked and shared. Each component on a page has its own page parameter. Deep pages load more
slowly, so for tables with more than a few dozen pages, give shoppers search or filters instead.

Only Noir has this component; Kitchenware has no equivalent.

Custom views

For a different presentation, such as a map or a comparison grid, a theme developer can add a view
next to Default under Components/CustomTable/ and pick it in the page builder. The view must be
uploaded to the store's theme, for example with the Shopranos VS Code extension, before the page
builder offers it. The view receives the records already prepared by the server and can reshape them
and add client-side behaviour.

Prefer a custom view over fetching data in JavaScript: records rendered on the server are visible to
search engines, records fetched by a script are not.

The storefront API

Theme JavaScript can read published tables from the store's own address, for example
https://yourstore.shopranos.eu. The API is anonymous and read-only. The store is worked out from the
address, so there is nothing to send to identify it, and no request can reach another store's data.

Use it when the server-rendered component cannot do the job: a search box over thousands of records,
"load more", or a map that loads the shops in view.

List records

GET https://yourstore.shopranos.eu/api/custom-tables/{tableId}/records

Parameter	Description
`filter`	`field:operator:value` on a queryable field. Repeat it for more filters; all must match. See Designing Fields, Queries and Links for the operators.
`linkType`, `linkId`	Only records linked to this entity, for example `brand` and the brand's id. Send both together; sending only one is rejected and returns an empty page.
`page`	Page number. Defaults to 1.
`pageSize`	Records per page, from 1 to 100. Defaults to 25; a value outside that range also gives 25.
`sort`	`field:asc` or `field:desc`. The field must be required and queryable.

Response:

{
  "records": [
    {
      "id": "6f1c2d3e-0000-4000-8000-000000000001",
      "tableId": "store_locations",
      "data": {
        "code": "ATH01",
        "name": "Athens Centre",
        "city": "Athens",
        "is_pickup_point": true
      },
      "links": null,
      "updateDate": "2026-01-22T09:30:00Z"
    }
  ],
  "totalCount": 1
}

data uses the field identifiers exactly as declared. Records saved before a field was removed may
still carry its value.

links is a list of { "type", "id" } pairs, or null.

Work out the number of pages from totalCount and the page size the response actually used, not
the one you asked for.

Get one record

GET https://yourstore.shopranos.eu/api/custom-tables/{tableId}/records/{recordId}

Returns the record, or 404 when it does not exist, belongs to another table, or its table is not
published. The three cases are deliberately indistinguishable.

Examples

Brand stories for the brand being viewed, filtered and sorted:

Shops in one city:

Empty results

The list endpoint never returns an error for a bad request; it returns an empty page instead. An
empty result can mean:

the table is not published, or does not exist;

a filter names a field that is not queryable, or a value that does not match the field's type;

there are simply no matching records.

If your section stays empty, check that the table is published first, then check your filters. An
invalid sort is dropped and the records are returned in the default order.

Caching

Storefront reads are cached for up to 5 minutes for each table and query.

Saving records in the admin normally refreshes the storefront within seconds; the 5 minutes is the
upper limit.

A CSV import refreshes the storefront once, after the whole import.

Unpublishing stops the storefront serving the table within the same window.

Unpublishing does not remove copies already served to visitors, CDNs or search engines. If something
was published by mistake, delete the records as well.

Using Custom Tables on Your Storefront

Publishing a table#

The Custom Table component (Noir)#

Custom views#

The storefront API#

List records#

Get one record#

Examples#

Empty results#

Caching#