Mattrbld

https://mattrbld.com/docs
Admin
Mattrbld is a headless, Git-based content management system (CMS) that enables users to manage,...
Tokens:80,589
Snippets:670
Trust Score:6.3
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### 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
  }
}
```

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

### 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
}
```

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

### 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'
```

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

### 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>
```

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

### 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"
}
```

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

### 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
  }
]
```

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

### 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;
```

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

### 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
```

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

### 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;
```
Tokens:
Raw