# Pages and cards

Part of the [Ownbox SDK reference](https://www.ownbox.io/sdk/reference.md).

## m.screen

```python
m.screen(path, *, owner_only=False, title=None)
```

One page of the machine, drawn by your Ownbox.

At `m.home` or under it. The function answers with screen.json, a dict of blocks your Ownbox draws in its own look (`text`, `figures`, `list`, `table`, `actions` and `settings`), or with `sdk.page(...)`. It may take `query`, `person` (`{"id", "role"}`) and `path`, by name. `owner_only=True` makes a page only the owner opens. A custom machine's page is only read: no JavaScript, no image, no form of its own. Its one form is a `settings` block, saved by your Ownbox. Use it as a decorator.

**Needs in machine.yaml:** Nothing

Example (where the machine is defined):

```python
@m.screen(m.home, title="Quotes")
def quotes_page(query, person):
    return {"v": 1, "title": "Quotes", "blocks": [
        {"kind": "figures", "items": [{"value": 2, "label": "waiting"}]},
        {"kind": "actions", "items": [{"run": "check_quotes", "label": "Check now"}]}]}
```

## m.panel

```python
m.panel(slot, *, title, render)
```

A card on another machine's screen.

In `slot`. `render()` answers with screen.json of at most 6 blocks and no settings, or `sdk.page(...)`'s body; it may take `person` by name. A card is drawn for anyone signed in: check `person["role"]` for what only the owner should see. Today the Inbox's screen offers the slot `inbox`.

**Needs in machine.yaml:** Nothing

Example (where the machine is defined):

```python
m.panel("inbox", title="Quotes waiting",
        render=lambda: {"v": 1, "title": "Quotes waiting", "blocks": [{"kind": "text", "text": "Two."}]})
```

## m.link

```python
m.link(path)
```

A full address for one of the machine's pages.

Only for a page under `m.home`; anything else raises ValueError.

**Needs in machine.yaml:** Nothing

**Returns:** `https://<the Ownbox>/my/...`.

Example (inside a job):

```python
url = m.link(m.home + "/quotes")
```

## sdk.page

```python
sdk.page(path, *, title, lede='', body)
```

A page as HTML, for a machine written before screen.json.

`title` and `lede` are plain words; `body` is HTML your Ownbox cuts to its allowlist: no script, style, form or image, every attribute but `class`, `colspan` and `rowspan` dropped, and links only to the machine's own pages. A machine written now answers with screen.json instead.

**Returns:** A page for `m.screen` to return.

Example (inside a job):

```python
page = sdk.page(m.home, title="Quotes", body="<p>Two quotes are waiting.</p>")
```