Design
The Livingdocs design is defined by 2 top-level project config properties: designSettings and components.
The components define the building blocks out of which you can create your documents. They are basically small HTML templates for things like paragraphs, images or embeds.
The design settings define global design properties like the CSS to use or how components are grouped together.
An example:
1
// projectConfig.designSettings: {...}
2
designSettings: {
3
assets: {
4
css: [
5
'https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css'
6
]
7
},
8
​
9
imageRendering: {
10
// strategy used if doc-image is declared on an <img> tag
11
imgTagRenderStrategy: 'srcSet',
12
// strategy used if doc-image is declared on any other tag
13
anyTagRenderStrategy: 'backgroundImage',
14
​
15
// configuration for the responsive 'backgroundImage' render strategy
16
backgroundImage: {
17
defaultWidth: 1200,
18
cssVars: {
19
'mobile-img': 600,
20
'tablet-img': 900
21
}
22
},
23
// configuration for the 'srcSet' render strategy
24
srcSet: {
25
defaultWidth: 1024,
26
widths: [
27
2048,
28
1024,
29
620,
30
320
31
],
32
sizes: ['100vw']
33
}
34
},
35
​
36
componentProperties: [{
37
label: 'Lead',
38
type: 'option',
39
value: 'paragraph--lead',
40
name: 'paragraph-style-lead'
41
}, {
42
label: 'Background Color',
43
type: 'style',
44
cssProperty: 'background-color',
45
name: 'css-background-color'
46
}],
47
​
48
componentGroups: [
49
{
50
name: 'text',
51
label: 'Text',
52
components: [
53
'title',
54
'p'
55
]
56
},
57
{
58
name: 'media',
59
label: 'Media',
60
components: [
61
'image',
62
'insta'
63
]
64
}
65
],
66
​
67
defaultComponents: {
68
paragraph: 'p',
69
image: 'image'
70
},
71
​
72
fieldExtractor: [
73
{
74
// metadata handle
75
identifier: 'title',
76
// 'text' / 'image' / 'cssProperty'
77
type: 'text',
78
// prefill from 'component.directive'
79
matches: ['title.title']
80
}
81
]
82
},
83
​
84
components: [
85
{
86
name: 'title',
87
label: 'Title',
88
iconUrl: 'https://livingdocs-assets.s3.amazonaws.com/magazine-design/assets/images/icons-components/icon_header_simple.svg',
89
directives: [
90
{
91
type: 'editable',
92
name: 'title',
93
maxLength: 5
94
}
95
],
96
html: "<h2 doc-editable=\"title\">\n Title\n</h2>"
97
},
98
{
99
name: 'p',
100
label: 'Paragraph',
101
iconUrl: 'https://livingdocs-assets.s3.amazonaws.com/magazine-design/assets/images/icons-components/icon_text.svg',
102
html: "<p class=\"text\" doc-editable=\"text\">\n Paragraph\n</p>"
103
},
104
{
105
name: 'image',
106
label: 'Bild',
107
iconUrl: 'https://livingdocs-assets.s3.amazonaws.com/magazine-design/assets/images/icons-components/icon_image.svg',
108
directives: [
109
{
110
name: 'image',
111
type: 'image',
112
allowOriginalRatio: true,
113
imageRatios: [
114
'16:9',
115
'1:1',
116
'4:3',
117
'3:4'
118
]
119
}
120
],
121
html: "<div class=\"m-asset-image m-asset-image--numbered\">\n <div class=\"m-asset-image__image\">\n <img doc-image=\"image\" />\n </div>\n <div class=\"m-asset-image__options\">\n <div class=\"a-asset-input\" doc-editable=\"caption\">Caption</div>\n <div class=\"a-asset-input\" doc-editable=\"source\">Source</div>\n </div>\n</div>"
122
},
123
{
124
name: 'insta',
125
label: 'Instagram',
126
iconUrl: 'https://livingdocs-assets.s3.amazonaws.com/magazine-design/assets/images/icons-components/icon_image.svg',
127
directives: [
128
{
129
name: 'insta',
130
type: 'include',
131
service: 'instagram'
132
}
133
],
134
html: "<div doc-include=\"insta\">\n <div>Instagram Include</div>\n</div>"
135
}
136
]
Copied!

Assets

Livingdocs uses CSS and possible JS assets to render documents. The assets object contains 2 keys, css and js, both of which are arrays and contain fully specified URLs to your CSS and JS files respectively. We advise you to upload the files to an AWS S3 bucket or similar and link them.

Component Properties

Component properties give users of the Livingdocs editor easy styling options for components. There are three types of properties:
  • option, turns a style (css class) on or off
  • select, select from a set of css classes
  • style, in tandem with doc-style directives, sets the style attribute of a tag
The value in case of option or select contains a CSS class from your CSS asset files.
Component Property
The schema looks as follows.
1
componentProperties: ms.arrayOf(ms.allOf([{
2
if: ms.obj({type: ms.const('option')}),
3
then: ms.strictObj({
4
type: ms.required.enum('option'),
5
name: 'string:required',
6
label: 'string',
7
value: 'string:required'
8
})
9
}, {
10
if: ms.obj({type: ms.const('select')}),
11
then: ms.strictObj({
12
type: ms.required.enum('select'),
13
name: 'string:required',
14
label: 'string',
15
// must contain one empty option
16
options: ms.required.arrayOf(ms.strictObj({
17
caption: 'string:required',
18
value: 'string'
19
}))
20
})
21
}, {
22
if: ms.obj({type: ms.const('style')}),
23
then: ms.strictObj({
24
type: ms.required.enum('style'),
25
name: 'string:required',
26
label: 'string',
27
cssProperty: 'string:required'
28
})
29
}]))
Copied!

Component Groups

has UI support
With component groups you can visually group together similar components, e.g. "Text components" for use in the Livingdocs editor sidebar. We advise you to use the UI in "Project Setup - Component Library" to create and re-arrange groups.

Default Components

Livingdocs knows 2 types of default components:
  • Paragraph, automatic insert when a user presses "Enter" in the editor, typically a p tag
  • Image, automatic insert when a user drags an image to Livingdocs, e.g. from the Desktop
You have to configure the handle of the respective component that should be inserted.

Field Extractor

The field extractor allows you to one way synchronising metadata fields with values from the document. As long as the metadata field is not overwritten manually, the sync is active. A common use case is to use the document title in a metadata field title.
Example
1
fieldExtractor: [
2
{
3
identifier: 'title',
4
type: 'text',
5
matches: ['title.title']
6
}
7
]
Copied!
Properties
  • identifier - metadata field handle, you want to sync to
  • type data type
    • text for doc-editable directives
    • image for doc-image
    • cssProperty for doc-style
    • Other design directives are currently not supported.
  • matches defines an array of component.directive pairs from which the content should be synced into the metadata field. E.g. for a component named "title" that has a doc-editable directive "title", you would write "title.title". When type is set to cssProperty one can define which CSS property to extract, e.g. color.

Components

Components are the building blocks of Livingdocs documents. In essence a component is a combination of an HTML template with declarative Livingdocs directive attributes (doc- directives) and a JSON with configuration for those directives.
1
"name": "p",
2
"label": "Paragraph",
3
"iconUrl": "https://livingdocs-assets.s3.amazonaws.com/magazine-design/assets/images/icons-components/icon_text.svg",
4
"directives": [{
5
"name": "p",
6
"type": "editable",
7
"plainText": true
8
}],
9
"html": "<p class=\"text\" doc-editable=\"text\">\n Paragraph\n</p>"
Copied!
The above component definition will render a paragraph with editable text. Only plaintext is allowed in this text.
Livingdocs supports the following directive types.
Type
Description
editable
The content of this tag is editable text by the user. details​
image
The user can select and image that is set as a src attribute on <img> tags and as background-image style on other tags. details​
container
This tag can contain other components. details​
link
The href attribute of this tag can be set to a link by the user. details​
include
Inside of this tag, a remote micro service will render an edge-side include of the given type. details​
html
The content of this tag is freeform HTML. This can be used to embed tweets or IFrames. details​
style
Allows a user to set the style attribute on a DOM node details​
For the declaration in HTML always prepend doc- to the type.
Apart from directives, components also have properties.
  • allowedParents, array of strings, defines in which components that have container directives (you must give the component name) this component may be added
  • excludeFromTextCount, true | false, if true no editable directives in this component are counted towards the document text count
  • properties, array of strings, references to component properties (see above) that should be shown in the properties panel if this component is selected in the editor
  • iconUrl, string, fully specified URL to an icon that is displayed for this component in the editors sidebar
  • label, string, the title that this component has
  • description, string, a descriptive text for this component
  • name, string, the system name of this component
Last modified 1yr ago