Skip to content

Commit d74a3f6

Browse files
bdenhambdenham
committed
MAGEDOC-3434: Edit custom toolbar topic
1 parent 243b315 commit d74a3f6

File tree

5 files changed

+413
-70
lines changed

5 files changed

+413
-70
lines changed

‎docs/how-to/how-to-add-custom-toolbar.md

Lines changed: 76 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,22 @@
11
# How to add a custom Toolbar
22

3-
## What's in this topic
4-
5-
This document outlines how to implement the inline editing toolbar for any content type. This feature is used within the heading to allow for easy modification of the heading type and alignment. It can be used within your content types to quickly change common things without needing to open the full editor.
3+
This topic shows you how to implement an inline toolbar for your content type. You can see an example of a toolbar in Page Builder's Heading content type, as shown here:
64

75
![Page Builder toolbar](../images/toolbar.png)
86

9-
## Overview
10-
11-
To add a custom toolbar to a Page Builder content block:
7+
Toolbars provide end-users with a quick way to change common properties of your content type (such as text alignment and heading types) without needing to open the full editor. The toolbar does not replace the need for form fields in the editor; it simply extends those fields.
128

13-
1. [Add a toolbar configuration](#toolbarConfig)
14-
2. [Add a toolbar template](#toolbarTpl)
9+
## How the Toolbar works
1510

16-
## Add a toolbar configuration {#toolbarConfig}
11+
The diagram below shows the basic steps for adding a toolbar to your content type. It also shows how the various parts connect and work together.
1712

18-
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.
13+
![](../images/how-toolbars-work.png)
1914

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

23-
In the Heading example, the `Toolbar` constructor requires its parent preview and the toolbar options you want to include as follows:
2416

25-
```javascript
26-
new Toolbar(this, this.getToolbarOptions());
27-
```
17+
## Step 1: Add toolbar options
2818

29-
where `this.getToolbarOptions()`returns the toolbar options. For example, the Heading toolbar's three text-alignment options are defined as follows:
19+
Toolbar options are the clickable items in a toolbar that represent the property values of a form field. For example, the Heading content type adds toolbar options for the `text_align` field from `pagebuilder_base_form.xml`. The Heading adds the values of the `text_align` field (`left`, `center`, and `right`) as items on the toolbar, represented with the images provided by the icon CSS classes as shown here:
3020

3121
```typescript
3222
{
@@ -52,28 +42,79 @@ where `this.getToolbarOptions()`returns the toolbar options. For example, the He
5242
},
5343
```
5444

55-
Option property descriptions:
45+
The `OptionInterface` and `ValueInterface` define the structure of toolbar options. You can find these interfaces in `magento2-page-builder/app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type-toolbar.types.ts`. Descriptions of the elements follow:
46+
47+
| Element | Description |
48+
| -------- | ------------------------------------------------------------ |
49+
| `key` | The field `name` you are binding to. For example: `<field name="quote_css"...>` |
50+
| `type` | The `formElement` of the key field. For example: `<field ... formElement="select">` |
51+
| `values` | Array of field option values. |
52+
| `value` | Field option value, such as a CSS class (as shown in the code example). |
53+
| `label` | Field option label, such as a label for a select option (as shown in the code example) |
54+
| `icon` | CSS class name for the icon to display in the toolbar to represent the field's option. If you don't include a CSS class, the toolbar will display the label instead. |
5655

57-
| Element | Description |
58-
| ------------------- | ---------------------------------------------------------------------------------- |
59-
| `key` | Describes the menu section name in the menu (comparable to a CSS property, `text_align`). |
60-
| `type` | Describes the element type (comparable to the HTML `input` type). |
61-
| `values` | Array of values for each option. |
62-
| `value` | Value referenced in the dataStore (comparable to a CSS property value). |
63-
| `label` | Label of the option. If no icon is specified, this will be displayed |
64-
| `icon` | Name of CSS class to use for the icon. |
56+
## Step 2: Create `Toolbar` instance
6557

66-
## Add toolbar template {#toolbarTpl}
58+
To create an instance of the Page Builder toolbar in your `preview.js` component:
6759

68-
In your content block template, add the toolbar events to your main toolbar container, and insert the toolbar template:
60+
- **Import Page Builder's `Toolbar` class** (`'Magento_PageBuilder/js/content-type-toolbar'`)
61+
- **Call the toolbar constructor.** The `Toolbar` constructor requires you to pass your `Preview` component and the array of toolbar options you created in step 1 (`this.toolbar = new Toolbar(this, this.getToolbarOptions());`). You can find Page Builder's `Toolbar` class in `magento2-page-builder/app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type-toolbar.ts`.
6962

70-
```html
71-
<div class="pagebuilder-toolbar-container" tabindex="0" event="{ focusin: toolbar.onFocusIn, focusout: toolbar.onFocusOut }">
72-
<with args="toolbar">
73-
<render args="template" />
74-
</with>
63+
```js
64+
define([
65+
'Magento_PageBuilder/js/content-type/preview',
66+
'Magento_PageBuilder/js/content-type-toolbar',
67+
], function (PreviewBase, Toolbar) {
68+
'use strict';
69+
70+
function Preview(parent, config, stageId) {
71+
PreviewBase.call(this, parent, config, stageId);
72+
this.toolbar = new Toolbar(this, this.getToolbarOptions());
73+
}
74+
});
75+
```
76+
77+
## Step 3: Add toolbar markup
78+
79+
Within your `preview.html` template, use a `div` element (with CSS class and events) to wrap whichever element in your template you want the toolbar to act on. For example, the custom Quote content type wraps its `<blockquote>` element within a `div` with the toolbar's CSS class and event binding, as shown here:
80+
81+
``` html
82+
<!--preview.html-->
83+
<div attr="data.main.attributes" ko-style="data.main.style" class="pagebuilder-content-type" css="data.main.css" event="{ mouseover: onMouseOver, mouseout: onMouseOut }, mouseoverBubble: false">
84+
<render args="getOptions().template"/>
85+
<div class="pagebuilder-toolbar-container"
86+
tabindex="0"
87+
event="{ focusin: toolbar.onFocusIn, focusout: toolbar.onFocusOut }">
88+
<with args="toolbar">
89+
<render args="template"/>
90+
</with>
91+
<blockquote class="quote-content" attr="data.quote.attributes" css="data.quote.css" ko-style="data.quote.style" data-bind="liveEdit: { field: 'quote_text', placeholder: $t('Enter Quote') }"></blockquote>
92+
</div>
93+
<div class="quote-author" attr="data.author.attributes" ko-style="data.author.style" css="data.author.css" data-bind="liveEdit: { field: 'quote_author', placeholder: $t('Enter Author') }"></div>
94+
<div class="quote-description" attr="data.author_title.attributes" ko-style="data.author_title.style" css="data.author_title.css" data-bind="liveEdit: { field: 'quote_author_desc', placeholder: $t('Enter Description') }"></div>
7595
</div>
7696
```
7797

78-
An example implementation can be found in the Heading content block:
79-
`app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type/heading/default/preview.html`
98+
**Line 4:** Use this CSS class to correctly format and control the screen placement of the toolbar when the wrapped HTML element receives focus.
99+
100+
**Line 5:** Set a `tabindex` of 0 to ensure that the `div` wrapper is part of the default focus order for tabbing.
101+
102+
**Line 6:** Use the the Toolbar's `onFocusIn` and `onFocusOut` methods to handle the events for `focusin` and `focusout`.
103+
104+
**Lines 7-9:** Add the toolbar's HTML template as returned from your `toolbar` instance of the `Toolbar` class.
105+
106+
```js
107+
get template(): string {
108+
return "Magento_PageBuilder/content-type-toolbar";
109+
}
110+
```
111+
112+
You can find this HTML template here: `app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type-toolbar.html`.
113+
114+
## Example code
115+
116+
Heading content type example code:
117+
118+
- `app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type/heading/default/preview.html`
119+
- `app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/heading/preview.ts`
120+

‎docs/images/how-toolbars-work.png

187 KB
Loading

0 commit comments

Comments
 (0)