# Interfaces

> An interface is an app on top of a base, for the people who use the data rather than design it: a client portal, a team's request form, a manager's dashboard. It has pages down the side; each page shows one view of a...

Source: https://artavolo.com/docs/interfaces

An interface is an app on top of a base, for the people who use the data
rather than design it: a client portal, a team's request form, a manager's
dashboard. It has pages down the side; each page shows one view of a table,
with only the fields it shows and only what it lets people do. Airtable calls
them interfaces too, and they map one to one:

| Airtable page layout | Artavolo page |
|---|---|
| List | Grid, or List |
| Gallery, Kanban, Calendar, Timeline | Gallery, Kanban, Calendar, Timeline |
| Record review | Record review: the records on the left, the one picked on the right |
| Dashboard, Blank | Dashboard: numbers, charts, lists and progress over any table of the base, text (headings, paragraphs, bold, links), buttons that open a link, images, dividers between sections, and record pickers |
| Form | Form |

## Making one

On the base page, **Interfaces** (in the sections at the top of the base, beside Data, Automations and Forms), then **Create**. The base's
owners make and change interfaces; every member of the base can open them.

1. **Edit** shows each page's settings beside it: its name, its table, its
   layout, what people may do there, which records it shows, and each field
   **Shown**, **Read only** or **Hidden**.
2. Shape the page with the bar over it, as any view: its filter, sort, groups,
   the fields it shows, and on a dashboard its tiles.
3. **+ Add a page** for another; **Move up**, **Move down** and **Delete page**
   in its settings.
4. **Publish**. Until then nobody sees the changes: the draft is saved as you
   go, and people keep using what was last published.

| Setting | What it does |
|---|---|
| Add records, Change records, Delete records, Comment | What people may do on the page. A form page adds records and reads none; a dashboard is read only. |
| Only where *a person field* is the viewer | Each person sees the records that name them: a client their own projects. |
| Hidden | The field is not on the page; for people invited to the interface only it is never sent at all. |
| Read only | Shown, not changed. |

## People invited to the interface only

**Share** invites people by e-mail, to this interface and nothing else of the
base. They get a link; opened signed in (with any account), the invitation is
theirs, and the link does not work a second time. Roles:

| Role | May |
|---|---|
| Editor | what each page allows |
| Commenter | read, and comment where the page allows comments |
| Read only | read |

For them the server enforces each page, not only the screen:

- only the page's table, and the tables its links name (by their records'
  names, nothing more); on a dashboard page, the tables its tiles read, read
  only;
- only the fields the page shows; a hidden field cannot be read, filtered,
  sorted, grouped, searched or written; formulas, lookups and rollups come as
  their finished values, so the fields they read stay hidden;
- only the records the page's filter keeps, and with "only where ... is the
  viewer", only theirs; a record outside them answers as one that does not
  exist;
- only the actions the page allows and their role permits;
- nothing else: the base's own screen, its schema, the API with a token,
  `/v0`, the AI connector, exports, history and the trash all answer as for
  someone without the base.

Base members using an interface keep their own role on the base; for them the
page's settings shape the screen. Taking someone off the interface (or
deleting it) ends their access at once. Making, publishing, inviting and
deleting interfaces are in the audit log.

## A public link

**Share**, **Public link**: anyone holding the link sees what is published,
read only, with no account: a status page for clients, a catalogue, a
schedule. Everything above about what the server sends holds for them too
(only the pages' tables, fields and records), and they change nothing and
comment on nothing. A page that shows only the viewer's records shows nothing
on the public link, since nobody is signed in. **New link** makes another and
ends the old one; switching it off ends it at once.

## Files

Files on a page open for everyone who sees the page: for people invited to the
interface only and visitors with the public link, the server hands out signed
links to the files of the records they see, valid for six hours, and only for
files of this base.

## Record pickers

A record picker tile lists a table's records; whoever uses the page picks
one, and sees its fields. Any number, chart, list or progress tile on the page
can be **narrowed by** the picker (in the tile's settings): once a record is
picked, it counts only the records linked to it, as Airtable's record picker
filters the elements on its page. "Every record" counts them all again. The
pick is each viewer's own and is not saved. The server applies the narrowing
too, so it works on tables too big to hold in the page.

## Changes made elsewhere

An open interface page shows what others change: every 15 seconds, while the
page is in front, it asks the server which of its records changed (through the
page's own access, so nobody learns of a record they may not see) and shows
them. Records deleted, or no longer kept by the page's filter, leave it.

## Where people find them

- Members: the base page's **Interfaces**, or the link `/interface/<id>`.
- People invited to an interface only: the link in their invitation, and
  `/interfaces`, which lists the interfaces shared with them.

Tests: `tests/interfaces_test.php` (the API and what the server enforces),
`tests/ui_interfaces_test.php` (the screens, in a browser).
