Skip to content

Bodies and rich text

The layouts a product, a lesson or a page shows, and the rich text format their texts use.

Updated

What a product, an entry (a lesson or an article), a custom page or the store’s home shows is its body: a layout of blocks, some of which hold rich text. You read a body with GET /v1/stores/{store}/body, or with include=body on the product, entry or page read. Without a body of its own, a page still shows a default layout, which the read answers in its place.

Bodies

curl --globoff 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/body?target[kind]=entry&target[id]=<entry id>' \
  --header 'Authorization: Bearer ctk_...'

target names whose body: { "kind": "store" } for the store’s home, or a product, entry or page with its id.

readBody 200json
{
  "id": "<body id>",
  "role": "body",
  "access": "unlocked",
  "requires": { "kind": "tier", "rank": 1, "product_id": "<product id>" },
  "words": 412,
  "content": "{\"blocks\":[{\"id\":\"intro\",\"type\":\"markdown\",\"content\":\"<rich-text version=\\\"1\\\"><h2>Welcome</h2><p>Start here.</p></rich-text>\"},{\"id\":\"lesson-video\",\"type\":\"video\",\"fileId\":\"<file id>\"}]}",
  "files": {
    "<file id>": {
      "id": "<file id>",
      "kind": "video",
      "mime": "video/mp4",
      "name": "lesson-1.mp4",
      "bytes": 48213900,
      "width": 1920,
      "height": 1080,
      "duration": 754,
      "pages": null,
      "status": "ready",
      "url": null,
      "attachment_id": "<attachment id>",
      "unlocks": null
    }
  }
}
  • default is null for the page’s own body.
  • content is a JSON string. Parse it: it’s an object whose blocks is the layout, each block an object with its id, its type and its props. Containers hold more blocks.
  • access is unlocked, or locked when the customer may not read it yet. A locked body answers its requires and words, but no content: show what unlocks it instead (A customer’s library).
  • files lists every file the layout names, by the fileId a block holds. A public file has its lasting url, and a public image its smaller copies as resized, for a responsive image; a private one has url: null and an attachment_id you open when you show it. A file kept back by its own rules lists what unlocks it.
  • A body still being prepared answers 409 conflict on status (pending): ask again shortly.

Default layouts

A page with no body of its own, or with one it can’t show, shows a default layout instead, and the body read answers that default. A body it can’t show is a layout that doesn’t read, or a body of another type; a lesson’s text and an article’s HTML show as their text.

readBody 200json
{
  "default": { "template": "page" },
  "attachment": null,
  "mime": "application/vnd.sherpo.blocks+json",
  "access": "unlocked",
  "requires": { "kind": "everyone" },
  "content": "{\"blocks\":[{\"id\":\"default-hero\",\"type\":\"hero\",\"title\":\"About us\",\"alignment\":\"center\",\"highlights\":[],\"additionalContent\":[],\"lineProducts\":{\"id\":\"default-line\",\"type\":\"line-products\",\"hidden\":true},\"hidden\":false}]}",
  "words": null,
  "files": {}
}
  • default.template names the default:
    • home: a hero with the line of products, a rule and the product grid;
    • page: a centered hero with the page’s title and description;
    • lesson and article: empty, since an entry’s title, media and header come from its own fields;
    • a product’s, by category: series, blog, podcast, portfolio, or product for every other category.
  • attachment names the body the page shows the default for, or is null without one.
  • The store’s home and a product’s page also show their default to a customer their own body is kept from.
  • A product’s default shows its poster when its settings show it as the background. Its cover is the product’s own pictures and videos the customer may open, all listed in files.
  • A default has no gate of its own. It is locked, with content: null, only when the page itself is kept from the customer, and its words are null.
  • A front-end that can show none of a page’s own blocks asks for its default instead with fallback=true: the body read then answers the default whatever the page’s body, attachment naming that body.

Blocks

Every block type a body holds, its props and their JSON Schema are in the block reference, with where each one sits: a lesson’s body takes fewer types than an article’s, a page’s or the store’s home (though one may still hold a page’s block it held before), and a product’s page has its own. A block with hidden: true isn’t shown, and a markdown block holds a rich text in its content.

A formula block holds a display formula’s TeX in tex: render it with a TeX renderer such as KaTeX, or show its source.

A diagram block holds a diagram’s Mermaid source in source, a type the store’s page draws (a flowchart, sequence, state, class, ER or XY chart diagram): render it with a Mermaid renderer, or show its source.

An audio block plays the file its fileId names, in an <audio> or a player of your own. Where the customer may play it, its file in files carries audio.waveform: the recording’s loudness from start to end as 256 levels from 0 to 255, in base64, to draw as bars the customer seeks on. It’s null until the wave is drawn after upload, so show a plain bar until then. A private recording streams through its attachment_id as a video does (Files and media): ask for its URL on the first play rather than when the page shows, as each URL asked for counts as a play, then with renew: true as it nears expires_at, which keeps it one play. Its audio also lists the chapters, summary and transcript the merchant published as outputs, read through audio.attachment_id (A video’s or audio file’s chapters, summary and transcript), and their subtitles as tracks.

A slideshow block shows the PDF its fileId names a page at a time, as a lesson’s slides are shown, with no download. Its file in files carries an attachment_id even when it is public, and pages: ask for its URL with intent: "view" when it shows, then read it whole, as a PDF viewer does (Files and media). A public PDF’s url is readable from any origin too.

A map block shows a place: latitude and longitude, an optional venue and address, and openInMaps, which shows a link to the seller’s mapUrl, or to OpenStreetMap at the point when it has none. The store draws the map itself, so it is listed in the read’s maps beside files, one entry per point the body names, matched by latitude and longitude (both rounded to 6 decimals, as the block stores them): a light and a dark picture of the place, each a public url with its width, height and smaller copies as resized (responsive images), and the attribution to show over it, linking to attribution_url. Show the picture for the page’s theme, the place’s pin at its centre. A point is missing from maps until its map is drawn, shortly after the body is saved: show the venue and address alone until then.

Render a block type you don’t know as nothing: new types may be added.

Rich text

Every rich text field (a product’s description, an entry’s teaser, the texts a body’s blocks hold, a quiz’s text) comes back as HTML in one closed format, as stored when it was written, so you can render it as it is or map each element to a component of your own. It’s wrapped in <rich-text version="1">.

<rich-text version="1"><h1>Welcome</h1><p style="text-align: center">Start with <strong>the intro</strong>, then <a href="https://example.com/notes" target="_blank">read the notes</a>.</p><ul><li data-checked="true"><p>Watch the intro</p></li><li data-checked="false"><p>Take the <span style="color: #047857">quiz</span></p></li></ul><details><summary>Why it works</summary><p>Short lessons stick.</p></details></rich-text>

What it holds

  • Text: p, h1 (Title), h2 (Heading), h3 (Subheading), br.
  • Marks: strong, em, u, s, sup, sub, code (a text written with b, i, del or strike is stored as strong, em and s); links (a) to http, https, mailto, tel, ftp, ftps, callto, sms, cid, xmpp, irc, ircs or a relative path, optionally with target="_blank". A link’s rel (noopener, noreferrer, nofollow) is read when written but never stored, so add your own.
  • Style: color and background-color on a span, as #rgb or #rrggbb; text-align (left, center, right, justify) on a paragraph or heading.
  • Structure: ul, ol (start), li (data-checked="true" or "false" for a task list), tables (table, thead, tbody, tr, th, td, with colspan and rowspan), code blocks (pre holding one code, class="language-<id>" with an id among bash, c, cpp, csharp, css, go, xml, java, javascript, json, kotlin, markdown, php, python, ruby, rust, sql, swift, typescript, yaml), blockquote, hr, details (open) with its summary first.
  • Figures: a figure holds any of the above, with at most one figcaption, first or last.
  • Blocks: images, videos, audio, slideshows, formulas, diagrams, maps, downloads and the other blocks sit in a text as <block type="…" props="…"></block> elements, their props a JSON object with its quotes escaped, the same props a body’s block has (block reference). There is no raw img, video or iframe.
<block type="image" props="{&quot;id&quot;:&quot;cover&quot;,&quot;fileId&quot;:&quot;FILE_ID&quot;,&quot;alt&quot;:&quot;The cover&quot;}"></block>

A <block>’s fileId is listed in the same read’s files, as a body’s are.

The stored form

Texts come back in a canonical form: attributes in a fixed order, entities and spacing normalized, loose inline content in a paragraph, an empty list item, cell, quote, details or figure holding an empty paragraph, an empty list holding one empty item, tables made rectangular, and each block’s props as its type reads them (defaults filled in). A text holds at most 1 MiB, nests at most 32 elements deep, and its tables cover at most 10000 cells in all.

Type to search…

↑↓ navigate↵ selectEsc close