Skip to content

Commit a9dea71

Browse files
author
Bruce Denham
committed
Updated custom toolbar docs
1 parent 63fb1a5 commit a9dea71

File tree

1 file changed

+164
-82
lines changed

1 file changed

+164
-82
lines changed

‎app/code/Magento/PageBuilder/docs/toolbar.md

Lines changed: 164 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -44,95 +44,180 @@ This document outlines how to add a custom toolbar in Page Builder. It's a simpl
4444

4545
## Overview
4646

47-
To add toolbar customization to a Page Builder content block:
48-
1. [Add toolbar configuration](#toolbarConfig)
49-
2. [Add toolbar template](#toolbarTpl)
50-
51-
## Add toolbar configuration
47+
To add a custom toolbar to a Page Builder content block:
48+
1. [Add a toolbar configuration](#toolbarConfig)
49+
2. [Add a toolbar template](#toolbarTpl)
50+
51+
## Add a toolbar configuration
52+
53+
To add a Toolbar configuration to your content block, you need to create a new instance of the `Toolbar` class, then add configuration options to it. Page Builder's Heading content block (`app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/heading/preview.ts`) provides an example of what you can do in your own content block:
54+
55+
```typescript
56+
import $ from "jquery";
57+
import events from "uiEvents";
58+
import _ from "underscore";
59+
import ContentTypeConfigInterface from "../../content-type-config.d";
60+
import Toolbar from "../../content-type-toolbar";
61+
import ToolbarOptionInterface from "../../content-type-toolbar/option.d";
62+
import ContentTypeInterface from "../../content-type.d";
63+
import ContentTypeReadyEventParamsInterface from "../content-type-ready-event-params.d";
64+
import ObservableUpdater from "../observable-updater";
65+
import BasePreview from "../preview";
66+
67+
export default class Heading extends BasePreview {
68+
public toolbar: Toolbar;
69+
private element: Element;
70+
71+
/**
72+
* @param {ContentTypeInterface} parent
73+
* @param {ContentTypeConfigInterface} config
74+
* @param {ObservableUpdater} observableUpdater
75+
*/
76+
constructor(
77+
parent: ContentTypeInterface,
78+
config: ContentTypeConfigInterface,
79+
observableUpdater: ObservableUpdater,
80+
) {
81+
super(parent, config, observableUpdater);
82+
this.toolbar = new Toolbar(
83+
this,
84+
this.getToolbarOptions(),
85+
);
86+
}
87+
88+
/**
89+
* On render init the tabs widget
90+
*
91+
* @param {Element} element
92+
*/
93+
public afterRender(element: Element): void {
94+
this.element = element;
95+
}
96+
97+
public bindEvents() {
98+
super.bindEvents();
99+
100+
// When a heading is dropped for the first time show heading toolbar
101+
events.on("heading:block:dropped:create", (args: ContentTypeReadyEventParamsInterface) => {
102+
if (args.id === this.parent.id) {
103+
_.delay(() => {
104+
$(this.element).focus();
105+
}, 100); // 100 ms delay to allow for heading to render
106+
}
107+
});
108+
}
109+
110+
/**
111+
* Build and return the tool bar options for heading
112+
*
113+
* @returns {ToolbarOptionInterface[]}
114+
*/
115+
private getToolbarOptions(): ToolbarOptionInterface[] {
116+
return [
117+
{
118+
key: "heading_type",
119+
type: "select",
120+
values: [
121+
{
122+
value: "h1",
123+
label: "H1",
124+
icon: "",
125+
},
126+
{
127+
value: "h2",
128+
label: "H2",
129+
icon: "",
130+
},
131+
{
132+
value: "h3",
133+
label: "H3",
134+
icon: "",
135+
},
136+
{
137+
value: "h4",
138+
label: "H4",
139+
icon: "",
140+
},
141+
{
142+
value: "h5",
143+
label: "H5",
144+
icon: "",
145+
},
146+
{
147+
value: "h6",
148+
label: "H6",
149+
icon: "",
150+
},
151+
],
152+
},
153+
{
154+
key: "text_align",
155+
type: "select",
156+
values: [
157+
{
158+
value: "left",
159+
label: "Left",
160+
icon: "icon-pagebuilder-align-left",
161+
},
162+
{
163+
value: "center",
164+
label: "Center",
165+
icon: "icon-pagebuilder-align-center",
166+
},
167+
{
168+
value: "right",
169+
label: "Right",
170+
icon: "icon-pagebuilder-align-right",
171+
},
172+
],
173+
},
174+
];
175+
}
176+
}
177+
```
52178

53-
Add configuration options to your content block preview. This is an array of options:
179+
In the Heading example, the `Toolbar` constructor requires its parent preview and the toolbar options you want to include:
54180

55-
| Element | Description |
56-
| ------------------- | ------------------------------------------------------------------------ |
57-
| `key` | Describes the group name in the menu. |
58-
| `type` | Describes the element type. |
59-
| `values` | Array of values for each option. |
60-
| `value` | Value referenced in the dataStore. |
61-
| `label` | Label of the option. If no icon is specified, this will be displayed |
62-
| `icon` | Name of CSS class to use for the icon. |
181+
```javascript
182+
new Toolbar(this, this.getToolbarOptions());
183+
```
63184

185+
where `this.getToolbarOptions()`returns the toolbar options. For example, the Heading toolbar's three text-alignment options are defined as follows:
64186

65-
```javascript
66-
private getToolbarOptions(): ToolbarOptionInterface[] {
67-
return [
187+
```typescript
188+
{
189+
key: "text_align",
190+
type: "select",
191+
values: [
68192
{
69-
key: "heading_type",
70-
type: "select",
71-
values: [
72-
{
73-
value: "h1",
74-
label: "H1",
75-
icon: "",
76-
},
77-
{
78-
value: "h2",
79-
label: "H2",
80-
icon: "",
81-
},
82-
{
83-
value: "h3",
84-
label: "H3",
85-
icon: "",
86-
},
87-
{
88-
value: "h4",
89-
label: "H4",
90-
icon: "",
91-
},
92-
{
93-
value: "h5",
94-
label: "H5",
95-
icon: "",
96-
},
97-
{
98-
value: "h6",
99-
label: "H6",
100-
icon: "",
101-
},
102-
],
193+
value: "left",
194+
label: "Left",
195+
icon: "icon-pagebuilder-align-left",
103196
},
104197
{
105-
key: "text_align",
106-
type: "select",
107-
values: [
108-
{
109-
value: "left",
110-
label: "Left",
111-
icon: "icon-pagebuilder-align-left",
112-
},
113-
{
114-
value: "center",
115-
label: "Center",
116-
icon: "icon-pagebuilder-align-center",
117-
},
118-
{
119-
value: "right",
120-
label: "Right",
121-
icon: "icon-pagebuilder-align-right",
122-
},
123-
],
198+
value: "center",
199+
label: "Center",
200+
icon: "icon-pagebuilder-align-center",
124201
},
125-
];
126-
}
127-
```
128-
129-
Pass toolbar configuration to a new instance of Toolbar.
130-
```javascript
131-
new Toolbar(this, this.getToolbarOptions());
202+
{
203+
value: "right",
204+
label: "Right",
205+
icon: "icon-pagebuilder-align-right",
206+
},
207+
],
208+
},
132209
```
210+
Option property descriptions:
211+
212+
| Element | Description |
213+
| ------------------- | ---------------------------------------------------------------------------------- |
214+
| `key` | Describes the group name in the menu (comparable to a CSS property, `text_align`). |
215+
| `type` | Describes the element type (comparable to the HTML `input` type). |
216+
| `values` | Array of values for each option. |
217+
| `value` | Value referenced in the dataStore (comparable to a CSS property value). |
218+
| `label` | Label of the option. If no icon is specified, this will be displayed |
219+
| `icon` | Name of CSS class to use for the icon. |
133220

134-
An example implementation can be found in the Heading content block:
135-
`app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/heading/preview.ts`
136221

137222
## Add toolbar template
138223

@@ -145,7 +230,4 @@ In your content block template, add the toolbar events to your main toolbar cont
145230
</div>
146231
```
147232

148-
An example implementation can be found in the Heading content block:
149-
`app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type/heading/default/preview.html`
150-
151233

0 commit comments

Comments
 (0)