Skip to content

Commit 14b48a4

Browse files
bdenhambdenham
committed
MAGEDOC-3550: How to add an appearance
WIP tutorial for overview and steps 1 and 2.
1 parent 4800d1b commit 14b48a4

File tree

4 files changed

+66
-3
lines changed

4 files changed

+66
-3
lines changed

‎docs/extend-existing-content-type/overview.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Many of Page Builder's content types have only one `appearance` element. These i
1212

1313
Page Builder defines these appearances in the Banner's configuration file (`Magento/PageBuilder/view/adminhtml/pagebuilder/content_type/banner.xml`), as shown here:
1414

15-
```
15+
```xml
1616
<appearances>
1717
<appearance name="collage-left"...>
1818
<appearance name="collage-centered"...>

‎docs/extend-existing-content-type/step-2-extend-appearances.md

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,69 @@
11
# Step 2: Extend appearances
22

3-
In progress. To be officially published on 3/26
3+
In this step, you will extend two of the four Banner appearances (`collage-left` and `collage-right`) by adding a new `max_height` property to each. This property stops the Banner from growing beyond a certain height as end-users enter text.
44

5+
## Create a content configuration file
56

7+
Appearances are defined in a content type's configuration file. As previously mentioned, the Banner's appearances are defined within the `banner.xml` file, as shown collapsed here:
8+
9+
```xml
10+
<appearances>
11+
<appearance name="collage-left"...>
12+
<appearance name="collage-centered"...>
13+
<appearance name="collage-right"...>
14+
<appearance name="poster" default="true" ...>
15+
</appearances>
16+
```
17+
18+
Because we are extending the Banner, we start by creating a new configuration file called `banner.xml`. Giving our extension configuration file the same name as the Banner's config file ensures that Magento will merge our appearance extensions with the Banner's existing configuration. Your file structure for the `banner.xml` extension should look like this:
19+
20+
![Extension config file structure](../images/appearance-extension-config-file.png){:width="511px" height="auto"}
21+
22+
## Add the appearances you want to extend
23+
24+
We are only extending two Banner appearances, which means we only need to define two `appearance` elements in the config file, as shown here:
25+
26+
```xml
27+
<?xml version="1.0"?>
28+
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_types.xsd">
29+
<type name="banner">
30+
<appearances>
31+
<appearance name="collage-left">
32+
<elements>
33+
<element name="wrapper">
34+
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
35+
</element>
36+
</elements>
37+
<form>pagebuilder_banner_collage_left_form</form>
38+
</appearance>
39+
<appearance name="collage-right">
40+
<elements>
41+
<element name="wrapper">
42+
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
43+
</element>
44+
</elements>
45+
<form>pagebuilder_banner_collage_right_form</form>
46+
</appearance>
47+
</appearances>
48+
</type>
49+
</config>
50+
```
51+
52+
The following table describes the elements in our extension configuration.
53+
54+
| Element | Description |
55+
| ------------- | ------------------------------------------------------------ |
56+
| `type` | The type `name` defines the name of the content type. Make sure you name this configuration `banner` so that Magento will merge this configuration with the Banner's configuration. |
57+
| `appearances` | The grouping element that specifies one or more `appearance` elements. |
58+
| `appearance` | The appearance `name` that Magento uses for XML merging. Again, make sure you use the same appearance names as the Banner so that Magento can merge your appearance extensions with the Banner appearances you want to modify. |
59+
| `elements` | The grouping element that specifies one or more `element` nodes. |
60+
| `element` | The element maps styles and other appearance extensions from the form editor to the HTML templates that render content on the Admin stage and storefront. We want our appearance styles to map to the `wrapper` element of the Banner's templates, so the element for each appearance extension is named `wrapper`. |
61+
| `style` | The `style` element configures the bindings from the form field to the template elements. In this case, our style is applied to the `wrapper` element of the template. The style `name` represents the CSS `max-height` style. The `source` is the name of the form field you want the style bound to. Hint: The field name added in step 3 is `max-height`. |
62+
| `form` | Each appearance can use a different form to merge with or overwrite the Banner's form. You will create the form in step 3. |
63+
64+
{:style="table-layout:auto"}
65+
66+
## Next
67+
68+
[Step 3: Extend forms](step-3-extend-forms.md)
669

‎docs/extend-existing-content-type/step-3-extend-forms.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Step 3: Extend forms
22

3-
In progress. To be officially published on 3/26
3+
In this step, you will create two forms, one for each of the Banner appearances (`collage-left` and `collage-right`) by adding a new `max_height` property to each. This property stops the Banner from growing beyond a certain height as end-users enter text.
44

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

57.1 KB
Loading

0 commit comments

Comments
 (0)