Skip to content

Commit 01bf385

Browse files
bdenhambdenham
committed
MAGEDOC-3550: How to add an appearance
Fixed tutorial, highlighted install instructions, and update release note
1 parent 286c191 commit 01bf385

File tree

7 files changed

+115
-141
lines changed

7 files changed

+115
-141
lines changed

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

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ Because we are extending the Banner, we start by creating a new configuration fi
1919

2020
![Extension config file structure](../images/appearance-extension-config-file.png){:width="511px" height="auto"}
2121

22-
## Add the appearances you want to extend
22+
## Add properties to appearances
2323

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:
24+
Currently, you cannot extend just one appearance of a content type. You have to extend them all. In our example, we are extending the Banner content type, which has four appearances. Our example shows how you add a max-height property to all four of the Banner appearances.
2525

2626
```xml
2727
<?xml version="1.0"?>
@@ -34,15 +34,27 @@ We are only extending two Banner appearances, which means we only need to define
3434
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
3535
</element>
3636
</elements>
37-
<form>pagebuilder_banner_collage_left_form</form>
3837
</appearance>
3938
<appearance name="collage-right">
4039
<elements>
4140
<element name="wrapper">
4241
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
4342
</element>
4443
</elements>
45-
<form>pagebuilder_banner_collage_right_form</form>
44+
</appearance>
45+
<appearance name="poster">
46+
<elements>
47+
<element name="wrapper">
48+
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
49+
</element>
50+
</elements>
51+
</appearance>
52+
<appearance name="collage-centered">
53+
<elements>
54+
<element name="wrapper">
55+
<style name="max_height" source="max_height" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
56+
</element>
57+
</elements>
4658
</appearance>
4759
</appearances>
4860
</type>
@@ -59,7 +71,6 @@ The following table describes the elements in our extension configuration.
5971
| `elements` | The grouping element that specifies one or more `element` nodes. |
6072
| `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`. |
6173
| `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. |
6374

6475
{:style="table-layout:auto"}
6576

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

Lines changed: 10 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,42 +4,41 @@ In this step, you will extend the Banner form (`pagebuilder_banner_form.xml`) by
44

55
## Create the appearance forms
66

7-
Page Builder forms are UI component forms. This means they follow the same conventions as any other UI component form. If you are not already familiar with UI component forms, you can learn more about them from the [UI Components Guide](https://devdocs.magento.com/guides/v2.3/ui_comp_guide/concepts/ui_comp_xmldeclaration_concept.html). For this tutorial, we provide you with the basic markup for setting up these forms.
7+
Page Builder forms are UI component forms. This means they follow the same conventions as any other UI component form. If you are not already familiar with UI component forms, you can learn more about them from the [UI Components Guide](https://devdocs.magento.com/guides/v2.3/ui_comp_guide/concepts/ui_comp_xmldeclaration_concept.html). For this tutorial, we provide you with the basic markup for setting up an empty form.
88

99
Your file structure for the Banner extension forms and corresponding layouts should look like this:
1010

11-
![Extension forms file structure](../images/extension-forms-files.png){:width="433px" height="auto"}
11+
![Extension forms file structure](../images/extension-forms-files.png){:width="544px" height="auto"}
1212

13-
When setting up your extension forms, ensure you are inheriting from the form of the content type you want to extend. In our case, we are extending from the Banner's form: `page-banner-form` . The basic XML configuration for both forms is as follows.
13+
When setting up your extension form, ensure you have named your form with the same name as that of the content type you want to extend. In our case, we are extending from the Banner's form: `page-banner-form.xml` . The basic XML configuration for both forms is as follows.
1414

1515
### `collage-left` form
1616

1717
```xml
1818
<?xml version="1.0" encoding="UTF-8"?>
1919
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20-
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd"
21-
extends="pagebuilder_banner_form">
20+
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd">
2221
<argument name="data" xsi:type="array">
2322
<item name="js_config" xsi:type="array">
2423
<item name="provider" xsi:type="string">
25-
pagebuilder_banner_collage_left_form.pagebuilder_banner_collage_left_form_data_source
24+
pagebuilder_banner_form.pagebuilder_banner_form_data_source
2625
</item>
2726
</item>
2827
<item name="label" xsi:type="string" translate="true">Banner</item>
2928
</argument>
3029
<settings>
3130
<deps>
32-
<dep>pagebuilder_banner_collage_left_form.pagebuilder_banner_collage_left_form_data_source</dep>
31+
<dep>pagebuilder_banner_form.pagebuilder_banner_form_data_source</dep>
3332
</deps>
34-
<namespace>pagebuilder_banner_collage_left_form</namespace>
33+
<namespace>pagebuilder_banner_form</namespace>
3534
</settings>
36-
<dataSource name="pagebuilder_banner_collage_left_form_data_source">
35+
<dataSource name="pagebuilder_banner_form_data_source">
3736
<argument name="data" xsi:type="array">
3837
<item name="js_config" xsi:type="array">
3938
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
4039
</item>
4140
</argument>
42-
<dataProvider name="pagebuilder_banner_collage_left_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
41+
<dataProvider name="pagebuilder_banner_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
4342
<settings>
4443
<requestFieldName/>
4544
<primaryFieldName/>
@@ -52,52 +51,11 @@ When setting up your extension forms, ensure you are inheriting from the form of
5251
</form>
5352
```
5453

55-
### `collage-right` form
56-
57-
```xml
58-
<?xml version="1.0" encoding="UTF-8"?>
59-
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
60-
xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd"
61-
extends="pagebuilder_banner_form">
62-
<argument name="data" xsi:type="array">
63-
<item name="js_config" xsi:type="array">
64-
<item name="provider" xsi:type="string">
65-
pagebuilder_banner_collage_right_form.pagebuilder_banner_collage_right_form_data_source
66-
</item>
67-
</item>
68-
<item name="label" xsi:type="string" translate="true">Banner</item>
69-
</argument>
70-
<settings>
71-
<deps>
72-
<dep>pagebuilder_banner_collage_right_form.pagebuilder_banner_collage_right_form_data_source</dep>
73-
</deps>
74-
<namespace>pagebuilder_banner_collage_right_form</namespace>
75-
</settings>
76-
<dataSource name="pagebuilder_banner_collage_right_form_data_source">
77-
<argument name="data" xsi:type="array">
78-
<item name="js_config" xsi:type="array">
79-
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
80-
</item>
81-
</argument>
82-
<dataProvider name="pagebuilder_banner_collage_right_form_data_source"
83-
class="Magento\PageBuilder\Model\ContentType\DataProvider">
84-
<settings>
85-
<requestFieldName/>
86-
<primaryFieldName/>
87-
</settings>
88-
</dataProvider>
89-
</dataSource>
90-
91-
<!--Add Fieldsets and fields-->
92-
93-
</form>
94-
```
95-
9654
## Add fieldsets and fields
9755

9856
Before you add a field to the form of an existing content type, you need to know where to add it. In other words, you need to decide which fieldset to put your field in. We want to put our new max-height field with the Banner's existing min-height field, which is the `appearance_fieldset`.
9957

100-
The markup for adding the field to the fieldset looks exactly like this for both forms:
58+
The markup for adding the field to the fieldset looks like this:
10159

10260
```xml
10361
<fieldset name="appearance_fieldset"

‎docs/getting-started/install-pagebuilder.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Install Page Builder
22

3-
Page Builder is automatically installed with Magento Commerce 2.3.1. There is nothing else you need to do. However, If you want to contribute to the Page Builder code or documentation, you can use the GitHub installation as follows.
3+
{: .bs-callout .bs-callout-info }
4+
These installation instructions are only for contributors to the Page Builder code or documentation. For everyone else, **Page Builder is automatically installed with Magento Commerce 2.3.1. There is nothing else you need to do.**
45

56
## GitHub installation for Contributors
67

‎docs/images/extension-file-structure-complete.png

-93.3 KB
Loading

‎docs/images/extension-forms-files.png

-22.5 KB
Loading

‎docs/release-notes-beta.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Release Notes
2+
3+
## Beta 8 - February 19, 2019
4+
5+
- Resolved: Analytics module sequence issue.
6+
7+
## Beta 7 - February 14, 2019
8+
9+
Beta 7 has breaking changes due to renaming of several critical variables and parameters in Page Builder's code and configuration. Please refer to the [breaking changes document](https://devdocs.magedevteam.com/ds_pagebuilder/page-builder/breaking-changes.html) for details on how to update your custom content types.
10+
11+
- Resolved: Content type markup within Text content type causes whole stage to become HTML <!--MC-13917-->
12+
- Resolved: Hard-coded margins on individual Button <!--MC-13925-->
13+
- Resolved: Various TypeScript errors <!--MC-10833-->
14+
- Resolved: Column rearranging drop zone indicators are too small and sometimes hard to activate <!--MC-4262-->
15+
- Resolved: Collect Page Builder content type data for Page Builder analytics <!--MC-1426-->
16+
- Resolved: Improve naming of the critical variables/parameters in the code and configuration <!--MC-5810-->
17+
- Resolved: Text height inconsistency on stage and storefront <!--MC-4254-->
18+
- Resolved: Option menus, Heading inline editor, and tinyMCE inline editor are cut off on full screen view <!--MC-5383-->
19+
- Resolved: Anchor tags for TinyMCE links are not added to the storefront for Banners and Slides (Added notification for when link attribute is entered) <!--MC-5386-->
20+
- Resolved: `WidgetInitializerConfig` only supports <div /> elements <!--MC-13770-->
21+
- Resolved: Slide dots are hard to see against certain backgrounds on storefront <!--MC-5701-->
22+
- Resolved: Missing validation message when uploading big image <!--MC-5184-->
23+
- Resolved: Security issues <!--MC-10871, MC-13922-->
24+
25+
## Beta 6 - February 4, 2019
26+
27+
- Resolved: Background attachments of "fixed" do not work in storefront on Android or iPhone mobile devices<!-- MC-5419 -->
28+
- Resolved: Minimum height issues with Columns <!-- MC-5405 -->
29+
- Resolved: Parallax fixed settings should work in admin and storefront <!-- MC-11066 -->
30+
- Resolved: Move data migration into its own module <!-- MC-5824 -->
31+
- Resolved: Changing row appearance with two rows on stage breaks admin <!-- MC-11821 -->
32+
- Resolved: Banner and Slider TinyMCE menus display inconsistently in admin <!-- MC-13691 -->
33+
- Improved: Test coverage for CMS Blocks and Catalog Product <!-- MC-3328, MC3329 -->
34+
35+
## Beta 5 - January 28, 2019
36+
37+
- Resolved: Prefixed field names with section name to avoid field name collision <!-- MC-5232 -->
38+
- Resolved: MFTF: Rewrite Selectors/ActionGroups to allow using Page Builder in non-CMS page areas <!-- MC-4231 -->
39+
- Resolved: Right/Left Margin Not Working For Content Types <!-- MC-5025 -->
40+
- Resolved: Alignment doesn't work for Slide, Banners, & Text Placeholders & for Slide Content & Banner Poster Content <!-- MMC-4290 -->
41+
- Resolved: Implement better developer error reporting <!-- MC-5691 -->
42+
- Resolved: Banner placeholder disappears when user switching between different appearances <!-- MC-5727 -->
43+
44+
## Beta 4 - January 14, 2019
45+
46+
- Resolved: Collage Center/Left/Right does not work correctly in a container smaller than 100% width <!-- MC-5372 -->
47+
- Resolved: Contained row appearance renders too small when in smaller container or in Block/Dynamic Block <!-- MC-5432 -->
48+
- Resolved: XSS Vulnerability in Page Builder <!-- MC-5835 -->
49+
50+
## Beta 3 - December 19, 2018
51+
52+
- Improved: Handling of invalid Google Maps API keys <!-- MC-5723 -->
53+
- Removed: Legacy overlay transparency field from banner & slider in favor of using the color picker <!-- MC-3895 -->
54+
- Resolved: Box sizing issues on storefront and Admin <!-- MC-5079 -->
55+
- Resolved: Issue with initiation of tabs breaking in certain scenarios <!-- MC-5363 -->
56+
- Resolved: Performance issues with "Edit with Page Builder" button in category and product areas <!-- MC-5403 -->
57+
- Resolved: Numerous issues within staging slide out <!-- MC-5423 -->
58+
59+
## Beta 2 - December 10, 2018
60+
61+
- Resolved: Image inside Text Content Type is scaled on stage <!-- MC-3509 -->
62+
- Resolved: Padding is not respected on Text <!-- MC-3713 -->
63+
- Resolved: Saving Slide Button Type As Secondary Or Link Will Still Show As Primary On Edit Form <!-- MC-3818 -->
64+
- Resolved: Columns Widths Are Not Consistent Between Stage & Storefront <!-- MC-3992 -->
65+
- Resolved: Review Information Covered By Add To Cart Button On Products On Stage <!-- MC-4130 -->
66+
- Resolved: Hard Coded Padding On Button Groups & On Text <!-- MC-4278 -->
67+
- Resolved: Remove Reset Button From Slide Outs For All Content Types <!-- MC-5790 -->
68+
- Resolved: Remove is_hideable option from content type configuration <!-- MC-4959 -->
69+
- Resolved: IE11 - Cannot Use Slide Item Option Menu <!-- MC-5443 -->
70+
71+
## Beta 1 - November 27, 2018
72+
73+
- Initial beta release
74+
75+
## Known Issues
76+
77+
* Degraded admin experience when using IE 11.
78+
* Product does not display in admin when it is assigned to a specific website. <!-- MC-5373 -->
79+
* Issues with padding, margins, and box-sizing on numerous content types. <!-- MC-11021 -->
80+
* Floating option menus and other controls can be displayed off screen when content types are rendered near the edge of the screen. <!-- MC-5383 -->
81+
* Degraded Parallax performance on storefront and in admin within some browsers. <!-- MC-5480 -->
82+
* Using Page Builder within a slide out form has a degraded experience.
83+
* Left-side panel will not scroll with the user.
84+
* Dragging and dropping can become broken due to another instance of Page Builder being loaded.
85+

0 commit comments

Comments
 (0)