Front Matter CMS - Extensibility module

This module provides a way to extend the CMS its UI with custom functionality, and it provides helpers for creating your custom content or media scripts.

Custom scripts

To make it easier to create your custom scripts, you can make use of the @frontmatter/extensibility module its ContentScript, MediaScript, and PlaceholderScript classes.

$3

If you want to write a script for content management in Front Matter CMS, you can make use of the ContentScript class. This class provides methods to retrieve the arguments, ask questions, and let the script know its done.

#### Get arguments

To retrieve all arguments, you can use the getArguments method.

``js
import { ContentScript } from '@frontmatter/extensibility';

const { command, scriptPath, workspacePath, filePath, frontMatter, answers } = ContentScript.getArguments();
`

#### Ask questions

To ask a question to the user in the CMS, you can use the askQuestions method:

`js
if (!answers) {
MediaScript.askQuestions([{
name: "customId",
message: "Which ID do you want to use?",
default: ""
}]);
return;
}
`

In case you want to have a multi-select question, you can just add the options to the question:

`js
if (!answers) {
MediaScript.askQuestions([{
name: "category",
message: "Which category do you want to use?",
options: [
"Category 1",
"Category 2",
"Category 3"
]
}]);
return;
}
`

> Important: Front Matter will execute the same script, so you first need to check if the answers were provided.

You can retrieve the answer from the answers object:

`js
const customId = answers.customId;
`

#### Update front matter

To let the CMS know you want to update the article its front matter, you can make use of the updateFrontMatter method:

`js
ContentScript.updateFrontMatter({
"field": "value"
});
`

#### Open a file or page on completion

To let the CMS know you want to open a file or page after the script is done, you can make use of the open method:

`js
// Open a URL
ContentScript.open("https://frontmatter.codes");

// Or open a file
ContentScript.open("./path/to/file.md");
`

#### Done

To let the CMS know you are done with your script, you can make use of the done method:

`js
ContentScript.done("The script is done");
`

$3

The MediaScript class provides the same functionality as the ContentScript class, but it is used for media management scripts. There are a couple differences:

- Arguments will not provide the frontMatter object;
- You cannot make use of the updateFrontMatter method.

Additionally, they provide the following methods:

- MediaScript.copyMetadata(source, destination): This method will copy the metadata from the source file to the destination file.
- MediaScript.copyMetadataAndDelete(source, destination); This method will copy the metadata from the source file to the destination file and delete the source file.
- MediaScript.delete(source): This method will delete the source file.

$3

The PlaceholderScript class provides the same functionality as the ContentScript class, but it is used for placeholders which can be used on content creation. The main difference between the ContentScript and PlaceholderScript is that it will not provide the frontMatter object. Instead it returns the title of the page.

UI extensibility

$3

Card extensibility points:

- Image
- Footer

Extension version 9.0.0 and higher:

- Draft status
- Date
- Title
- Description
- Tags

$3

- Custom panel view
- Custom fields

Usage

You can make use of ESM modules in order to make use of the extensibility dependency. We recommend to use the CDN from Skypack or jsdelivr.

URLs:

- https://cdn.skypack.dev/@frontmatter/extensibility
- https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm
- https://esm.run/@frontmatter/extensibility

$3

Turn on the development mode in order to quickly reload the webviews (panel + dashboard) when you make changes to the code.

`js
import { enableDevelopmentMode } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

enableDevelopmentMode();
`

$3

`js
import { registerCardImage } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardImage(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardStatus } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardStatus(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardDate } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardDate(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardTitle } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardTitle(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardDescription } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardDescription(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardTags } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardTags(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerCardFooter } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {string} filePath - The path of the file
* @param {object} data - The metadata of the file
* @returns {string} - The HTML to be rendered in the card footer
*/
registerCardFooter(async (filePath, metadata) => {
return Your HTML;
});
`

$3

`js
import { registerPanelView } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";

/**
* @param {object} data - The metadata of the file
* @returns {object} - The view to be rendered in the panel
*/
registerPanelView(async (metadata) => {
return {
title: "Custom View",
content:

`js
import { registerCustomField } from "https://cdn.jsdelivr.net/npm/@frontmatter/extensibility/+esm";
import { css, html, LitElement } from "https://esm.run/lit";

let CustomFieldValueChange;

class CustomField extends LitElement {
static styles = css
input {
border: 1px solid transparent;
box-sizing: border-box;
font-family: var(--vscode-font-family);
padding: var(--input-padding-vertical) var(--input-padding-horizontal);
color: var(--vscode-input-foreground);
outline: none;
background-color: var(--vscode-input-background);
width: 100%;
}

input:focus {
border: 1px solid var(--vscode-inputValidation-infoBorder);
}
;

static properties = {
inputValue: {
type: String,
},
};

constructor() {
super();
this.inputValue = "";
}

_internalChange(e) {
this.inputValue = e.target.value;
CustomFieldValueChange(e.target.value);
}

render() {
return html
type="text"
value="${this.inputValue}"
@change=${(e) => this._internalChange(e)}
/>
;
}
}
customElements.define("custom-field", CustomField);

/**
* @param {string} name - The name of the custom field to use in the content-type
* @param {function} callback - The callback that will be used for rendering the custom field
*/
registerCustomField("customField", async (value, onChange) => {
// Bind the event handler for the onChange evet
CustomFieldValueChange = onChange;
// Return the HTML of the custom field
return

;
});
``

Issues

Please report any issues you find in the Front Matter CMS issue list.