Skip to content

Commit d3aa2bf

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 48969d6 + 14fea21 commit d3aa2bf

17 files changed

+421
-75
lines changed

README.md

Lines changed: 76 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,85 @@
11
# magento2-page-builder
22

3-
# PageBuilder EAP
3+
## PageBuilder Early Access Program
44

5-
We open access to PageBuilder code for Partners to:
6-
- explore extension points that PageBuilder provides in oder to build integration with native PageBuilder capabilities for 3rd parties (Facebook, Instagram etc) and their own modules
7-
- try out PageBuilder customization options to grow its functionality beyond native features
8-
- Prepare to migrate clients from Bluefoot 1.0 to PageBuilder
5+
The PageBuilder Early Access Program (EAP) gives partners the following perks:
96

10-
This program is _not design_ to build a website and go live using early code.
7+
* Explore PageBuilder extension points to build custom modules and integrations for 3rd party services, such as Facebook, Instagram, etc.
8+
* Try out PageBuilder customization options and extend its functionality beyond its default features.
9+
* Preview PageBuilder to prepare a migration plan from BlueFoot 1.0 to PageBuilder.
10+
11+
**Note:**
12+
*This program should not be used to design and launch a production website using early code.*
1113

12-
# PageBuilder Package
13-
We offer 2 options to get the PageBuilder code:
14-
- Composer package - option for installing page builder if you do not plan to do any contribution into PageBuilder code repository
15-
- GitHub repository - option to install page builder and contribute to the code
14+
## Installation
1615

17-
# Contribution to the PageBuilder
18-
We appreciate your direct contribution to PageBuilder repo. It can be either feature development or bug fix:
19-
List of known issues
16+
We offer two methods for installing PageBuilder:
2017

21-
# PageBuilder Updates from Magento Core Team
22-
Expect the code to be updated on regular basis (every 2 weeks) and be ready to the update introducing breaking changes. We want to limit that harm so we publish the backlog that core teams are going to work on next couple of months:
23-
link to the list of features
18+
* As a [Composer package] - use this option if you do not plan to contribute to the PageBuilder code repository
19+
* Using the [GitHub repository] - use this option to install PageBuilder from the GitHub repository and contribute to the code
2420

25-
# Feedback needed
26-
We want to know more how you would need to customize PageBuilder. Here is the list of topics that we are specifically interested in:
27-
Web Content API
21+
[Composer package]: app/code/Magento/PageBuilder/docs/install.md#composer-installation
22+
[GitHub repository]: app/code/Magento/PageBuilder/docs/install.md#github-installation
2823

29-
Join the PageBuilder slack channel to participate in technical discussions and ask questions
30-
URL: magentocommeng.slack.com
31-
And ping Olena Tkacheva (https://magentocommeng.slack.com/messages/@UAFV915FB)
24+
## Developer documentation
25+
26+
This project repository contains PageBuilder developer documentation on the following topics:
27+
28+
1. [Architecture overview]
29+
1. [BlueFoot to PageBuilder data migration]
30+
1. [Third-party content type migration]
31+
1. [Iconography]
32+
1. [Module integration]
33+
1. [Additional data configuration]
34+
1. [Content type configuration]
35+
1. [How to add a new content type]
36+
1. [Events]
37+
1. [Master format]
38+
1. [Visual select]
39+
40+
[Architecture overview]: app/code/Magento/PageBuilder/docs/architecture-overview.md
41+
[BlueFoot to PageBuilder data migration]: app/code/Magento/PageBuilder/docs/bluefoot-data-migration.md
42+
[Third-party content type migration]: app/code/Magento/PageBuilder/docs/new-content-type-example.md
43+
[Iconography]: app/code/Magento/PageBuilder/docs/iconography.md
44+
[Module integration]: app/code/Magento/PageBuilder/docs/module-integration.md
45+
[Additional data configuration]: app/code/Magento/PageBuilder/docs/custom-configuration.md
46+
[Content type configuration]: app/code/Magento/PageBuilder/docs/content-type-configuration.md
47+
[How to add a new content type]: app/code/Magento/PageBuilder/docs/how-to-add-new-content-type.md
48+
[Events]: app/code/Magento/PageBuilder/docs/events.md
49+
[Master format]: app/code/Magento/PageBuilder/docs/master-format.md
50+
[Visual select]: app/code/Magento/PageBuilder/docs/visual-select.md
51+
52+
## Contribute to PageBuilder
53+
54+
We appreciate any and all contributions to PageBuilder.
55+
A good place to start is by looking at our [features roadmap] and list of [known issues].
56+
57+
If you are interested in contributing to this repository, please see our [Contribution Guide].
58+
59+
[Contribution Guide]: app/code/Magento/PageBuilder/docs/CONTRIBUTING.md
60+
[features roadmap]: app/code/Magento/PageBuilder/docs/roadmap.md#planned-features-and-functionality
61+
[known issues]: app/code/Magento/PageBuilder/docs/roadmap.md#known-issues
62+
63+
## PageBuilder updates from the Magento core team
64+
65+
The PageBuilder team updates the code every 2 weeks.
66+
**These changes may introduce breaking changes.**
67+
68+
To help you prepare for these changes, we are publishing a [roadmap] of features and issues that we are going to work on in the following months.
69+
70+
[roadmap]: app/code/Magento/PageBuilder/docs/roadmap.md
71+
72+
## Provide feedback
73+
74+
We want to hear what you think of PageBuilder!
75+
We are particularly interested on your thoughts on the following:
76+
77+
* [How would you customize PageBuilder and what do you need to accomplish this task?](https://github.com/magento/magento2-page-builder/issues/57)
78+
* [What web content API do you use or would like to see in PageBuilder?](https://github.com/magento/magento2-page-builder/issues/58)
79+
80+
To participate in technical discussions and ask questions, join us in [Slack].
81+
82+
For all other questions or requests, contact [Olena Tkacheva].
83+
84+
[Slack]: https://magentocommeng.slack.com/
85+
[Olena Tkacheva]: https://magentocommeng.slack.com/messages/@UAFV915FB

app/code/Magento/PageBuilder/docs/CONTRIBUTING.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,36 @@
11
# Contributing to Magento 2 code
22

3+
## Navigation
4+
5+
1. [Introduction]
6+
2. [Installation guide]
7+
3. **Contribution guide**
8+
1. [Overview](#overview)
9+
1. [Contribution requirements](#contribution-requirements)
10+
1. [Contribution process](#contribution-process)
11+
1. [Code of Conduct](#code-of-conduct)
12+
4. [Developer documentation]
13+
5. [Roadmap and known issues]
14+
15+
[Introduction]: README.md
16+
[Installation Guide]: install.md
17+
[Contribution guide]: CONTRIBUTING.md
18+
[Developer documentation]: developer-documentation.md
19+
[Architecture overview]: architecture-overview.md
20+
[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md
21+
[Third-party content type migration]: new-content-type-example.md
22+
[Iconography]: iconography.md
23+
[Module integration]: module-integration.md
24+
[Additional data configuration]: custom-configuration.md
25+
[Content type configuration]: content-type-configuration.md
26+
[How to add a new content type]: how-to-add-new-content-type.md
27+
[Events]: events.md
28+
[Master format]: master-format.md
29+
[Visual select]: visual-select.md
30+
[Roadmap and Known Issues]: roadmap.m
31+
32+
## Overview
33+
334
Contributions to the Magento 2 codebase are done using the fork & pull model.
435
This contribution model has contributors maintaining their own copy of the forked codebase (which can easily be synced with the main copy). The forked repository is then used to submit a request to the base repository to “pull” a set of changes (hence the phrase “pull request”).
536

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,25 +7,34 @@ It replaces the default WYSIWYG Editor in the Admin area with a highly configura
77

88
1. **Introduction**
99
2. [Installation guide]
10-
3. Contribution guide
10+
3. [Contribution guide]
1111
4. [Developer documentation]
12+
1. [Architecture overview]
1213
1. [BlueFoot to PageBuilder data migration]
1314
1. [Third-party content type migration]
1415
1. [Iconography]
1516
1. [Module integration]
1617
1. [Additional data configuration]
1718
1. [Content type configuration]
1819
1. [How to add a new content type]
20+
1. [Events]
21+
1. [Master format]
22+
1. [Visual select]
1923
5. [Roadmap and known issues]
2024

2125
[Introduction]: README.md
2226
[Installation Guide]: install.md
27+
[Contribution guide]: CONTRIBUTING.md
2328
[Developer documentation]: developer-documentation.md
29+
[Architecture overview]: architecture-overview.md
2430
[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md
2531
[Third-party content type migration]: new-content-type-example.md
2632
[Iconography]: iconography.md
2733
[Module integration]: module-integration.md
2834
[Additional data configuration]: custom-configuration.md
2935
[Content type configuration]: content-type-configuration.md
3036
[How to add a new content type]: how-to-add-new-content-type.md
37+
[Events]: events.md
38+
[Master format]: master-format.md
39+
[Visual select]: visual-select.md
3140
[Roadmap and Known Issues]: roadmap.md
Lines changed: 100 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,85 @@
11
# Architecture overview
22

3-
## What is Page Builder?
4-
5-
PageBuilder is tool that simplifies content creation. It allows to grag and drop content types and configure them. Changes are immediately displayed in the preview in admin and it matches to what user will see on the storefront.
6-
7-
## What is Page Builder?
8-
9-
PageBuilder is tool that simplifies content creation. It allows to grag and drop content types and configure them. Changes are immediately displayed in the preview in admin and it matches to what user will see on the storefront.
3+
## Navigation
4+
5+
1. [Introduction]
6+
2. [Installation guide]
7+
3. [Contribution guide]
8+
4. [Developer documentation]
9+
1. **Architecture overview**
10+
1. [BlueFoot to PageBuilder data migration]
11+
1. [Third-party content type migration]
12+
1. [Iconography]
13+
1. [Module integration]
14+
1. [Additional data configuration]
15+
1. [Content type configuration]
16+
1. [How to add a new content type]
17+
1. [Events]
18+
1. [Master format]
19+
1. [Visual select]
20+
5. [Roadmap and known issues]
21+
22+
[Introduction]: README.md
23+
[Contribution guide]: CONTRIBUTING.md
24+
[Installation Guide]: install.md
25+
[Developer documentation]: developer-documentation.md
26+
[Architecture overview]: architecture-overview.md
27+
[BlueFoot to PageBuilder data migration]: bluefoot-data-migration.md
28+
[Third-party content type migration]: new-content-type-example.md
29+
[Iconography]: iconography.md
30+
[Module integration]: module-integration.md
31+
[Additional data configuration]: custom-configuration.md
32+
[Content type configuration]: content-type-configuration.md
33+
[How to add a new content type]: how-to-add-new-content-type.md
34+
[Events]: events.md
35+
[Master format]: master-format.md
36+
[Visual select]: visual-select.md
37+
[Roadmap and Known Issues]: roadmap.md
38+
39+
## What is PageBuilder?
40+
41+
PageBuilder is tool that simplifies content creation by letting you drag and drop content types and configure them without writing a line of code.
42+
Changes appear in real time in the preview area in the Admin and matches what users see on the storefront.
1043

1144
## Technologies
1245

13-
Page Builder written in TypeScript, however it comes with compiled JavaScript. You don't need to worry about compiling TypeScript or use it TypeScript your module.
46+
PageBuilder is written in [TypeScript], a superset of JavaScript, that is compiled down to JavaScript prior to a release.
47+
Use the TypeScript components in the module as reference to understand the flow information.
1448

15-
Page Builder also uses Knockout.js, UI components for building forms and different libraries like slick.
49+
**Note:**
50+
*You do not need to use TypeScript in your module to work with the PageBuilder code.*
51+
52+
PageBuilder also uses core Magento technologies such as jQuery, Knockout & UI Components.
53+
It also uses additional libraries to help with various content types shipped with the module.
1654

1755
## Storage format
1856

19-
For storage (later master format) Page Builder uses XHTML with inline styles and data attributes. The idea is that is that content can be displayed with minimum changes on Magento storefront and also by third party systems.
57+
PageBuilder uses XHTML with inline stlyes and data attributes for storage and as the [master format].
58+
This allows the content to be displayed with minimum changes to the Magento storefront and other third-party systems.
2059

2160
To display Page Builder content on storefront Magento and third party systems need to do the following
2261

23-
1. Replace Magento directives (for instance {{image url=path/to/image.png}}).
24-
2. Add custom stylesheet to provide base styles that user can't edit (this includes styles for the content types like `slider`, `tabs`, `accordion`, etc).
25-
3. After content is rendered, on the frontend find all of content types that need to have widgets initialized (for instance, slider, tabs, etc) and load and initialize these widgets.
62+
Use the following steps to display PageBuilder content on a Magento storefront or third-party system:
2663

27-
See more on [master format](master-format.md)
64+
1. Replace all Magento directives such as `{{image url=path/to/image.png}}`
65+
2. Add custom stylesheet to provide the base styles that user can't edit.
66+
This includes styles for the content types such as `slider`, `tabs`, `accordion`, etc.
67+
3. After the content renders, load and initialze the widgets and libraries on the frontend that need initalization, such as slider, tabs, etc.
2868

2969
## Integration with Magento and custom modules
3070

31-
PageBuilder replaces WYSIWYG on all forms. You can enable/disable Page Builder for product attributes.
71+
When PageBuilder is enabled in the system configuration, it replaces all WYSIWYG instances.
72+
It does this by intercepting the WYSIWYG UI Component field and replacing the traditional WYSIWYG editor with the PageBuilder editor.
73+
74+
This means that any custom extension that utilises the WYSIWYG field UI Component automatically supports the PageBuilder editor.
3275

33-
Page Builder also would be enabled in custom extensions where WYSIWYG is used.
76+
To revert back to using the default WYSIWYG, add the following entry to the field configuration in the XML configuration file:
77+
78+
```
79+
<item name="wysiwygConfigData" xsi:type="array">
80+
<item name="is_pagebuilder_enabled" xsi:type="boolean">false</item>
81+
</item>
82+
```
3483

3584
## Big picture
3685

@@ -52,43 +101,52 @@ Page Builder also would be enabled in custom extensions where WYSIWYG is used.
52101

53102
![Page Builder data flow](images/data-flow.png)
54103

55-
Here is simplified data flow:
56-
1. Data read by reader `Magento_PageBuilder/js/master-format/read/configurable`.
57-
2. Data for each element (`border`, `border_color`, `border_width` etc) converted to internal format by element converters.
58-
3. Data converted by mass converters, for more details see [converter interface](content-type-configuration.md).
59-
4. Content type created and `Magento_PageBuilder/js/data-store` populated with data.
60-
5. Data in data store modified in the form or using live edit.
61-
6. Data converted by mass converters.
62-
7. Converted by element data converters.
63-
8. Preview and master component observables updated.
64-
9. Editable with Page Builder entity attribute updated, when user saves the pages master format being saved to the database.
104+
The following is a simple overview of the data flow:
105+
106+
1. Data is read by reader `Magento_PageBuilder/js/master-format/read/configurable`.
107+
2. Data for each element (`border`, `border_color`, `border_width` etc) is converted to an internal format by element converters.
108+
3. Data is converted by mass converters. For more details see [converter interface](content-type-configuration.md).
109+
4. Content type is created and `Magento_PageBuilder/js/data-store` is populated with data.
110+
5. Data in the data store is modified in the form or using live edit.
111+
6. Data is converted by mass converters.
112+
7. It is then converted by element data converters.
113+
8. The preview and master component observables are updated.
114+
9. When the user saves the page's master format into the database, the editable with the PageBuilder entity attribute is updated.
115+
116+
### Mass converter
65117

66-
Mass converter modifies on data for all content type elements. For instance, if content type two elements, main and image. And data for these elements stored in the fields `border`, `border_color`, `border_width`, `background_image`. Mass converter will allow to modify all these fields. See more on how [data stored internally](#Data store).
118+
A Mass converter modifies data for all content type elements.
119+
For example, the content type of two elements, main and image has data stored in the fields `border`, `border_color`, `border_width`, `background_image`.
120+
A mass converter allows you to modify all these fields.
67121

68-
Element converter modifies single field at a time.
122+
For more information, read about how [data is stored internally](#Data store).
123+
124+
### Element converter
125+
126+
An element converter modifies a single field at a time.
69127

70128
## Data store
71129

72-
Data for content type stored in DataStore `Magento_PageBuilder/js/data-store`.
130+
Data for content types are stored in a simple object called the DataStore `Magento_PageBuilder/js/data-store`.
73131

74-
DataStore is a simple object. `var` from [content type configuration](content-type-configuration.md) is the name of parameter in DataStore.
132+
`var` from [content type configuration](content-type-configuration.md) is the name of a parameter in the DataStore.
75133

76-
You can use `subscribe` method to subscribe to changes of the data and perform custom action on it.
134+
You can use the `subscribe` method to subscribe to changes in the data and perform custom action on it.
77135

78136
## Content type configuration
79137

80-
Please see [content type configuration](content-type-configuration.md#Converter Interfaces) for content type configuration.
138+
Please see [content type configuration](content-type-configuration.md#Converter Interfaces) for information on content type configuration.
81139

82140
## Appearances
83141

84-
Appearances allow to customize existing content types.
142+
Appearances allow you to make the following customization on existing content types:
85143

86-
Appearance allows to make the following customizations to content type:
87-
1. Add new style properties to existing content types.
144+
1. Add new style properties to existing content types
88145
2. Add new attributes to existing content types. This is similar to above.
89146
3. Change templates
90-
4. Move data between elements, achieved with data mapping configuration. For example, developer can move margin from one element to another.
91-
5. Change form for content type.
147+
4. Move data between elements, achieved with data mapping configuration.
148+
For example, a developer can move the `margin` style property from one element to another.
149+
5. Change the form for a [content type]
92150

93151
## Module structure
94152

@@ -99,4 +157,8 @@ Appearance allows to make the following customizations to content type:
99157
| Styles | `Vendor/ModuleName/view/adminhtml/web/css/source/content-type/content-type-name` |
100158

101159
**Note:**
102-
*We also considering introducing appearance component and/or moving initialization of the libraries to bindings. This would allow add custom logic per appearance changes libraries per appearance for content types like slider, tabs, accordion, etc.*
160+
*We also considered introducing appearance component and/or moving the initialization of the libraries to bindings. This would allow you to add custom logic per appearance changes and libraries per appearance for content types like slider, tabs, accordion, etc.*
161+
162+
[TypeScript]: https://www.typescriptlang.org/
163+
[master format]: master-format.md
164+
[content type]: how-to-add-new-content-type.md

0 commit comments

Comments
 (0)