What are page blocks?

[stephenwf]

Page blocks are the building blocks of the frontend site of Madoc. Almost every page is made up these blocks. A block usually displays one slice of UI, such as breadcrumbs, list of items or a viewer. These blocks on the page are not fixed on the page and can be reordered, removed or replaced with different blocks. A block can also be customised with different content or variations in how the data is displayed.

• Pages - A custom page with a layout and some editorial content. A layout may contain many slots.
• Slots - A slot is a defined area on a page. A slot contains a list of blocks and a direction to render.
• Block - A configurable piece of content / widget / component. Lives inside of a slot and rendered based on user configuration and context of the page.

Basic page blocks

The simplest page blocks are static pieces of content. Other simple blocks may have some configuration to customise the block. Where the simple blocks are used, they will look the same. They do not change based on where they are used (for example within the context of a Manifest).

Anatomy of a page

Most pages in Madoc are built on top of page blocks. Each page is sliced into regions called slots.

A slot has one or more blocks inside of it. These are usually displayed in a stack, with each block listed from top to bottom. Blocks cannot live side-by-side inside of a slot, but slots may be organised into columns.

When you go to customise a page (All collections page shown here), you'll see both default and empty slots.

Clicking on "customise" will let you edit the blocks inside each slot. Some blocks have an "Edit" button which will open up configuration options for the block. The handle on the left will let you drag-and-drop reorder the blocks. The "X" will remove the block.

At any time you can click on "Reset slot" and revert back to what was originally there.

Some slots let you choose how many pages will be affected by your change. For example, on a Manifest page you can choose to customise just for the manifest you are viewing, or for all manifests.

The Frontend does not yet expose all of the options for customisations. Details can be found in the technical details below.

When you click on "Edit" in a block, you will see the configuration options. In this example the title field on the "All collections" page can be customised.

In a slot you can also add new blocks.

This shows you:

• Default blocks - The blocks that were in the slot before customisation
• Page specific blocks - Blocks that provide functionality on this page.
• All blocks - List of all blocks, including the above and other generic blocks.

Technical details

Page

A page lives at a specific url and contains a layout. A layout is simple a react component that defines some basic grid or layout and regions for that page. It could be as simple as:

const MyLayout = () => (
  <div>
    <Slot name="header" />
    <Slot name="content" />
    <Slot name="footer" />
  </div>
)

CSS wrappers to make nice layouts should be simple and clear. The editing UI is baked into all slots.

Page data model

Property	Description
id	Identifies the resource (numeric)
path	The path of the page (/my-custom/page)
previous_paths	Any previous paths if its been moved, for redirecting
title	The title of the page, for page metadata and can be used in a layout in an H1 or similar
navigation_title	If this page is in a navigation menu a shorter title can be given
description	A description of the page, for page metadata and can be used in a layout
created	When the page was created
modified	When the page was last modified
author	id / name of the user who created the page
layout	The name of the layout to use (text)
parent_page	If this page is a child page, this defines that relationship. Used for navigation / menus
is_post	Multiple pages can have the same path if they are marked as a post. e.g. /blog . Require slug
slug	If this is a post, the slug will be used to identify the post and the URL to render e.g. /my-blog-post at /blog/my-blog-post
is_navigation_root	Boolean for if this page is a navigation route and a menu should be shown with child pages
hide_from_navigation	Hides this page from any navigation requests
include_in_search	Future property for indexing into search
site_id	Which site this page belongs to

Slot

In essence a slot is a list of blocks. A slot can be placed anywhere in the code and it is made to be very quick to add to existing pages. A slot can appear on a page layout, used by pages above to define regions where components can live, or they can be defined on existing pages we have created (such as collection pages).

A slot is contextually aware of the page it is on and can be conditionally rendered. For each of the primary data types we have there is the following filter options:

filter name	type	description	specificity
exact	identifier	Display this slot only on this specific resource (e.g. collection id 123)	4
whitelist	identifier list	Display this slot only on these specific resources	3
blacklist	identifier list	Display this slot only on all but these resources	2
all	boolean	Display this slot on all of this type of resource	1
none	boolean	Don't display this on this resource type	0

The following resources have these configurations:

• Project (10^1 e.g. exact = 4, specificity += 4)
• Collection (10^2 e.g. exact = 4, specificity += 40)
• Manifest (10^3 e.g. exact = 4, specificity += 400)
• Canvas (10^4 e.g. exact = 4, specificity += 4000)

Tasks will be added later as this will also be a useful context for crowdsourcing or similar. A slot can be configured with all of the above resources each with the filters. The specificity is calculated based on these properties. The specificity of each is added together. Some examples:

• A resource targeting a specific canvas on a specific project (4004)
• A resource targeting only a specific canvas (4000)
• A resource targeting a canvas on a manifest (4400)

When a page is rendered, the suitable slots are found and the one with the highest specificity is chosen. This allows an end user to add slots that appear on many pages and render contextual blocks (see below) but also the ability to override blocks in specific pages. There could be a default description for how to translate canvases on a project, but then one manifest might be slightly different, so the text could be changed just for that manifest.

From a users point of view, the slot is editable inline and new blocks can be created, existing ones edited and reordered.

Slot data model

Note there is a lot of properties here for the filters. They are made to be flexible and verbose. They are described above.

Property	Description
id	Identifies the slot instance, unique to this slot instance (numeric)
slot_layout	The layout that should be used when displaying blocks (e.g. left to right grid, or a vertical stack)
slot_id	The name of the slot that this is targeting
specificity	Pre-calculated specificity based on the filter properties
site_id	The site for which this belongs
filter_project_none	Display when no matching project resource
filter_project_all	Display on all matching project resources
filter_project_exact	Display when exactly matching a project with this id
filter_project_whitelist	Display when matching any project with these ids
filter_project_blacklist	Display when not matching any project with these ids
filter_collection_none	Display when no matching collection resource
filter_collection_all	Display on all matching collection resources
filter_collection_exact	Display when exactly matching a collection with this id
filter_collection_whitelist	Display when matching any collection with these ids
filter_collection_blacklist	Display when not matching any collection with these ids
filter_manifest_none	Display when no matching manifest resource
filter_manifest_all	Display on all matching manifest resources
filter_manifest_exact	Display when exactly matching a manifest with this id
filter_manifest_whitelist	Display when matching any manifest with these ids
filter_manifest_blacklist	Display when not matching any manifest with these ids
filter_canvas_none	Display when no matching canvas resource
filter_canvas_all	Display on all matching canvas resources
filter_canvas_exact	Display when exactly matching a canvas with this id
filter_canvas_whitelist	Display when matching any canvas with these ids
filter_canvas_blacklist	Display when not matching any canvas with these ids

Block

A block is a unit of UI that can be configured once and added to a slot (or many slots). It is comprised of the following elements:

• A type that points to code definition
• A capture model (from the definition)
• Required contexts (from the definition)
• A method for rendering to React (from the definition)
• A method for rendering to HTML (from the definition)
• Static data - per block and JSON output of the capture model
• Internationalisation config (language, is_fallback and sort key)

When a user decides to add a new block to a slot they will see all of the blocks that are available given their current context. So if they added a slot to a manifest page, they would see blocks that require a manifest to render and any other normal blocks.

The user then chooses the block they want and are presented with a capture model and preview of the block:

When they save this block it is added to that slot. The data model allows for blocks to be reused, and a title for a block to be given. This would allow a "Block library" to be created by the user and blocks to be pulled into slots from that collection.

Block internationalisation

There are 3 properties that control the internationalisation of blocks.

• Languages - List of language codes that this should be rendered
• Sort key - Arbitrary identifier for blocks that represent the same thing in different languages
• Is fallback - Wether this block should be the fallback if no language matches

If you created 2 blocks that should be changed based on language, they would both have the language they are written in, they would both have the same sort key and the one that has "is fallback" would be displayed when no language matches. If there is no fallback, then nothing will be rendered.

Block definition

The way a block knows how to render is based on it's definition. Here is the source for the most basic HTML block:

import { captureModelShorthand } from '@capture-models/helpers';
import { HTMLPageBlockDefinition } from '../extension';

const definition: HTMLPageBlockDefinition<{ html: string }> = {
  label: 'Simple HTML block',
  type: 'simple-html-block',
  renderType: 'html',
  model: captureModelShorthand({
    html: {
      label: 'Enter HTML content',
      type: 'html-field',
    },
  }),
  defaultData: {
    html: '',
  },
  render: data => {
    return data.html;
  },
};

export default definition;

It defines a label shown to the user, a type for referring back to this definition, a model (using the shorthand) some default data and a very simple render method that returns HTML (renderType can be HTML or React).

Block data model

Property	Description
id	Identifies the resource (numeric)
type	The type, used to find the definition
static_data	The output from the capture model - passed to the block when rendering (json)
lazy	Wether this component should be server-rendered (mirador for example cannot be)
site_id	The site this block belongs to
i18n_languages	The languages for this block (text array)
i18n_sort_key	When multiple blocks in a slot share a key, only one will be displayed based on best language
i18n_fallback	A component with a sort key and fallback will be displayed on all languages if there is no other available

Slots on existing pages

In addition to creating a page layout, slots can be retroactively added to existing madoc-rendered pages to allow users to add new content or replace the UI components we have created. For example, here is a way that a manifest grid page could have slots added to it for custom content to be added:

Some slots might wrap existing UI, like the metadata and others might just be blank regions on the page. Since this is a manifest within a collection, the blocks that are rendered have access to these. Specific blocks may require (required contexts) that they are inside of a manifest. A replacement metadata component that is customisable could be created that could replace the default and it would have access to all of the data it needed to render. It wouldn't however be available on a static page as there is no manifest to pull from.

If a page is made under a resource (e.g. at a path of /madoc/collection/1/my-custom-page) then it will have access to the context and all of the contextual blocks will be available to place.