### Example directory structure for a Mattrbld project

Source: https://mattrbld.com/docs/quickstart

Mattrbld doesn't enforce a specific directory structure; this is a simple structure used in the guide for clarity. Only the 'content' folder and its 'posts' and 'uploads' subfolders are relevant; other folders are for context.

```text
my-first-mattrbld-project
├── .git
├── content
│   ├── posts
│   └── uploads
├── src
│   └── (files and folders relating to your SSG)
└── (other files)
```

--------------------------------

### Blog post example: file and Schema

Source: https://mattrbld.com/docs/fields-and-types

Illustrates a blog post file with frontmatter and Markdown body, and the corresponding Schema that maps fields to that structure. The 'content' key is special and writes to the body instead of frontmatter.

```markdown
---
title: Hello World
published: 2021-06-23
---

# Hello World!

This is the **Markdown** content of the post.
```

```json
{
  "fields": [
    {
      "type": "text",
      "key": "title"
    },
    {
      "type": "date",
      "key": "published"
    },
    {
      "type": "rich text",
      "key": "content",
      "options": {
        "outputFormat": "markdown"
      }
    }
  ]
}
```

--------------------------------

### Localised field output example

Source: https://mattrbld.com/docs/multi-language-content

Shows the JSON output of the same field when localisation is enabled, with language codes 'de-DE' and 'en-GB'.

```json
{
  "title": {
    "de-DE": "wert",
    "en-GB": "value"
  }
}
```

--------------------------------

### Localised to non-localised property conversion example

Source: https://mattrbld.com/docs/multi-language-content

Shows the JSON structure before and after converting a localised property back to non-localised. The value of the first locale (de-DE) is kept and other values are discarded.

```json
{
  "title": {
    "de-DE": "wert",
    "en-GB": "value"
  }
}
```

```json
{
  "title": "wert"
}
```

--------------------------------

### Non-localised to localised property conversion example

Source: https://mattrbld.com/docs/multi-language-content

Shows the JSON structure before and after converting a non-localised property to a localised one. The current value becomes the value of the first locale (de-DE) and other locales are set to null.

```json
{
  "title": "value"
}
```

```json
{
  "title": {
    "de-DE": "value",
    "en-GB": null
  }
}
```

--------------------------------

### showByValue visibility option examples

Source: https://mattrbld.com/docs/fields-and-types

Two JSON examples of the showByValue visibility option. The first shows a field when the value of field "test" matches the regular expression /[0-9]+/. The second shows a field when the value of field "toggle" is false. Both use the comparator and field keys; the first uses the string value "matches" to trigger regex matching, the second uses a boolean value for strict equality.

```json
{
  "comparator": "/[0-9]+/",
  "field": "test",
  "value": "matches"
}
```

```json
{
  "comparator": null,
  "field": "toggle",
  "value": false
}
```

--------------------------------

### Handling messages from optional features

Source: https://mattrbld.com/docs/implementing-the-preview-protocol

Example of handling messages inside the handleMessage() function. It checks for handshake, then for the 'feature' property to handle optional features like comments, and finally renders content for regular updates.

```javascript
// inside the handleMessage() function
if (data && data.handshake) {
  // handle handshake
} else if (data && data.feature === 'comments') {
  // handle comment-feature related messages e.g.:
  switch (data.type) {
    case 'modechange':
      // handle modechange event
      break;
    default:
      break;
  }
} else if (data) {
  // render content
}
```

--------------------------------

### Non-localised field output example

Source: https://mattrbld.com/docs/multi-language-content

Shows the JSON output of an Unformatted Text field with key 'title' when localisation is not enabled.

```json
{
  "title": "value"
}
```

--------------------------------

### handlePageClick function for comment mode

Source: https://mattrbld.com/docs/preview-features/comments

Example function to handle clicks on the preview page, distinguishing between comment markers and the page itself. Sends a message to Mattrbld with the appropriate event type ('commentClick' or 'pageClick') and coordinates.

```javascript
function handlePageClick(e) {
  const {
    target, clientX, clientY, pageX, pageY,
  } = e;
  const isCommentMarker = 
    target.classList.contains('comment-marker');

  const data = {
    feature: 'comments',
    payload: {
      clientX,
      clientY,
    },
  };

  if (isCommentMarker) {
    data.type = 'commentClick';
    data.payload.id = target.dataset.id;
  } else {
    data.type = 'pageClick';
    data.payload.pageX = pageX;
    data.payload.pageY = pageY;
  }

  cachedSource.postMessage(
    data, MATTRBLD_INSTANCE
  );
}
```

--------------------------------

### Handling addCommentMarker event in postMessage handler

Source: https://mattrbld.com/docs/preview-features/comments

Example switch-case handler for the 'addCommentMarker' event, which calls a function to create a comment marker on the preview page.

```javascript
// in the switch-case within the postMessage
// handler
case 'addCommentMarker':
  const { comment } = data.payload;
  // a function that places comment markers on 
  // the preview page
  createCommentMarker(comment);
  break;
```

--------------------------------

### JavaScript function to get localised value

Source: https://mattrbld.com/docs/multi-language-content

A simple JavaScript function that retrieves a localised value from content using a locale key. Includes example content and usage calls. Note the typo 'getLocalisedValule' in the calls.

```javascript
// Simple example for brevity
function getLocalisedValue(content, key, locale) {
  if (content[key]) return content[key][locale];
  else throw new Error(`${key} could not be found in content`);
}

const content = {
  title: {
    'de-DE': 'wert',
    'en-GB': 'value',
  },
};

getLocalisedValule(content, 'title', 'en-GB'); // → 'value'
getLocalisedValule(content, 'title', 'de-DE'); // → 'wert'
```

--------------------------------

### Handling deleteCommentMarker event in postMessage handler

Source: https://mattrbld.com/docs/preview-features/comments

Example switch-case handler for the 'deleteCommentMarker' event, which calls a function to remove a comment marker from the preview page.

```javascript
// in the switch-case within the postMessage
// handler
case 'deleteCommentMarker':
  const { comment } = data.payload;
  // a function that removes comment markers from 
  // the preview page
  deleteCommentMarker(comment);
  break;
```

--------------------------------

### Complete Preview Protocol Implementation

Source: https://mattrbld.com/docs/implementing-the-preview-protocol

A complete HTML page that implements the Mattrbld preview protocol. It listens for messages, verifies the origin against the Mattrbld instance URL, handles the handshake by responding with the handshake ID and an empty supports array, and renders received data as JSON. It also signals Mattrbld that the page has loaded when opened in a separate tab or window.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Preview Protocol Tester</title>
</head>
<body>
  <h1>Mattrbld Preview Protocol Tester</h1>
  <pre>Ready for output.</pre>
  <script>
    // replace this with the URL of your Mattrbld instance if you're using a custom one!
    const MATTRBLD_INSTANCE = "https://app.mattrbld.com";
    const output = document.body.querySelector('pre');

    function handleMessage(e) {
      // get the relevant details from the message
      const { origin, data, source } = e;

      if (origin !== MATTRBLD_INSTANCE) {
        output.innerText = `The message came from an unallowed origin: ${origin}`;
        return;
      }

      // handle the handshake
      if (data && data.handshake) {
        source.postMessage(
          {
            handshake: data.handshake,
            supports: [],
          },
          MATTRBLD_INSTANCE
        );
      } else {
        // Render the received data
        output.innerText = JSON.stringify(data, null, 2);
      }
    }

    // handle messages coming from Mattrbld
    window.addEventListener('message', handleMessage);

    // needed to signal Mattrbld that the page has   loaded if it was opened in a separate tab / window
    if (window.opener) {
      window.opener.postMessage(
        { loaded: true }, MATTRBLD_INSTANCE
      );
    }
  </script>
</body>
</html>
```

--------------------------------

### Legacy config.json sidebar entries for system types

Source: https://mattrbld.com/docs/sidebar

For projects configured before v1.0.0, add the Dashboard, Media Library, and Settings entries manually to the project's config.json file in the .mattrbld directory. The entries use the 'protected' flag and 'onlyPrivileged' for Settings.

```json
"sidebar": [
  {
    "label": "Dashboard",
    "icon": "grid",
    "target": {
    "name": "Project"
    },
    "protected": true
  },
  {
    "label": "Media Library",
    "icon": "image-stack",
    "target": {
    "name": "Project.MediaLibrary"
    },
    "protected": true
  },
  {
    "label": "Settings",
    "icon": "settings",
    "target": {
    "name": "Project.Settings"
    },
    "onlyPrivileged": true,
    "protected": true
  }
]
```

--------------------------------

### Enable Umami analytics with .env.production.local

Source: https://mattrbld.com/docs/self-hosting-overview

Add this .env.production.local file to the root directory to enable Umami analytics. The VUE_APP_UMAMI_SCRIPT variable must be set to the full URL of the Umami script (e.g., https://analytics.example.com/umami.js), and VUE_APP_UMAMI_ID to the ID Umami assigned when you added your Mattrbld domain as a site. If these variables are absent when npm run build is run, no analytics are reported.

```plaintext
VUE_APP_UMAMI_SCRIPT=[URL of your Umami script]
VUE_APP_UMAMI_ID=[ID of your instance in Umami]
```

--------------------------------

### Filesystem structure tree

Source: https://mattrbld.com/docs/how-it-works

Shows the virtual file system layout Mattrbld generates in IndexedDB. The root contains a projects directory for each imported project, a users directory for local user profiles, and a mattrbld.config file for global configuration.

```text
root
├── projects
│   ├── your-project
│   │   ├── .mattrbld
│   │   └── (all other files in your repository)
│   └── (repeat for every other imported project)
├── users
│   ├── user-at-example-com.json
│   ├── user-at-example-com.jpg
│   └── (repeat for every other local user)
└── mattrbld.config
```

--------------------------------

### Handle binary image data and replace content src with ObjectURL

Source: https://mattrbld.com/docs/preview-limitations

Processes preview data by storing binary media blobs in a Map as ObjectURLs, then recursively replaces src attributes in content with those URLs. Media files are unprocessed and may not be resized or optimized.

```javascript
const images = new Map();

// data is the data passed by the Mattrbld preview
function handlePreviewData(data) {
  if (data.imageMap && data.imageMap.size > 0) {
    data.imageMap.forEach((image, path) => {
      if (images.has(path)) return;
      images.set(
        path,
        URL.createObjectURL(image)
      );
    });
  }

  // the actual content is in data.data
  content = replaceContent(data.data);
}

// A recursive function to replace content
// with usable data, could also be used to convert
// Markdown and other things
function replaceContent(obj) {
  if (!obj || typeof obj !== 'object') return obj;

  if (Array.isArray(obj)) {
    return obj.map((item) => {
      return replaceContent(item));
    }
  }

  return Object.entries(obj)
    .reduce((content, [key, value]) => {
      if (
        typeof value === 'string'
        && key === 'src'
        && images.has(value)
      ) content[key] = images.get(value);
      else content[key] = replaceContent(value);
      return content;
    }, {});
}
```

--------------------------------

### Mattrbld Invite Link URL Structure

Source: https://mattrbld.com/docs/users

Invite link structure for Mattrbld. Only the repo and branch parameters are required; all others are optional and fall back to defaults or prompt the user. The email parameter, if present, is displayed read-only when the link is opened.

```text
// Formatted and URL encoding omitted
// for better legibility

https://app.mattrbld.com/import
?name=Example User
&email=user@example.com
&repo=https://git-provider.com/path/to/repo.git
&branch=main
&proxy=https://proxy-url.com
&inviter=Name of person inviting
&projectName=Name of the project
```

--------------------------------

### Content-Security-Policy header for frame-ancestors

Source: https://mattrbld.com/docs/common-issues-with-realtime-previews

Set the Content-Security-Policy header to allow the preview page to be opened in an iFrame on the Mattrbld origin. The X-Frame-Options header is obsolete and should be replaced with this CSP header.

```http
Content-Security-Policy: frame-ancestors 'self' https://app.mattrbld.com
```

--------------------------------

### Handle initialData event

Source: https://mattrbld.com/docs/preview-features/comments

Handle the initialData event by creating comment markers for each comment. Ensure positions are handled appropriately.

```javascript
// in the switch-case within the postMessage
// handler
case 'initialData':
  const { comments } = data.payload;
  comments.forEach((comment) => {
    // a function that places comment markers on 
    // the preview page
    createCommentMarker(comment)
  });
  break;
```

--------------------------------

### Preview page handshake handler

Source: https://mattrbld.com/docs/implementing-the-preview-protocol

JavaScript code for the preview page to handle the handshake with Mattrbld. It validates the origin, caches the message source, and responds with the handshake code and an empty supports array. Also signals Mattrbld that the page has loaded when opened in a separate tab or window.

```javascript
// replace this with the URL of your Mattrbld instance if you're using a custom one!
const MATTRBLD_INSTANCE = "https://app.mattrbld.com";
const cachedSource = null;

function handleMessage(e) {
  // get the relevant details from the message
  const { origin, data, source } = e;

  if (origin !== MATTRBLD_INSTANCE) {
    // handle postMessages from other origins
    // usually by throwing an error
    return;
  }

  // cache the message source to send data back
  cachedSource = source;

  // handle the handshake
  if (data && data.handshake) {
    cachedSource.postMessage(
      {
        handshake: data.handshake,
        // include optional features here
        // but only if implemented!
        supports: [],
      },
      MATTRBLD_INSTANCE
    );
  }
}

// handle messages coming from Mattrbld
window.addEventListener('message', handleMessage);

// needed to signal Mattrbld that the page has loaded if it was opened in a separate tab / window
if (window.opener) {
  window.opener.postMessage(
    { loaded: true }, MATTRBLD_INSTANCE
  );
}
```

--------------------------------

### Preview data format

Source: https://mattrbld.com/docs/implementing-the-preview-protocol

The general preview data sent after handshake and after every content change. The 'url' property is compiled based on collection URL-template, localization, and draft status; otherwise it is assembled from the project path. The 'data' property contains content according to the Schema.

```javascript
{
  // the name of the collection the content is in
  collection: 'Pages.json',
  // the URL of the content item
  url: '/docs/implementing-the-preview-protocol/',
  // the content according to the Schema
  data: {…},
  // any Media Library images
  imageMap: <Map>
}
```

--------------------------------

### Default metadata file for an image

Source: https://mattrbld.com/docs/advanced-media-library

Shows the default metadata file structure stored in .mattrbld/media for an image, containing only the alt and title fields from the Advanced Media Library Schema.

```json
{
  "alt": "The alt text for the image",
  "title": "The image title text, if specified"
}
```

--------------------------------

### Heading and Description Field Options

Source: https://mattrbld.com/docs/fields/heading

Default options for the Heading and Description field. Both heading and description are optional strings that default to empty. This field is visualOnly and has no impact on the data structure.

```json
{
  "heading": "",
  "description": ""
}
```

--------------------------------

### Image field options

Source: https://mattrbld.com/docs/fields/image

Default options for the Image field. Set resolutionHint to a custom hint about image resolution (e.g., "200w" or "100x400px"), removable to allow removing the image (resetting value to null), and simple to true to deactivate the Advanced Media Library for this image.

```json
{
  "resolutionHint": "",
  "removable": true,
  "simple": false
}
```

--------------------------------

### Date and Time Field Options (Default Values)

Source: https://mattrbld.com/docs/fields/date

Default configuration options for the Date and Time field. The outputFormat can be 'iso' or 'ms' (UNIX timestamp). removable allows resetting to null, showTime toggles time selector, defaultToNow sets default to creation time, useAsUpdatedAt overrides user input on save, and only restricts selectable dates to 'past' or 'future'.

```json
{
  "outputFormat": "iso",
  "removable": false,
  "showTime": true,
  "defaultToNow": true,
  "useAsUpdatedAt": false,
  "only": null
}
```

--------------------------------

### Field key mapping: Schema and output

Source: https://mattrbld.com/docs/fields-and-types

Shows a minimal Schema with a single text field keyed 'title', and the resulting content structure where the field value is stored under that key.

```json
{
  "fields": [
    {
      "type": "text",
      "key": "title"
    }
  ]
}
```

```json
{
  "title": "value of the text input"
}
```

--------------------------------

### Icon field default options

Source: https://mattrbld.com/docs/fields/icon

Default options for the Icon field. Set sourceDir to a repository folder containing image files; insertAs controls whether the picked icon is inserted as a filepath or via a URL template; preserveColor should be enabled if icons lack transparency; prettyFilenames shows only the file name in the picker; removable controls whether the value can be cleared.

```json
{
  "sourceDir": "",
  "insertAs": "filepath",
  "urlTemplate": "",
  "preserveColor": false,
  "prettyFilenames": false,
  "removable": false
}
```

--------------------------------

### Mattrbld Field Structure Interface

Source: https://mattrbld.com/docs/fields-and-types

Shows the common interface for all Mattrbld fields. Use this as a reference for the available properties when defining a custom field or understanding the structure of any field type.

```json
{
  "type": String,
  "customField": String,
  "default": Any,
  "description": String,
  "displayField": String,
  "group": String,
  "icon": String,
  "key": String,
  "label": String,
  "localised": Boolean,
  "options": [
    {
      "component": String,
      "key": String,
      "label": String,
      "props": Object,
      "slot": String,
      "value": Any,
    }, …
  ],
  "tab": String,
  "validation": {
    "enforceMinMax": Boolean,
    "max": Number,
    "min": Number,
    "regex": String,
    "regexError": String,
    "required": Boolean,
    "unit": String,
    "isString": Boolean
  },
  "value": [Array, null],
  "version": Number,
  "visibility": {
    "hidden": Boolean,
    "limitToRoles": Array,
    "showByValue": {
      "comparator": [String, Number],
      "field": String,
      "value": Any
    }
  },
  "visualOnly": Boolean
}
```

--------------------------------

### Mattrbld Schema JSON structure

Source: https://mattrbld.com/docs/schemas

Shows the top-level structure of a Mattrbld Schema JSON file, which contains a fields array and an optional tabs array. The tabs array uses a label and a groupAs property, which defaults to null. Use this as a reference when creating or inspecting Schema files.

```json
{
  "fields": […],
  "tabs": [
    {
      "label": "Label of the Tab",
      "groupAs": null
    }  
  ]
}
```

--------------------------------

### Link field default options

Source: https://mattrbld.com/docs/fields/link

Default options for the Link field. The type option may be "both", "internal", or "external". byFilePath uses the selected file's path without extension for internal links, urlSuffix is appended when byFilePath is true, and urlTemplate overrides the Collection's template for internal link URLs.

```json
{
  "type": "both",
  "byFilePath": false,
  "urlSuffix": "/",
  "urlTemplate": ""
}
```

--------------------------------

### Image field output with Advanced Media Library

Source: https://mattrbld.com/docs/advanced-media-library

Shows the output of an Image field when the Advanced Media Library is active, with a src property containing the image path and other properties from the schema.

```json
{
  "src": "/content/media/image.jpg",
  "alt": "The alt text for the image",
  "title": "The image title text, if specified"
}
```

--------------------------------

### Handle moveFailed event to reset comment marker position

Source: https://mattrbld.com/docs/preview-features/comments

Mattrbld sends this event when a comment cannot be moved due to missing permissions or an error. Use it to reset the comment marker position on the preview page.

```json
{
  feature: 'comments',
  type: 'moveFailed',
  payload: {
    comment: <Comment> or null,
  }
}
```

--------------------------------

### Enable comments feature in handshake

Source: https://mattrbld.com/docs/preview-features/comments

Include 'comments' in the supports array of the initial handshake to enable the comments feature. Cache the source outside the handler for sending subsequent messages.

```javascript
// in a postMessage handler
if (data && data.handshake) {
  source.postMessage({
    handshake: data.handshake,
    supports: ['comments'],
  });
}

// you'll also need to cache the source to easily send more messages, so cachedSource is defined outside the handlerFunction

cachedSource = source;
```

--------------------------------

### File field default options

Source: https://mattrbld.com/docs/fields/file

Default options for the File field. The removable option controls whether the file can be removed after being set, resetting the value to null. allowUpload enables uploading new files via the picker. root restricts the picker to a folder within the project, defaulting to the project root. filetypes is an array of extensions without a leading dot; only the file name extension is compared.

```json
{
  "removable": false,
  "allowUpload": false,
  "root": null,
  "filetypes": ["pdf", "zip"]
}
```

--------------------------------

### Apache VirtualHost configuration for CORS proxy

Source: https://mattrbld.com/docs/cors-proxy

Experimental Apache configuration that proxies /corsprox requests to HTTPS endpoints using mod_proxy and mod_rewrite. It includes SSLProxyEngine, disables ProxyRequests, unsets WWW-Authenticate for proxy requests, and defines rewrite rules for Git smart HTTP (info/refs, upload-pack, receive-pack) with preflight handling. Note the commented-out dangerous rule that allows arbitrary proxying.

```apache
<VirtualHost *:1000>
  ServerAdmin webmaster@localhost
  DocumentRoot /var/www/html

  # Enable SSL Proxy engine
  # so we can talk to https endpoints
  SSLProxyEngine on

  # Make sure ProxyRequests is off
  # for better security,
  # but mod_proxy needs to be enabled
  # for [P] to work in RewriteRule
  ProxyRequests Off

  # Unset the WWW-Authenticate header
  # to avoid browser login prompt on 401
  # if we’re making a proxy request
  Header unset "WWW-Authenticate" "expr=%{REQUEST_URI} =~ m#^/corsprox/#"

  # Since using ProxyPass
  # doesn't work, use mod_rewrite
  RewriteEngine on

  # This works but is dangerous
  # since it allows arbitratry requests
  # to be proxied through us
  # RewriteRule "^/corsprox/(.*$)" "https://$1" [P]

  # So instead, let's limit what can go through 
  # based on allow-requests.js
  # here: @isomorphic-git/cors-proxy
  # Since complex rewrite cond are hard to read 
  # we're repeating the RewriteRule
  # when appropriate
  # I believe the preflight requests never fire, 
  # since we’re not technically making a CORS 
  # request but I’ve added them nonetheless
  
  # isPreflightInfoRefs? or isInfoRefs?
  RewriteCond %{REQUEST_METHOD} OPTIONS
  RewriteCond %{REQUEST_URI} "/info/refs$"
  RewriteCond %{QUERY_STRING} "(^|&)service=git-upload-pack($|&)" [OR]
  RewriteCond %{QUERY_STRING} "(^|&)service=git-receive-pack($|&)"
  RewriteRule "(.*$)" "$1" [R=200,L]

  # isInfoRefs?
  RewriteCond %{REQUEST_METHOD} GET
  RewriteCond %{REQUEST_URI} "/info/refs$"
  RewriteCond %{QUERY_STRING} "(^|&)service=git-upload-pack($|&)" [OR]
  RewriteCond %{QUERY_STRING} "(^|&)service=git-receive-pack($|&)"
  RewriteRule "^/corsprox/(.*$)" "https://$1" [P]

  # isPreflightPull? or isPreflightPush?
  RewriteCond %{REQUEST_METHOD} OPTIONS
  RewriteCond %{HTTP:Access-Control-Request-Headers} "(^|,\s*)content-type(,|$)"
  RewriteCond %{REQUEST_URI} "git-upload-pack$" [OR]
  RewriteCond %{REQUEST_URI} "git-receive-pack$"	
  RewriteRule "(.*$)" "$1" [R=200,L]

  # isPull?
  RewriteCond %{REQUEST_METHOD} POST
  RewriteCond %{HTTP:Content-Type} "^application/x-git-upload-pack-request$"
  RewriteCond %{REQUEST_URI} "git-upload-pack$"
  RewriteRule "^/corsprox/(.*$)" "https://$1" [P]

  # isPush?
  RewriteCond %{REQUEST_METHOD} POST
  RewriteCond %{HTTP:Content-Type} "^application/x-git-receive-pack-request$"
  RewriteCond %{REQUEST_URI} "git-receive-pack$"
  RewriteRule "^/corsprox/(.*$)" "https://$1" [P]

  # Fall back to index.html for routes
  # that don’t exist
  # (so client side router can pick up on them)
  FallbackResource  /index.html

  ErrorLog ${APACHE_LOG_DIR}/error.log
  CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
```

--------------------------------

### Handle modechange event

Source: https://mattrbld.com/docs/preview-features/comments

Handle the modechange event: add or remove a click listener and manage comment markers. Use canComment to adjust UI like cursor.

```javascript
// in a postMessage handler
if (data && data.feature === 'comments') {
  switch (data.type) {
    case: 'modechange':
      const { active, canComment } = data.payload;
      if (active) {
        window.addEventListener(
          'click',
          // a function that handles page clicks
          handlePageClick,
          false
        );
        // you can use canComment here to show 
        // that the comment mode is enabled for 
        // your preview page, e.g. by changing the 
        // cursor
      } else {
        window.removeEventListener(
          'click',
          handlePageClick,
          false
        );
        // a function that removes all comment 
        // markers on the page
        removeCommentMarkers();
        // use canComment to determine whether you
        // need to undo anything else here
      }
      break;       
    default:
      break;
  }
}
```

--------------------------------

### Prevent link navigation in preview with disableLinks

Source: https://mattrbld.com/docs/preview-limitations

Adds a global click event listener that prevents navigation for links opening in the same window, preserving the preview connection. It allows links with target='_blank' and hash-only hrefs.

```javascript
function disableLinks(e) {
  let link;

  if (e.target.tagName.toLowerCase() === 'a') {
    link = e.target;
  } else {
    link = e.target.closest('a');
  }

  if (!link) return;

  if (
    link.getAttribute('target') !== '_blank'
    && (!link.getAttribute('href')
    || !link.getAttribute('href').startsWith('#'))
  ) {
    e.preventDefault();
  }
}

window.addEventListener('click', disableLinks, { capture: true });
```

--------------------------------

### Handle updateCommentMarker event to update comment marker

Source: https://mattrbld.com/docs/preview-features/comments

Mattrbld sends this event when a comment's status changes. Use it to update the comment marker appearance on the preview page.

```json
{
  feature: 'comments',
  type: 'updateCommentMarker',
  payload: {
   comment: <Comment>, // the updated comment
  },
}
```

--------------------------------

### initialData event payload

Source: https://mattrbld.com/docs/preview-features/comments

Event sent when comment mode is enabled, containing the array of top-level comments.

```json
{
  feature: 'comments',
  type: 'initialData',
  payload: {
    // an array of all the top-level comments for
    // the content item
    comments: <Array of Comment>,
  },
}
```

--------------------------------

### Dropdown Field Options Default Configuration

Source: https://mattrbld.com/docs/fields/select

Default options for the Dropdown field. Set filterable to true to show a filter input, removable to true to allow resetting to null, placeholder to customize the placeholder text, and options to define the selectable values.

```json
{
  "filterable": false,
  "removable": false,
  "placeholder": "Select a value…",
  "options": []
}
```

--------------------------------

### File field validation options

Source: https://mattrbld.com/docs/fields/file

Default validation options for the File field. If max is not set, the global maximum file size from the media library options is used if set. required indicates whether a file must be set. unit is the unit for max, shown as filesize (MB).

```json
{
  "max": null,
  "required": false,
  "unit": "filesize (MB)"
}
```

--------------------------------

### Rows Field Options Default Values

Source: https://mattrbld.com/docs/fields/rows

Default configuration options for the Rows field: compact, allowEditing, and itemLabel.

```json
{
  "compact": true,
  "allowEditing": true,
  "itemLabel": "Row"
}
```

--------------------------------

### addCommentMarker event message structure

Source: https://mattrbld.com/docs/preview-features/comments

Message structure sent by Mattrbld when a new comment is added. Contains the feature, type, and payload with the comment object.

```json
{
  feature: 'comments',
  type: 'addCommentMarker',
  payload: {
    comment: <Comment>, // the newly added comment
  },
}
```

--------------------------------

### Handshake message payload

Source: https://mattrbld.com/docs/implementing-the-preview-protocol

The initial postMessage payload sent by Mattrbld to the preview page after it loads. Contains a random 7-character handshake code.

```json
{
  handshake: 'p7s8n1c', // random 7 character code
}
```

--------------------------------

### Rich Text Field Default Options

Source: https://mattrbld.com/docs/fields/rich-text

Default configuration for the Rich Text field. Shows all available options with their default values, including outputFormat, blockFormats, inlineFormats, formatOptions, inputRuleOptions, minHeading, maxHeading, codeLangs, allowRaw, urlTemplate, urlSuffix, and linkOptions.

```json
{
  "outputFormat": "html",
  "blockFormats": [
    "blockquote",
    "heading",
    "hr",
    "orderedList",
    "unorderedList",
    "image"
  ],
  "inlineFormats": [
    "em",
    "strong",
    "link"
  ],
  "formatOptions": [
    "allowQuoteFooters",
    "allowNestedLists",
    "allowImageCaptions"
  ],
  "inputRuleOptions": [
    "autoquotes",
    "dashes",
    "ellipsis",
    "noDoubleCaps",
    "noDoubleSpace"
  ],
  "minHeading": 2,
  "maxHeading": 4,
  "codeLangs": [
    "html",
    "css",
    "javascript",
    "markdown"
  ],
  "allowRaw": false,
  "urlTemplate": "",
  "urlSuffix": "",
  "linkOptions": [
    "forceBlankTarget",
    "allowExternal",
    "allowInternal"
  ]
}
```

--------------------------------

### Icon field validation options

Source: https://mattrbld.com/docs/fields/icon

Default validation options for the Icon field. Set required to true to make the field mandatory.

```json
{
  "required": false
}
```

--------------------------------

### Send commentMoved event to update comment position

Source: https://mattrbld.com/docs/preview-features/comments

Send this event to Mattrbld after moving a comment marker on the preview page. The payload requires the comment ID and the new position in page coordinates (top and left as numbers below 999,999).

```json
{
  feature: 'comments',
  type: 'commentMoved',
  payload: {
    comment: <CommentID>,
    position: { x: <Number>, y: <Number> },
  },
}
```

--------------------------------

### Tags Field Options Default Configuration

Source: https://mattrbld.com/docs/fields/tags

Default options for the Tags field. Set allowUnsuggested to false to restrict values to those in autocompleteModel. autocompleteModel can be an array of strings, an array of { label, value } objects, or an object with path and key properties pointing to a JSON file.

```json
{
  "allowUnsuggested": true,
  "autocompleteModel": []
}
```

--------------------------------

### Content Reference Field Options

Source: https://mattrbld.com/docs/fields/reference

Default options for the Content Reference field. The collections array limits selectable content items; by default, only linkable collections are allowed. The field option is a key-path to the referenced value, and removable controls whether the value can be reset to null.

```json
{
  "collections": [],
  "field": "",
  "removable": false
}
```

--------------------------------

### Date and Time Field Validation Options (Default Values)

Source: https://mattrbld.com/docs/fields/date

Default validation options for the Date and Time field. max and min are null, required is false, unit is 'date', and isString is true.

```json
{
  "max": null,
  "min": null,
  "required": false,
  "unit": "date",
  "isString": true
}
```

--------------------------------

### Default options for Sortable List field

Source: https://mattrbld.com/docs/fields/list

Shows the default options object for the Sortable List field. The limitToModel option controls whether values not in the model are allowed, and the model option defines the source for suggested tags.

```json
{
  "limitToModel": true,
  "model": []
}
```

--------------------------------

### Container Field default options

Source: https://mattrbld.com/docs/fields/container

Default options for the Container Field. Set collapsible to true to render sub-fields in a collapsible section, which implicitly assumes bordered is true. collapseByDefault only takes effect when collapsible is true.

```json
{
  "collapsible": false,
  "collapseByDefault": false,
  "row": false,
  "bordered": false
}
```

--------------------------------

### Color Field Default Options

Source: https://mattrbld.com/docs/fields/color

Default options for the Color field. The format option determines the output string format: hex, rgb, or rgba; rgba is the only format supporting transparency. The palette array contains objects like { label: 'white', value: '#ffffff' }.

```json
{
  "format": "hex",
  "removable": false,
  "useBrandPalette": true,
  "paletteOnly": false,
  "palette": []
}
```

--------------------------------

### Validation property structure

Source: https://mattrbld.com/docs/validation

Shows the structure of the validation property for a field in Mattrbld. The object can include enforceMinMax, max, min, regex, regexError, required, unit, and isString properties. Not all fields support every property, but all fields with validation options have at least one.

```json
{
  …
  "validation": {
    "enforceMinMax": Boolean,
    "max": Number,
    "min": Number,
    "regex": String,
    "regexError": String,
    "required": Boolean,
    "unit": String,
    "isString": Boolean
  }
  …
}
```

--------------------------------

### Toggle field default options

Source: https://mattrbld.com/docs/fields/toggle

Default options for the Toggle field. Set iconLeft and iconRight to the names of icons to display when the toggle is off or on, respectively.

```json
{
  "iconLeft": null,
  "iconRight": null
}
```

--------------------------------

### Comments event data format

Source: https://mattrbld.com/docs/preview-features/comments

General format of data sent by Mattrbld for the comments feature. The type and payload vary by event.

```json
{
  feature: 'comments',
  type: <Type of Event>,
  payload: <Event Payload>,
}
```

--------------------------------

### Comment object structure

Source: https://mattrbld.com/docs/preview-features/comments

Structure of a comment object. position may be out of bounds depending on viewport size.

```json
{
  id: '89x27mzfls', // random id
  author: <Name>, // name of the comment author
  parent: null, // optional parent id if is reply
  content: <CommentContent>, // HTML string
  position: { x: <Int>, y: <Int> }, // or null
  status: null, // status like "resolved"
  created: <Date>,
  updated: null, // <Date> if edited
}
```

--------------------------------

### Unformatted Text Field Options

Source: https://mattrbld.com/docs/fields/text

Default options for the Unformatted Text field. Set wrapping to false to display text in a single line; set multiline to true to allow line breaks, which implicitly overrides wrapping.

```json
{
  "wrapping": true,
  "multiline": false
}
```

--------------------------------

### Radio Group field default options

Source: https://mattrbld.com/docs/fields/radio-group

Shows the default configuration options for the Radio Group field. The 'type' option can be 'inline', 'wide', or 'segmented'. The 'options' option can be an array of values, an array of { label, value } objects, or an object with a 'path' to a JSON file and a 'key' to look up an options array.

```json
{
  "type": 'inline',
  "options": []
}
```

--------------------------------

### deleteCommentMarker event message structure

Source: https://mattrbld.com/docs/preview-features/comments

Message structure sent by Mattrbld when a comment is deleted. Contains the feature, type, and payload with the comment object.

```json
{
  feature: 'comments',
  type: 'deleteCommentMarker',
  payload: {
    comment: <Comment>, // the deleted comment
  },
}
```

--------------------------------

### Tags Field Validation Default Configuration

Source: https://mattrbld.com/docs/fields/tags

Default validation options for the Tags field. Set min and max to limit the number of tags. The unit is always 'tags'.

```json
{
  "max": null,
  "min": null,
  "unit": "tags"
}
```

--------------------------------

### Checkboxes field default validation options

Source: https://mattrbld.com/docs/fields/checkboxes

Default validation options for the Checkboxes field. enforceMinMax is false by default, and min and max are null. The unit is 'selected'.

```json
{
  "enforceMinMax": false,
  "max": null,
  "min": null,
  "unit": "selected"
}
```

--------------------------------

### Number field validation options

Source: https://mattrbld.com/docs/fields/number

Default validation options for the Number field. The max and min options are null by default, and required is false.

```json
{
  "max": null,
  "min": null,
  "required": false
}
```

--------------------------------

### modechange event payload

Source: https://mattrbld.com/docs/preview-features/comments

Event sent when the Toggle Comments button is clicked. active indicates whether comment mode is on, canComment whether the user may comment.

```json
{
  feature: 'comments',
  type: 'modechange',
  payload: {
    active: true, // or false when deactivating
    canComment: true, // or false when not allowed
  },
}
```

--------------------------------

### Columns Field Validation Defaults

Source: https://mattrbld.com/docs/fields/columns

Default validation options for the Columns field. Set min and max to limit the number of columns. The unit is 'columns'.

```json
{
  "max": null,
  "min": null,
  "unit": "columns"
}
```

--------------------------------

### Reset comment marker position on moveFailed

Source: https://mattrbld.com/docs/preview-features/comments

In the postMessage handler's switch-case, handle the 'moveFailed' event by resetting the comment marker. The code deletes the existing marker and re-adds it if the comment has a position.

```javascript
// in the switch-case within the postMessage
// handler
case 'moveFailed':
  const { comment } = data.payload;
  // could also be a single function that resets
  // the position of the comment marker
  deleteCommentMarker(comment);
  if (comment && comment.position) {
    addCommentMarker(comment);
  }
  break;
```

--------------------------------

### Default validation options for Sortable List field

Source: https://mattrbld.com/docs/fields/list

Shows the default validation object for the Sortable List field. The enforceMinMax option enables or disables min/max constraints, with max and min as null by default and unit set to 'list items'.

```json
{
  "enforceMinMax": false,
  "max": null,
  "min": null,
  "unit": "list items"
}
```

--------------------------------

### Unformatted Text Field Validation Options

Source: https://mattrbld.com/docs/fields/text

Default validation options for the Unformatted Text field. Includes enforceMinMax, min/max bounds, regex pattern and error message, required flag, and unit set to length.

```json
{
  "enforceMinMax": true,
  "max": null,
  "min": null,
  "regex": null,
  "regexError": null,
  "required": false,
  "unit": "length"
}
```

--------------------------------

### Columns Field Options Defaults

Source: https://mattrbld.com/docs/fields/columns

Default configuration for the Columns field. Set allowEditing to false to prevent content editors from adding or removing columns. The itemLabel option customizes the label used to refer to a column.

```json
{
  "allowEditing": true,
  "itemLabel": "Row"
}
```

--------------------------------

### Unique ID field default options

Source: https://mattrbld.com/docs/fields/id

Default options for the Unique ID field. The type can be 'filepath', 'uuid', or 'template'. When type is 'template', idTemplate is used and editable is implicitly false.

```json
{
  "type": "uuid",
  "idTemplate": null,
  "editable": false
}
```

--------------------------------

### Update comment marker in postMessage handler

Source: https://mattrbld.com/docs/preview-features/comments

In the postMessage handler's switch-case, handle the 'updateCommentMarker' event by extracting the comment from the payload and calling a function to update the marker.

```javascript
// in the switch-case within the postMessage
// handler
case 'updateCommentMarker':
  const { comment } = data.payload;
  // a function that updates comment markers on
  // the preview page
  updateCommentMarker(comment);
  break;
```

--------------------------------

### Rows Field Validation Default Values

Source: https://mattrbld.com/docs/fields/rows

Default validation options for the Rows field: max, min, and unit.

```json
{
  "max": null,
  "min": null,
  "unit": "rows"
}
```

--------------------------------

### Checkboxes field default options

Source: https://mattrbld.com/docs/fields/checkboxes

Default options for the Checkboxes field. The type option controls display: 'inline' shows checkboxes next to each other, 'wide' shows each on its own line. The checkboxes option can be an array of values, an array of { label, value } objects, or an object with a path to a JSON file and a key to look up an options array.

```json
{
  "type": 'inline',
  "checkboxes": []
}
```

--------------------------------

### Unique ID field validation options

Source: https://mattrbld.com/docs/fields/id

Default validation options for the Unique ID field. The required option is set to true by default.

```json
{
  "required": true
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.