# `Html`

HTML that is always safe to write into a page or an email: building one from text keeps only the allowed elements and attributes, with no scripts, no event handlers and links only to `https:` and `mailto:`, so it never fails; a literal must already be what it keeps.

[Text formats](types.md#text-formats); not ordered; since Jadpo 0.1.0.

## Make one

Build one from its text, `Html("<p>Fresh <strong>soup</strong> daily.</p>")`, which checks it: text that isn't one breaks `format`.

`text.parse(raw, as: Html)` reads one from its text; text that isn't one at all fails `malformed`.

These operations give one: `markup.rich_to_html` and `markup.to_html`.

## Text, JSON and storage

`text.from` writes its canonical text, the one form `text.parse` reads back. JSON sends its canonical text as a string.

| Text | JSON |
|---|---|
| `<p>Fresh <strong>soup</strong> daily.</p>` | `"<p>Fresh <strong>soup</strong> daily.</p>"` |
| `Tom &amp; Jerry` | `"Tom &amp; Jerry"` |
| `<ul><li>Leek</li><li>Tomato</li></ul>` | `"<ul><li>Leek</li><li>Tomato</li></ul>"` |
| `<a href="https://example.com/" rel="noopener noreferrer nofollow">our site</a>` | `"<a href=\"https://example.com/\" rel=\"noopener noreferrer nofollow\">our site</a>"` |

It is stored in one column named for the field, of type `text`. `<ul><li>Leek</li><li>Tomato</li></ul>` is stored as `'<ul><li>Leek</li><li>Tomato</li></ul>'`.

## Shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `<p>Fresh <strong>soup</strong> daily.</p>` | `Fresh soup daily.` |
| `Tom &amp; Jerry` | `Tom & Jerry` |
| `<ul><li>Leek</li><li>Tomato</li></ul>` | `"Leek\nTomato"` |
| `<a href="https://example.com/" rel="noopener noreferrer nofollow">our site</a>` | `our site` |

## Operations

- `markup.rich_to_html(rich: RichText) -> Html`: `rich` written as HTML, each block its element and each mark its element inside its link, then made safe as every `Html` is, which changes nothing: a `RichText` holds only what the sanitiser keeps.
- `markup.to_html(markdown: Markdown) -> Html`: `markdown` rendered as CommonMark (0.31.2), then made safe as every `Html` is: raw HTML inside it is kept only where the sanitiser keeps it, and an image is shown as its description, since `Html` keeps no images.
- `markup.to_plain_text(html: Html) -> Text`: The text people read in `html`: each block (a paragraph, a heading, a list item, a quote, a code block) on its own line, `<br>` a line break, white space run together as a browser shows it, kept as written in a code block.

Like every standard type, it also has the contract's own operations: `text.parse`, `text.from`, `text.format`, `json.read`, `json.write` and `==`. It isn't ordered, so `<` and sorting don't take it. [Every standard type meets one contract](../topics/every-standard-type-meets-one-contract.md) says how they work.