Skip to content

Commit 8a576c2

Browse files
bdenhambdenham
committed
PB-73: Create Appearances example and documentation
Draft for review
1 parent dfe36e7 commit 8a576c2

15 files changed

+559
-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: 204 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,210 @@
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 existing 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)
8+
_Steps for adding appearances_
9+
10+
Even though this topic describes how to add appearances to Page Builder's native content types, the steps can be applied to adding more appearances to your custom content types as well.
11+
12+
## Step 1: Add VisualSelect class
13+
14+
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:
15+
16+
![Banner visual selector](../images/banner-visual-selector.png)
17+
_Visual selector for Banner_
18+
19+
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:
20+
21+
![Add VisualSelect class](../images/add-visualselect-class.png)
22+
_File and location for the VisualSelect class_
23+
24+
Within the `di.xml` file, add a `VisualSelect` class using the Banner's `VisualSelect` class name (`<virtualType name="AppearanceSourceBanner"`), as shown here:
25+
26+
```xml
27+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
28+
<virtualType name="AppearanceSourceBanner" type="Magento\PageBuilder\Model\Source\VisualSelect">
29+
<arguments>
30+
<argument name="optionsSize" xsi:type="string">large</argument>
31+
<argument name="optionsData" xsi:type="array">
32+
<item name="4" xsi:type="array">
33+
<item name="value" xsi:type="string">simple-poster</item>
34+
<item name="title" xsi:type="string" translate="true">Simple Poster</item>
35+
<item name="icon" xsi:type="string">Example_PageBuilderBannerAppearance/css/images/content-type/banner/appearance/simple-poster.svg</item>
36+
</item>
37+
</argument>
38+
</arguments>
39+
</virtualType>
40+
</config>
41+
```
42+
_VisualSelect class for new Banner appearance_
43+
44+
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.
45+
46+
The following table describes the configuration arguments for each appearance option.
47+
48+
| Arguments | Description |
49+
| --------------- | ------------------------------------------------------------ |
50+
| `optionsSize` | The size of the icons that display each option. Use `large` for appearance options. |
51+
| `optionsData` | Grouping array for all the appearance options of a content type. |
52+
| `item array` | Grouping array of properties that define an appearance option. The `name="4"` signifies the index order for displaying the option. The Banner's existing options stop with an index of 3 (`name="3"`), ensuring that our new appearance option is positioned after the last Banner option. |
53+
| `value` | Assigns the unique key used in the component dataSource. |
54+
| `title` | Display name for the appearance option. Banner example: Poster. |
55+
| `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 |
56+
| `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. |
57+
58+
To add more appearance options, simply create more ` item` arrays, as shown here:
59+
60+
```xml
61+
<item name="5" xsi:type="array">
62+
<item name="value" xsi:type="string">tall</item>
63+
<item name="title" xsi:type="string" translate="true">Tall</item>
64+
<item name="icon" xsi:type="string">Example_PageBuilderExtensionBanner/css/images/content-type/banner/appearance/tall.svg</item>
65+
</item>
66+
<item name="6" xsi:type="array">
67+
<item name="value" xsi:type="string">short</item>
68+
<item name="title" xsi:type="string" translate="true">Short</item>
69+
<item name="icon" xsi:type="string">Example_PageBuilderBannerExtensionBanner/css/images/content-type/banner/appearance/short.svg</item>
70+
</item>
71+
```
72+
_Example of additional appearance options_
73+
74+
### Creating an appearance icon
75+
76+
Appearance icons are `.svg` files that graphically depict the layout of an appearance. Use the following SVG template as a starting place for creating your own appearance icon:
77+
78+
```xml
79+
<svg xmlns="http://www.w3.org/2000/svg" width="218" height="110" viewBox="0 0 218 110">
80+
<g fill="none" fill-rule="evenodd">
81+
<rect width="149" height="69" x="35" y="21" fill="#524D49"/>
82+
<rect width="45" height="16" x="87" y="60" fill="#FFF"/>
83+
<rect width="72" height="4" x="73" y="34" fill="#FFF"/>
84+
<rect width="60" height="4" x="79" y="43" fill="#FFF"/>
85+
</g>
86+
</svg>
87+
```
88+
_SVG appearance template_
89+
90+
You can use whatever tool you want to create your SVG. Just make sure you follow these specific dimensions to ensure your icon fits in with the existing appearance icons:
91+
92+
| Property | Value |
93+
| ---------------------------- | ----------- |
94+
| `svg width` | 218 |
95+
| `svg height` | 110 |
96+
| `svg viewbox` | 0 0 218 110 |
97+
| `g fill` | none |
98+
| background `rect width` | 149 |
99+
| background `rect height` | 69 |
100+
| background `rect x` | 35 |
101+
| background `rect y` | 21 |
102+
| background `rect fill` | #524D49 |
103+
| other `rect fill` properties | #FFF |
104+
105+
## Step 2: Add appearance configurations
106+
107+
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:
108+
109+
![Appearance configurations](../images/appearance-configurations.png)
110+
_Appearance configurations explained_
111+
112+
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.
113+
114+
To add a new Banner appearance configuration, create a content type config file named `banner.xml`, as shown here:
115+
116+
![Appearance configuration config file](../images/appearance-config-file.png)
117+
_Add additional appearances to Banner content type_
118+
119+
{: .bs-callout .bs-callout-info }
120+
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.
121+
122+
An example `banner.xml` config file for a new `simple-poster` appearance is shown here:
123+
124+
```xml
125+
<?xml version="1.0"?>
126+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
127+
<type name="banner">
128+
<children default_policy="deny"/>
129+
<appearances>
130+
<appearance name="simple-poster"
131+
preview_template="Example_PageBuilderBannerAppearance/content-type/banner/simple-poster/preview"
132+
master_template="Example_PageBuilderBannerAppearance/content-type/banner/simple-poster/master"
133+
reader="Magento_PageBuilder/js/master-format/read/configurable">
134+
<elements>
135+
<element name="main">
136+
<style name="display" source="display" converter="Magento_PageBuilder/js/converter/style/display" preview_converter="Magento_PageBuilder/js/converter/style/preview/display"/>
137+
<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
138+
<attribute name="name" source="data-content-type"/>
139+
<attribute name="appearance" source="data-appearance"/>
140+
<attribute name="show_button" source="data-show-button"/>
141+
<attribute name="show_overlay" source="data-show-overlay"/>
142+
<css name="css_classes"/>
143+
</element>
144+
. . .
145+
</appearance>
146+
</appearances>
147+
</type>
148+
</config>
149+
```
150+
_Additional simple-poster appearance for the Banner content type_
151+
152+
## Step 3: Add appearance forms
153+
154+
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.
155+
156+
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:
157+
158+
```xml
159+
<appearance name="carousel"
160+
preview_template="Magento_PageBuilder/content-type/products/grid/preview"
161+
master_template="Magento_PageBuilder/content-type/products/grid/master"
162+
reader="Magento_PageBuilder/js/master-format/read/configurable">
163+
<form>pagebuilder_products_carousel_form</form>
164+
<elements>
165+
. . .
166+
```
167+
_Adding a form to an appearance_
168+
169+
## Step 4: Add appearance templates
170+
171+
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:
172+
173+
![Appearance configuration config file](../images/appearance-templates-banner.png)
174+
_Banner appearance templates_
175+
176+
Each template set is located within a folder named after the appearance for which they are used. The folder names must match the appearance names assigned in the content type's config file.
177+
178+
To create appearance templates for additional Banner appearances, such as the `simple-poster` appearance described in steps 1 and 2, you must add a new appearance folder for your module's templates, as shown here:
179+
180+
![Appearance templates](../images/appearance-templates-additional.png)
181+
_Adding additional appearance templates_
182+
183+
## Step 5: Add appearance styles
184+
185+
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:
186+
187+
![Appearance stylesheets](../images/appearance-css-banner.png)
188+
_Banner stylesheets_
189+
190+
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:
191+
192+
![Additional appearance stylesheets](../images/appearance-css-additional.png)
193+
_Adding additional stylesheets_
194+
195+
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:
196+
197+
```scss
198+
@import "_simple-poster";
199+
```
200+
_Use _module.less for import statements_
201+
202+
## Conclusion
203+
204+
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.
205+
206+
## Example Module
6207

7-
## Step 1: Add appearance to config file
208+
An example module for this topic is available for download in the `pagebuilder-examples` repository here:
8209

9-
In progress...
210+
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)