Skip to content

Commit d70ef70

Browse files
author
Igor Melnikov
committed
Merge branch 'MAGETWO-91200-update-documentation-eap' of github.com:magento-obsessive-owls/bluefoot into MAGETWO-91200-update-documentation-eap
2 parents 9f973fd + 3963f11 commit d70ef70

15 files changed

+1129
-42
lines changed

‎app/code/Magento/PageBuilder/docs/README.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# PageBuilder Module Documentation
2+
3+
PageBuilder is a Content Management System(CMS) module for Magento 2.3 and above.
4+
It replaces the default WYSIWYG Editor in the Admin area with a highly configurable drag-and-drop editing system.
5+
6+
## Navigation
7+
8+
1. **Introduction**
9+
2. [Installation guide]
10+
3. Contribution guide
11+
4. [Developer documentation]
12+
1. [BlueFoot to PageBuilder data migration]
13+
1. [Third-party content type migration]
14+
1. [Iconography]
15+
1. [Module integration]
16+
1. [Additional data capability]
17+
1. [Content type configuration]
18+
1. [How to add a new content type]
19+
5. [Roadmap and known issues]
20+
21+
[Introduction]: README.md
22+
[Installation Guide]: install.md
23+
[Developer documentation]: developer-documentation.md
24+
[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md
25+
[Third-party content type migration]: new-content-type-example.md
26+
[Iconography]: iconography.md
27+
[Module integration]: module-integration.md
28+
[Additional data capability]: additional-data.md
29+
[Content type configuration]: content-type-configuration.md
30+
[How to add a new content type]: how-to-add-new-content-type.md
31+
[Roadmap and Known Issues]: roadmap.md

‎app/code/Magento/PageBuilder/docs/additional-data.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Additional data capability
2+
3+
## Navigation
4+
5+
1. [Introduction]
6+
2. [Installation guide]
7+
3. Contribution guide
8+
4. [Developer documentation]
9+
1. [BlueFoot to PageBuilder data migration]
10+
1. [Third-party content type migration]
11+
1. [Iconography]
12+
1. [Module integration]
13+
1. **Additional data capability**
14+
1. [Content type configuration]
15+
1. [How to add a new content type]
16+
5. [Roadmap and known issues]
17+
18+
[Introduction]: README.md
19+
[Installation guide]: install.md
20+
[Developer documentation]: developer-documentation.md
21+
[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md
22+
[Third-party content type migration]: new-content-type-example.md
23+
[Iconography]: iconography.md
24+
[Module integration]: module-integration.md
25+
[Additional data capability]: additional-data.md
26+
[Content type configuration]: content-type-configuration.md
27+
[How to add a new content type]: how-to-add-new-content-type.md
28+
[Roadmap and known issues]: roadmap.md
29+
30+
## What's in this topic
31+
This topic describes how to extend and configure Page Builder content types to accommodate any preferred setting that is not addressed in the confines of our existing `content_types.xsd` schema definition.
32+
33+
`additional_data` allows you to provide extra configuration, such as `maxFileSize` or `allowedExtensions`, for various content types.
34+
35+
For example, if you want to load data from the backend, you can use objects, `xsi:type="object"`, to implement `Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\ProviderInterface` to process the data and dynamically load information based on the system config.
36+
37+
38+
## Overview
39+
40+
To add customization to a Page Builder content type, you must:
41+
1. [Add additional data to the XML config](#additional-data)
42+
2. [Implement `ProviderInterface` for conversion](#conversion) (Optional, as it is only required if you're using `xsi:type="object"` to obtain dynamic configuration at runtime)
43+
44+
## Add additional data to the XML config {#additional-data}
45+
46+
Use `additional_data` in your `/app/code/Magento/PageBuilder/etc/content_types/<your-content-type>.xml` XML config file to add custom configuration to a content type:
47+
48+
``` xml
49+
<additional_data>
50+
<arguments name="uploaderConfig" xsi:type="array">
51+
<item name="maxFileSize" xsi:type="object">Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\Provider\Uploader\MaxFileSize</item>
52+
<item name="allowedExtensions" xsi:type="string">jpg jpeg gif png</item>
53+
<item name="component" xsi:type="string">Magento_PageBuilder/js/form/element/image-uploader</item>
54+
<item name="componentType" xsi:type="string">imageUploader</item>
55+
<item name="dataScope" xsi:type="string">image</item>
56+
<item name="formElement" xsi:type="string">imageUploader</item>
57+
<item name="uploaderConfig" xsi:type="array">
58+
<item name="url" xsi:type="object">Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\Provider\Uploader\SaveUrl</item>
59+
</item>
60+
<item name="previewTmpl" xsi:type="string">Magento_PageBuilder/form/element/uploader/preview/image</item>
61+
<item name="template" xsi:type="string">Magento_PageBuilder/form/element/stage/preview/uploader/image</item>
62+
<item name="mediaGallery" xsi:type="array">
63+
<item name="openDialogUrl" xsi:type="object">Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\Provider\Uploader\OpenDialogUrl</item>
64+
<item name="openDialogTitle" xsi:type="string" translate="true">Insert Images...</item>
65+
<item name="initialOpenSubpath" xsi:type="string">wysiwyg</item>
66+
<item name="storeId" xsi:type="object">\Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\Provider\StoreId</item>
67+
</item>
68+
<item name="validation" xsi:type="array">
69+
<item name="required-entry" xsi:type="boolean">true</item>
70+
</item>
71+
</arguments>
72+
</additional_data>
73+
```
74+
75+
## Implement `ProviderInterface` for conversion {#conversion}
76+
77+
Array and scalar types, `xsi:type="array"` and `xsi:type="string"` for example (but also boolean, integer, and constant), designated in the XML file are provided as-is to the additional data configuration payload.
78+
79+
Object content types, `xsi:type="object"`, must implement `ProviderInterface` in `/app/code/Magento/PageBuilder/Model/Config/ContentTypes/AdditionalData/ProviderInterface.php` to be converted:
80+
81+
``` php
82+
<?php
83+
/**
84+
* Copyright © Magento, Inc. All rights reserved.
85+
* See COPYING.txt for license details.
86+
*/
87+
88+
declare(strict_types=1);
89+
90+
namespace Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData;
91+
92+
/**
93+
* Provides runtime-specific data for additional data content types configuration
94+
*/
95+
interface ProviderInterface
96+
{
97+
/**
98+
* Get data from the provider
99+
* @param string $itemName - the name of the item to use as key in returned array
100+
* @return array
101+
*/
102+
public function getData(string $itemName) : array;
103+
}
104+
```
105+
106+
`getData` then returns an array that must contain the key of the configuration item you're providing.
107+
108+
### Example use case
109+
110+
In the `additional_data` XML config there is a `storeId` item with a `storeId` provider class, which must return `['storeId' => ...value here...]` to be integrated properly:
111+
112+
```
113+
<item name="storeId" xsi:type="object">\Magento\PageBuilder\Model\Config\ContentTypes\AdditionalData\Provider\StoreId</item>
114+
```
115+
116+
Custom configuration is injected into relevant content type block constructors (TypeScript), such as for the image block shown here, and accessed in `config.additional_data` within the content block type in `/app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/component/block/<your-content-type>.ts`:
117+
118+
``` typescript
119+
const uploaderConfiguration = Object.assign(
120+
{},
121+
config.additional_data.uploaderConfig,
122+
{
123+
value: this.stage.store.get(this.id).image,
124+
},
125+
);
126+
127+
// Create uploader
128+
this.uploader = new Uploader(
129+
this.id,
130+
"imageuploader_" + this.id,
131+
Object.assign({}, uploaderConfiguration, {
132+
value: this.stage.store.get(this.id).image,
133+
}),
134+
uploaderConfiguration,
135+
);
136+
```

0 commit comments

Comments
 (0)