Skip to content

Commit 3880851

Browse files
davemacaulaydavemacaulay
authored
Merge pull request #383 from magento-obsessive-owls/PB-73
PB-73: Create Appearances example and documentation
2 parents dfe36e7 + 1cf1891 commit 3880851

16 files changed

+582
-123
lines changed

‎docs/create-custom-content-type/step-1-add-configuration.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# Step 1: Add configuration
22

3-
The configuration file defines the settings and references to your content type files. You will return to this file often to update references and change settings during the development process.
3+
The configuration file defines the settings and references to your content type files. You will return to this file often to update references and change settings during the development process.
44

55
Files referenced from the configuration include the HTML templates, the JavaScript components, the icon displayed for your content type in the Page Builder panel, and the UI component form for your content type editor within the Admin.
66

77
![configuration-hub](../images/configuration-hub.png)
88

99
## Configuration conventions
1010

11-
By convention, Page Builder requires the configuration file to be in the `<module_name>/view/adminhtml/pagebuilder/content_type` or `content-type` directory.
11+
By convention, Page Builder requires the configuration file to be in the `<module_name>/view/adminhtml/pagebuilder/content_type` directory.
1212

1313
The name of your configuration file should reflect the name of your content type prefixed by your module vendor name and separated by an underscore (_). For example, our module name is `Example/PageBuilderQuote` and our content type is a quote control, so we name our configuration file `example_quote.xml` and add it to our module within the following directory structure (`view/adminhtml/pagebuilder/content_type/`):
1414

@@ -21,7 +21,6 @@ The reason we suggest prefixing your content type with your vendor name is to pr
2121

2222
Only a subset of configuration elements are described in our Quote example (enough to understand the basic role of the configuration file). For more details, refer to [Content type configurations](../reference/configurations.md) and [Additional configurations](../how-to/how-to-add-additional-configurations.md).
2323

24-
2524
The following configuration is from the Quote content type. An overview of these elements and attributes are described in the tables that follow.
2625

2726
```xml
@@ -74,7 +73,7 @@ The `type` element defines the key properties of your content type. The attribut
7473

7574
## The `children` element
7675

77-
The `children` element determines if your content type can contain other content types as children. In the Admin UI, it either allows or prevents you from dragging and dropping *other* content types from the panel into *your* content type.
76+
The `children` element determines if your content type can contain other content types as children. In the Admin UI, it either allows or prevents you from dragging and dropping *other* content types from the panel into *your* content type.
7877

7978
```xml
8079
<children default_policy="deny"/>

‎docs/extend-existing-content-type/step-1-create-extension-module.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,5 +45,4 @@ From your Magento root directory, use `bin/magento setup:upgrade` to install and
4545

4646
## Next
4747

48-
[Step 2: Extend appearances](step-2-extend-appearances.md)
49-
48+
[Step 2: Extend appearances](step-2-extend-appearances.md)

‎docs/how-to/how-to-add-appearance.md

Lines changed: 227 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,233 @@
11
# How to add an appearance
22

3-
This topic describes how to add a new appearance to a content type so that you can give end-users the custom features they require when creating content.
3+
Appearances provide different layout and styling options for a content type. For example, the Banner content type has four appearances. Each appearance shows a different layout for the Banner's text and button.
4+
5+
This topic shows how to add appearances to Page Builder's native content types. An overview of the steps and the files you need to add are illustrated here:
46

57
![How to add an appearance](../images/how-to-add-appearance.svg)
68

7-
## Step 1: Add appearance to config file
9+
_Steps for adding appearances_
10+
11+
These steps also apply to adding appearances to your custom content types and third-party content types.
12+
13+
## Step 1: Add virtual type for VisualSelect class
14+
15+
First, we need a way select an appearance within the Admin UI. In Page Builder, we use the `VisualSelect` class. This class provides the UI for selecting different appearances. For example, the `VisualSelect` class for the Banner provides four appearances to choose from:
16+
17+
![Banner visual selector](../images/banner-visual-selector.png)
18+
19+
_Visual selector for Banner_
20+
21+
To add a new appearance option for one of Page Builder's native content types, like the Banner, create a new `di.xml` file in your module, as shown here:
22+
23+
![Add VisualSelect class](../images/add-visualselect-class.png)
24+
25+
_File and location for the VisualSelect class_
26+
27+
Within the `di.xml` file, add a virtual type using the`VisualSelect` class with the Banner's virtual type name (`<virtualType name="AppearanceSourceBanner"`), as shown here:
28+
29+
```xml
30+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
31+
<virtualType name="AppearanceSourceBanner" type="Magento\PageBuilder\Model\Source\VisualSelect">
32+
<arguments>
33+
<argument name="optionsData" xsi:type="array">
34+
<item name="simple-poster" xsi:type="array">
35+
<item name="value" xsi:type="string">simple-poster</item>
36+
<item name="title" xsi:type="string" translate="true">Simple Poster</item>
37+
<item name="icon" xsi:type="string">Example_PageBuilderBannerAppearance/css/images/content-type/banner/appearance/simple-poster.svg</item>
38+
</item>
39+
</argument>
40+
</arguments>
41+
</virtualType>
42+
</config>
43+
```
44+
_VisualSelect class for new Banner appearance_
45+
46+
Using the same class name as the Banner ensures that Magento's XML merging will add your new visual appearance option to the existing Banner appearance options.
47+
48+
The following table describes the configuration arguments for each appearance option.
49+
50+
| Arguments | Description |
51+
| --------------- | ------------------------------------------------------------ |
52+
| `optionsData` | Grouping array for all the appearance options of a content type. |
53+
| `item array` | Grouping array of properties that define an appearance option. We recommend you match the `name` of the item array to the option's `value` string. In our example, the `item` array's name is `simple-poster`, which matches the option's value string `simple-poster`. |
54+
| `value` | The `value` string should match the appearance name defined in the content type's configuration file. Page Builder uses this value to link the option to the appearance.|
55+
| `title` | Display name for the appearance option. Banner example: Poster. |
56+
| `icon` | Path to the `.svg` icon for the appearance: `view/adminthtml/web/css/images/content-type/[content-type-name]/appearance/*.svg`. See [Creating an icon for your appearance](#create-an-appearance-icon) |
57+
| `noticeMessage` | (Not shown in example.) The `noticeMessage` displays a message below the appearance options when the appearance is selected. For example, two of the Row appearances (`full-width` and `full-bleed`) define `noticeMessage` strings that display when selected. |
58+
{:style="table-layout:auto"}
59+
60+
To add more appearance options, simply create more `item` arrays with names that match the `value`, as shown here:
61+
62+
```xml
63+
<item name="tall" xsi:type="array">
64+
<item name="value" xsi:type="string">tall</item>
65+
<item name="title" xsi:type="string" translate="true">Tall</item>
66+
<item name="icon" xsi:type="string">Example_PageBuilderExtensionBanner/css/images/content-type/banner/appearance/tall.svg</item>
67+
</item>
68+
<item name="short" xsi:type="array">
69+
<item name="value" xsi:type="string">short</item>
70+
<item name="title" xsi:type="string" translate="true">Short</item>
71+
<item name="icon" xsi:type="string">Example_PageBuilderBannerExtensionBanner/css/images/content-type/banner/appearance/short.svg</item>
72+
</item>
73+
```
74+
_Example of additional appearance options_
75+
76+
### Create an appearance icon
77+
78+
Appearance icons are `.svg` files that graphically depict the layout of an appearance. Add all the appearance icons for your content type within the following directory: `css/images/content-type/[content-type-name]/appearance/`.
79+
80+
![Add appearance icons](../images/appearance-icon-location.png)
81+
82+
_Add appearance icons for Banner content type_
83+
84+
You can use any design tool to create your SVG. But if you want to match your appearance icons to Page Builder's icons _perfectly_, use the SVG structure and dimensions shown here:
85+
86+
```xml
87+
<svg xmlns="http://www.w3.org/2000/svg" width="218" height="110" viewBox="0 0 218 110">
88+
<g fill="none" fill-rule="evenodd">
89+
<rect width="149" height="69" x="35" y="21" fill="#524D49"/>
90+
<!--- Optional shapes displayed on top of base rect -->
91+
<rect width="45" height="16" x="87" y="60" fill="#FFF"/>
92+
<rect width="72" height="4" x="73" y="34" fill="#FFF"/>
93+
<rect width="60" height="4" x="79" y="43" fill="#FFF"/>
94+
</g>
95+
</svg>
96+
```
97+
_SVG appearance template_
98+
99+
These specific dimensions ensure that your icon fits seamlessly with the existing appearance icons:
100+
101+
| Property | Value |
102+
| ------------------------------ | ----------- |
103+
| `svg width` | 218 |
104+
| `svg height` | 110 |
105+
| `svg viewbox` | 0 0 218 110 |
106+
| `g fill` | none |
107+
| base `rect width` | 149 |
108+
| base `rect height` | 69 |
109+
| base `rect x` | 35 |
110+
| base `rect y` | 21 |
111+
| base `rect fill` | #524D49 |
112+
| other shape `fill` properties | #FFF |
113+
{:style="table-layout:fixed"}
114+
115+
## Step 2: Add appearance configurations
116+
117+
Appearance configurations connect the data entered in a content type's form to its HTML templates. For example, the Heading content type has an `<html>` config element (`<html name="heading_text" />`) that maps the text entered into the content type's `heading_text` form field (`<field name="heading_text" formElement="input">`) to the Heading's Knockout template binding (`html="data.main.html"`), as illustrated here:
118+
119+
![Appearance configurations](../images/appearance-configurations.png)
120+
121+
_Appearance configurations explained_
122+
123+
The same concept applies to `styles`, `attributes`, and `css` elements. These elements ensure that the form settings (both content and styles) get applied to the templates as expected.
124+
125+
To add a new Banner appearance configuration, create a content type config file named `banner.xml`, as shown here:
126+
127+
![Appearance configuration config file](../images/appearance-config-file.png)
128+
129+
_Add additional appearances to Banner content type_
130+
131+
{: .bs-callout .bs-callout-info }
132+
This procedure applies to any native content type you want to extend. In other words, you can use the file name (`heading.xml`) and type name (`<type name="heading">`) of any native Page Builder content type to extend it based on Magento's XML merging behavior.
133+
134+
An example `banner.xml` config file for a new `simple-poster` appearance is shown here:
135+
136+
```xml
137+
<?xml version="1.0"?>
138+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
139+
<type name="banner">
140+
<children default_policy="deny"/>
141+
<appearances>
142+
<appearance name="simple-poster"
143+
preview_template="Example_PageBuilderBannerAppearance/content-type/banner/simple-poster/preview"
144+
master_template="Example_PageBuilderBannerAppearance/content-type/banner/simple-poster/master"
145+
reader="Magento_PageBuilder/js/master-format/read/configurable">
146+
<elements>
147+
<element name="main">
148+
<style name="display" source="display" converter="Magento_PageBuilder/js/converter/style/display" preview_converter="Magento_PageBuilder/js/converter/style/preview/display"/>
149+
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
150+
<attribute name="name" source="data-content-type"/>
151+
<attribute name="appearance" source="data-appearance"/>
152+
<attribute name="show_button" source="data-show-button"/>
153+
<attribute name="show_overlay" source="data-show-overlay"/>
154+
<css name="css_classes"/>
155+
</element>
156+
. . .
157+
</appearance>
158+
</appearances>
159+
</type>
160+
</config>
161+
```
162+
_Additional simple-poster appearance for the Banner content type_
163+
164+
## Step 3: Add appearance forms
165+
166+
Appearances for a content type can share the same form or use different forms. For example, the Products content type uses two different forms, one for each appearance. The Grid appearance uses the `pagebuilder_products_form.xml` to provide options for displaying products in a grid. While the Carousel appearance uses the `pagebuilder_products_carousel_form.xml` to provide extra options for displaying products in a carousel.
167+
168+
When you select an appearance with its own form, Page Builder replaces the content type's form (defined in the `<type>` element) with the appearance's form. But when you select an appearance that does not have a form defined, the appearance switches back to using the content type's form.
169+
170+
```xml
171+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"...>
172+
<type name="products"
173+
form="pagebuilder_products_form"
174+
```
175+
_Content type form used by default for all appearances_
176+
177+
To add a form for an appearance, add a `<form>` element as a child of the `<appearance>` element in your content type's config file. As mentioned, the Products content type does this for its Carousel appearance, shown here:
178+
179+
```xml
180+
<appearance name="carousel"
181+
preview_template="Magento_PageBuilder/content-type/products/grid/preview"
182+
master_template="Magento_PageBuilder/content-type/products/grid/master"
183+
reader="Magento_PageBuilder/js/master-format/read/configurable">
184+
<form>pagebuilder_products_carousel_form</form>
185+
<elements>
186+
. . .
187+
```
188+
_Adding a form to an appearance_
189+
190+
## Step 4: Add appearance templates
191+
192+
Appearances use different HTML templates to create different layouts and apply different styles to those layouts. For example, the Banner content type uses four sets of `preview.html` and `master.html` templates to create the visual differences for each content type:
193+
194+
![Appearance configuration config file](../images/appearance-templates-banner.png)
195+
196+
_Banner appearance templates_
197+
198+
Notice how Page Builder organizes the Banner templates by appearance name. We recommend the same practice when adding templates for your appearances.
199+
200+
To create appearance templates for additional Banner appearances, such as the `simple-poster` appearance described in steps 1 and 2, add a new appearance folder for your module's templates, as shown here:
201+
202+
![Appearance templates](../images/appearance-templates-additional.png)
203+
204+
_Adding additional appearance templates_
205+
206+
## Step 5: Add appearance styles
207+
208+
Appearances use different CSS/LESS files to create different visual styles for a content type. For example, the Banner content type uses a different `.less` file for each appearance, as shown here:
209+
210+
![Appearance stylesheets](../images/appearance-css-banner.png)
211+
212+
_Banner stylesheets_
213+
214+
To create a LESS stylesheet for an additional Banner appearances, such as the `simple-poster`, you must add a new appearance folder for your module's templates, as shown here:
215+
216+
![Additional appearance stylesheets](../images/appearance-css-additional.png)
217+
218+
_Adding additional stylesheets_
219+
220+
The `_module.less` file is an import file that ensures the additional stylesheet gets added to the existing Banner styles. The `_module.xml` file for our `simple-poster.less` file looks like this:
221+
222+
```scss
223+
@import "_simple-poster";
224+
```
225+
_Use _module.less for import statements_
226+
227+
## Conclusion
228+
229+
Using appearances to extend Page Builder's native content types represents one of Page Builder's best practices for creating a variety of new content building blocks based on existing content types. We hope this topic has helped adequately describe this best practice.
230+
231+
## Example Module
8232

9-
In progress...
233+
An example module for this topic is available for download in the [pagebuilder-examples repository](https://github.com/magento-devdocs/pagebuilder-examples/tree/master/Example/PageBuilderBannerAppearance).

‎docs/images/add-visualselect-class.png

18.8 KB
Loading

‎docs/images/appearance-config-file.png

22.2 KB
Loading

‎docs/images/appearance-configurations.png

318 KB
Loading

0 commit comments

Comments
 (0)