Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/amplience/dc-extension-dom-editor

Last synced: 3 months ago
JSON representation

Host: GitHub
URL: https://github.com/amplience/dc-extension-dom-editor
Owner: amplience
Created: 2021-04-08T13:42:17.000Z (over 3 years ago)
Default Branch: master
Last Pushed: 2024-06-18T04:29:51.000Z (5 months ago)
Last Synced: 2024-07-13T14:35:44.319Z (4 months ago)
Language: TypeScript
Size: 4.99 MB
Stars: 0
Watchers: 18
Forks: 3
Open Issues: 20
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# dc-extension-dom-editor

![Extension](media/extension.png)

The DOM Editor extension allows content authors to create and edit a hierarchy of components to structure their content in an abstract manner, for use in a Document Object Model.

This project requires Node 16.x to build.

## How to install

This extension can optionally be [registered](https://amplience.com/docs/development/registeringextensions.html) against a Hub with in the Dynamic Content application (Developer -> Extensions), to allow it to load within that Hub.

### Register Extension

![Setup](media/setup.png)

* Category: Content Field
* Label: DOM Editor
* Name: dc-extension-dom-editor _(needs to be unique with the Hub)_
* URL: [https://dom-editor.extensions.content.amplience.net](https://dom-editor.extensions.content.amplience.net)
* Description: DOM Editor extension _(can be left blank, if you wish)_
* Initial height: 1200

Note: You can use our deployed version of this extension (builds from the "production" branch) - [https://dom-editor.extensions.content.amplience.net](https://dom-editor.extensions.content.amplience.net)

_As this is an open source project you're welcome to host your own "fork" of this project. You can use any standard static hosting service (Netlify, Amplify, Vercel, etc.) if you wish. Further information can be found on the [Hosting](HOSTING.md) page._

To use the DOM Editor, you first need to add a field to your content type schema that is configured to use the DOM Editor extension.

### Assign the extension to schema

If you have registered your extension as detailed above, you then simply need to add a field to your content type schema that is configured to use the DOM Editor extension.

```json
"propertyName": {
"type": "object",
"ui:extension": {
"name": "dc-extension-dom-editor",
"params": {
"slots": {},
"components": []
}
}
}
```

It is also possible to to add an instance of the extension to a content type schema without first registering it. This can be done by referencing the extension by its URL instead of its name.

```json
"propertyName": {
"type": "object",
"ui:extension": {
"url": "https://dom-editor.extensions.content.amplience.net",
"params": {
"slots": {},
"components": []
}
}
}
```

## Configuration

You can then configure your instance of the DOM Editor with slots and their allowable components. These should be added to the `params` object in your `ui:extension` field.

### Slots:

```json
"slotName": {
"title":"string",
"allow": []
}
```

| Property | Format | Description |
| -------- | ------------------------------ | ------------------------------------------------------------ |
| title | string | The title of the slot.
If not defined, the title will default to the property name.
If 2 or more slots are defined at the same level, the title will be displayed within the extension. |
| allow | string OR array,
required | Defines which [components](#components) can be added to this slot.
Contains component names as an array of strings.
Use `"*"` if you want all components to be valid children. |

#### Example slots:

##### Slot which can contain only specific components

```json
"header": {
"title":"Header",
"allow": [
"header-link",
"header-inline"
]
}
```

##### Slot which can contain any components

```json
"body": {
"title":"Body",
"allow": "*"
}
```

### Components:

```json
{
"name": "string",
"title": "string",
"group": "string",
"infoLink": "string",
"icon": "string",
"properties": {},
"preview": {},
"slots": {}
}
```

| Property | Format | Description |
| ---------- | --------------------- | ------------------------------------------------------------ |
| name | string,
required | The name of the component.
Used to identify the component within the schema, and for adding as an allowed component to a slot. |
| title | string | The friendly label of the component.
The title will be shown in the component's top bar within the extension. |
| group | string | The name of a group under which this component will be categorised.
All components with a matching group will show under the same group in the extension.
If no group is provided, this component will display at the top level of the component tray. |
| infoLink | string | A link to an external resource.
Can be used for providing documentation for your custom components. |
| icon | string | A custom icon for the component for easier identification.
Will accept [Material Icons](https://fonts.google.com/icons?selected=Material+Icons+Outlined) by name (eg `"image"`), or a custom image as a URL.
If no value provided, will default to `settings` Material icon. |
| properties | object | Defines child content field properties for this component.
[Supported content field properties](#supported-content-field-properties). |
| preview | object | Defines text previews for this component.
Provided as a relative path to the text property within the component you wish to preview. |
| slots | object | Defines child [slots](#slots) for this component.
Cannot backreference slots defined at a higher level. |

#### Supported content field properties

| Type | Description |
| ------- | ------------------------------------------------------------ |
| string | A string of text that may contain unicode characters.
Supports the `enum` validation keyword, and `default` keyword.
Supports the `color` format, which will produce a color picker in the extension UI. |
| number | Any numeric type. It can be an integer or floating point number.
Supports the `enum` validation keyword, and `default` keyword. |
| boolean | A value that can be true or false.
Supports the `default` keyword. |
| object | A JSON object. Supports a $ref to the following Dynamic Content [choosers](https://amplience.com/docs/integration/choosers.html#using-the-schema-editor-to-add-media-and-content-links):
`http://bigcontent.io/cms/schema/v1/core#/definitions/image-link`
`http://bigcontent.io/cms/schema/v1/core#/definitions/content-link`
`http://bigcontent.io/cms/schema/v1/core#/definitions/content-reference` |

#### Example components:

Below are some example components which are loosely associated to one-another, to help you get started.

##### A basic component with no child properties

```json
{
"name": "header-link",
"title": "Basic Component"
}
```

##### Grouped component with content-link property

```json
{
"name": "header-link",
"title": "Header (Content-Link)",
"icon": "view_headline",
"group": "DC Links",
"properties": {
"content": {
"title": "Header",
"allOf": [
{
"$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content-link"
},
{
"properties": {
"contentType": {
"enum": [
"https://example.com/schemaUri.json"
]
}
}
}
]
}
}
}
```

##### Grouped component with image-link property

```json
{
"name": "simple-image",
"title": "Image",
"icon": "image",
"group": "DC Links",
"properties": {
"image": {
"title": "Image",
"description": "A simple Amplience Image-Link",
"allOf": [
{
"$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
}
]
}
}
}
```

##### Component with multiple inline properties & text preview

```json
{
"name": "copy-stack",
"title": "Copy Stack",
"icon": "horizontal_split",
"properties": {
"headline": {
"title": "Headline",
"description": "A short headline.",
"type": "string"
},
"headline-size": {
"title": "Headline Size",
"type": "string",
"enum": [
"h1",
"h2",
"h3",
"h4",
"h5",
"h6"
]
},
"support-copy": {
"title": "Support Copy",
"description": "A longer description.",
"type": "string"
}
},
"preview": {
"text": "/headline"
}
}
```

##### Component with its own generic slot

```json
{
"name": "container",
"title": "Container",
"icon": "inventory_2",
"slots": {
"children": {
"allow": "*"
}
}
}
```

##### Component with named & labelled slots

```json
{
"name": "split-block",
"title": "Split Block",
"icon": "inventory_2",
"slots": {
"image": {
"title": "Image",
"allow": "simple-image"
},
"copy-stack": {
"title": "Copy Stack",
"allow": "*"
}
}
}
```

### Example Schema

Below is an example schema composed from variations of the slots and components detailed above, which can be used to help you get started with configuring the extension within a new or existing content type schema.

```json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "...",
"title": "DOM Editor",
"description": "Example schema using the DOM Editor extension",
"allOf": [
{
"$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/content"
}
],
"type": "object",
"properties": {
"layout": {
"type": "object",
"ui:extension": {
"name": "dc-extension-dom-editor",
"params": {
"height": 1200,
"slots": {
"header": {
"title": "Header",
"allow": [
"header",
"image"
]
},
"body": {
"title": "Body",
"allow": [
"container"
]
}
},
"components": [
{
"name": "header",
"title": "Header",
"icon": "title",
"group": "Text Components",
"properties": {
"headline": {
"title": "Headline",
"description": "A short headline.",
"type": "string"
},
"headline-size": {
"title": "Headline Size",
"type": "string",
"enum": [
"h1",
"h2",
"h3",
"h4",
"h5",
"h6"
],
"default": "h1"
}
},
"preview": {
"text": "/headline"
}
},
{
"name": "paragraph",
"title": "Paragraph",
"icon": "view_headline",
"group": "Text Components",
"properties": {
"paragraph": {
"title": "Paragraph",
"description": "A paragraph of text.",
"type": "string"
},
"colour": {
"title": "Text Colour",
"description": "Text colour for this paragraph.",
"type": "string",
"format": "color"
}
},
"preview": {
"text": "/paragraph"
}
},
{
"name": "container",
"title": "Container",
"icon": "inventory_2",
"slots": {
"children": {
"allow": "*"
}
}
},
{
"name": "image",
"title": "Image",
"icon": "image",
"infoLink": "https://amplience.com/docs/dynamicmedia/dmapireference.html",
"properties": {
"image": {
"title": "Image",
"description": "A simple Amplience Image-Link",
"allOf": [
{
"$ref": "http://bigcontent.io/cms/schema/v1/core#/definitions/image-link"
}
]
}
}
}
]
}
}
}
},
"propertyOrder": []
}
```