Skip to main content

Show a view as a grid

Goal​

Put a list of records on your portal without drawing the list — the platform's own grid, with the columns a view decides.

Before you start​

  • A view on the table, with the columns you want visitors to see. This is where the headings, the widths and the order come from.
  • A Custom API that lists the table, ticked in the portal's What it can read. See Publish an app as a portal for how that list works.

Steps​

  1. In the app designer, drop Components → Table view or form where the list should go.
  2. On the Screen tab, pick the Table. Leave View on The table's default, or pick one of the table's views.
  3. Pick the Custom API (portal) the rows come through — Notices (api:par_list_notices@1), say. Only contracts that answer a GET are offered, because a grid only reads.
  4. Publish, and open the portal.

That is the whole of it on the drawing side. You do not choose columns here — the view already did.

A grid asks two questions, and the two boxes answer one each. The table and the view decide what to show — the headings, the widths, the order — and the platform works those out before the page is served, so nothing about your table's shape reaches a public browser. The Custom API decides what rows, because on a portal every read goes through a contract you wrote. In the app list the API box is ignored and the table supplies both.

What the API has to do​

Page, and say how many there are. The grid asks for a page at a time and reads total to know whether there is a next one:

var page = runQuery({
  entity: 'par_notice',
  select: ['par_name', 'par_category', 'par_published_on'],
  order: [{ field: 'par_published_on', descending: true }],
  top: num(getInput('top')),
  skip: num(getInput('skip'))
});

setOutput('rows', page);
setOutput('total', page.length());

Without total the pager cannot tell a last page from a full one, and will offer a Next that leads nowhere.

A column the view has and the API does not return​

It shows a dash in every row. The view decides the headings; the API decides what is in each row, and a field its select leaves out is not in the row. So adding a column is two edits: the column to the view, and the field to the API's select.

That is deliberate rather than an oversight. The view is shared with the app inside the platform, and adding a column there for your own people should not publish that field to strangers. What leaves the platform is what the API selects.

A grid with no API does not appear at all​

Leave Custom API (portal) empty, or name one the portal has not been given, and the grid is not served — you get no grid rather than headings above an empty body.

That is on purpose, and it is the same rule the rest of the portal obeys: an empty grid reads as there are no records, which is a different claim from this portal was never allowed to show them. Falling back to reading the table directly would be worse still — it is exactly the door §6.11.3 closes, arriving by another route.

Where the columns come from, and when​

From the view, when the portal is served. Edit the view, reload the portal, and the columns change — there is nothing to re-publish. That is also why a portal page never asks the platform what a view contains: the answer arrives with the page.

If you name a view and later delete it, the grid says it is unavailable rather than quietly falling back to the default. You chose those columns, and a different set appearing with no warning on a public page is worse than a grid that is honest about being broken.

What a visitor can and cannot do with it​

They can read it and page through it. They cannot select rows, click into a record, or use a command bar — none of those exist here. Every one of them is an action on a record, and what a stranger may do to a record is your Custom API's decision, not a grid's.

If you want a visitor to do something, draw a button and give it its own allow-list row.

Not available on a portal​

  • A quick form (Create/Edit surfaces). A form needs the table's required rules, its choices and its plugin steps, and none of that belongs on a public site. Draw the fields instead, and write the Custom API behind your Save button — see Let visitors save changes.
  • A task list. A portal visitor is not a platform user and has no inbox.

Both say so on the page rather than failing silently.

Confirm it worked​

Open the portal as a stranger would. The grid shows your view's columns, with its headings, and pages through the records the API returns. Then edit one of the view's column headings and reload — the portal follows.