Skip to content

Commit 0b17f30

Browse files
bdenhambdenham
committed
MC-4272: Update content type docs
WIP fixed last of the PR review feedback, with a couple of deferments noted in the PR comments
1 parent 2f9987a commit 0b17f30

File tree

3 files changed

+50
-23
lines changed

3 files changed

+50
-23
lines changed

‎docs/configurations/content-type-configuration.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Use the content type and group configuration to add new content types, extend ex
2424
| `component` | View model responsible for rendering the preview and master format. |
2525
| `preview_component` | Helper component that contains preview specific logic. Helper component is optional. |
2626
| `master_component` | Contains master format rendering logic that is generic for all appearances. Content component is optional. |
27-
| `form` | UI component form used for editing the content type |
27+
| `form` | UI component form used for editing the content type. |
2828
| `group` | Existing menu group that contains this content type. |
2929

3030
### Examples

‎docs/configurations/panel-configurations.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ These groups are defined in the Page Builder `group.xml` file and can be extende
1010

1111
| name | label | sortOrder | purpose |
1212
| ------------- | ----------- | --------- | ------------------------------------------------------ |
13-
| `layout` | Layout | 1 | Groups containers that control the structure of a page |
13+
| `layout` | Layout | 1 | Groups containers that control the structure of a page |
1414
| `elements` | Elements | 10 | Groups common text and input elements |
1515
| `media` | Media | 20 | Groups visual and interactive elements |
1616
| `add_content` | Add Content | 30 | Groups dynamic storefront elements |

‎docs/create-basic-content-type/step-1-add-configuration.md

Lines changed: 48 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,15 @@
22

33
# Step 1: Add configuration
44

5-
Creating a configuration file is the first step to creating a new content type. Through the configuration file, you can specify things like the label, location, and icon of your content type within the Page Builder panel menu. You can specify where your content type can be dropped on the stage, and reference the many other files you will use to control the appearance and behavior your content type.
5+
Creating a configuration file is the first step to defining a new content type. It defines the properties and files that control the appearances and behaviors of a content type.
66

7-
## Create the configuration file
7+
## Create a configuration file
88

9-
1. Create a new XML file in the following directory structure of your module: `view/adminhtml/pagebuilder/content_type/my-content-type.xml`.
9+
Create a new configuration (XML) file in the following directory structure of your module: `view/adminhtml/pagebuilder/content_type/my-content-type.xml`.
1010

11-
![Create config file](../images/create-config-file.png)
11+
![Create config file](../images/create-config-file.png)
1212

13-
2. Copy the contents of this example into your `my-content-type.xml` file. Element descriptions follow:
13+
This config file should contain the following minimal requirements, described in the tables that follow:
1414

1515
``` xml
1616
<?xml version="1.0"?>
@@ -23,8 +23,8 @@ Creating a configuration file is the first step to creating a new content type.
2323
master_component="Magento_PageBuilder/js/content-type/master"
2424
form=""
2525
icon=""
26-
sortOrder="-1"
27-
is_hideable="true"
26+
sortOrder="100"
27+
is_hideable="false"
2828
translate="label">
2929
<appearances>
3030
<appearance name="default"
@@ -44,22 +44,49 @@ Creating a configuration file is the first step to creating a new content type.
4444
</config>
4545
```
4646

47-
**Line 2**: The `content-type.xsd` schema that defines the elements for you config file can be found here: `magento2-page-builder/app/code/Magento/PageBuilder/et/content_type.xsd`.
47+
## The `type` node
4848

49-
**Line 3-13:** Attributes of the <type> element define several key properties of your content type as follows:
49+
The `<type>` node defines the key properties of your content type. The attributes are described here:
5050

51-
| Attribute | Description |
52-
| :-------- | ------------------------------------------------------------ |
53-
| name | Name for your content type. The convention for using multi-word names is to separate the words with hyphens. |
54-
| label | Label that displays in the Page Builder panel, option menu, and on the Admin stage. |
55-
| group | Group or category in the panel menu where your content type is displayed. The default groups are Layout, Elements, Media, and Add Content. See [Panel configurations](../configurations/panel-configurations.md) for more details. |
56-
| component | |
57-
| | |
58-
| | |
59-
| | |
60-
| | |
61-
| | |
51+
| Attribute | Description |
52+
| :---------------- | ------------------------------------------------------------ |
53+
| name | Name of the content type that Magento uses for XML merging. The convention for using multi-word names is to separate the words with hyphens. |
54+
| label | Label displayed in the Page Builder panel, option menu, and on the Admin stage. |
55+
| group | Group or category in the panel menu where your content type is displayed. The default groups are Layout, Elements, Media, and Add Content. See [Panel configurations](../configurations/panel-configurations.md) for more details. |
56+
| component | Currently there are two component types to choose from: `content-type` and `content-type-collection`. Use `Magento_PageBuilder/js/content-type` for static content types that do not have children. Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children, otherwise known as container content types. |
57+
| preview_component | JavaScript file that provides preview-specific rendering logic within the Admin UI. |
58+
| master_component | JavaScript file that provides master format rendering logic generic for all appearances of your content type when rendered on the storefront. |
59+
| form | UI component form that provides the editor for your content type. |
60+
| icon | Optional. PNG or SVG image displayed in the Page Builder panel alongside the label. |
61+
| is_hideable | Optional. Default `true`. Include it only when you want to set it to `false` to prevent the end-user from hiding your content type on demand, using a button (eye icon) in the options menu. A setting of false will remove the hide button from the options menu. |
62+
| translate | Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. |
6263

63-
If you try to view Page Builder at this point, Page Builder will throw an error noting that the `preview_template` and `render_template` from the `<appearance` element are missing. These templates are required before we can add our content type to Page Builder. Let's do that in [Step 2: Add templates](step-2-add-templates.md).
64+
## The `appearance` node
65+
66+
The purpose of the `<appearance>` node in a configuration is to define the appearance of your content type as a preview in the Admin (using the`preview.html` template) and in the storefront for customers (using the `master.html` template).
67+
68+
The `<appearance>` attributes are described as follows:
69+
70+
| attribute | description |
71+
| ---------------- | ------------------------------------------------------------ |
72+
| name | Name of the appearance for extending as needed. |
73+
| default | Content types must specify one of the appearances as the default appearance. That means if you only have one appearance, it must be set as the default. |
74+
| preview_template | `preview.html` - the HTML template for rendering the preview appearance of a content type within the Admin. |
75+
| render_template | `master.html` - the HTML template for rendering the storefront appearance of a content type for customers. |
76+
| reader | Reads data for the content type from the master format |
77+
78+
All content types must have at least one `<appearance>` defined within the `<appearances>` collection.
79+
80+
## The `element` node
81+
82+
**[Dave, I know the following sentence is incorrect. Please rewrite to correct it and add more information as needed. :) ]**
83+
84+
The purpose of the `<element>` nodes in a configuration is to map the data from the content type from the given source back to the master format so that the content type can be updated and rendered correctly within both the Admin preview and the storefront.
85+
86+
**[Add table to describe element attributes and nodes]**
87+
88+
## Next
89+
90+
At this point, if you try to view Page Builder you get an error noting that the `preview_template` and `render_template` from the `<appearance>` element are missing. These templates are referenced in the example config file, but we have not yet created them. Let's do that next in [Step 2: Add templates](step-2-add-templates.md).
6491

6592
<!-- {% endraw %} -->

0 commit comments

Comments
 (0)