From 108a3d81b1e573aa9a03f0323bf7b6481e7dd4e2 Mon Sep 17 00:00:00 2001 From: Bruce Denham Date: Tue, 9 Feb 2021 09:58:58 -0600 Subject: [PATCH 1/3] Fixed all md linting errors. --- docs/create-custom-content-type/overview.md | 8 +- .../step-1-add-configuration.md | 23 +- .../step-2-add-templates.md | 17 +- .../step-3-add-components.md | 27 ++- .../step-4-add-form.md | 86 ++++---- .../step-5-add-styles.md | 1 - .../step-6-add-icon.md | 14 +- docs/create-custom-content-type/summary.md | 24 +- .../workflow-tips.md | 2 +- docs/extend-existing-content-type/overview.md | 11 +- .../step-2-extend-appearances.md | 15 +- .../step-3-extend-forms.md | 10 +- .../install-pagebuilder-examples.md | 36 ++- docs/getting-started/install-pagebuilder.md | 6 +- docs/getting-started/view-pagebuilder.md | 14 +- .../how-to-add-additional-configurations.md | 15 +- docs/how-to/how-to-add-appearance.md | 18 +- docs/how-to/how-to-add-custom-toolbar.md | 27 +-- docs/how-to/how-to-add-icons-images.md | 24 +- docs/how-to/how-to-add-image-uploader.md | 53 +++-- docs/how-to/how-to-add-storefront-widget.md | 14 +- docs/how-to/how-to-add-text-editor.md | 34 ++- .../how-to/how-to-apply-product-conditions.md | 18 +- .../how-to-create-container-content-type.md | 51 +++-- docs/how-to/how-to-customize-panel.md | 12 +- docs/how-to/how-to-customize-selectors.md | 4 +- docs/how-to/how-to-deactivate-pagebuilder.md | 10 +- ...-use-pagebuilder-for-product-attributes.md | 6 +- .../how-to/how-to-use-server-side-previews.md | 16 +- docs/how-to/how-to-use-upgrade-library.md | 5 +- docs/index.md | 18 +- docs/intro.md | 18 +- docs/reference/architecture.md | 39 ++-- docs/reference/configurations.md | 135 ++++++------ docs/reference/events.md | 205 +++++++++--------- docs/reference/knockout-bindings.md | 20 +- .../styling/use-modules-to-override-styles.md | 2 +- docs/styling/use-themes-to-override-styles.md | 20 +- 38 files changed, 519 insertions(+), 539 deletions(-) diff --git a/docs/create-custom-content-type/overview.md b/docs/create-custom-content-type/overview.md index 8bd88ee..95b3e43 100644 --- a/docs/create-custom-content-type/overview.md +++ b/docs/create-custom-content-type/overview.md @@ -6,7 +6,7 @@ Page Builder comes with several content types (controls) you can use to build yo ## Quote preview -The following screenshot shows three instances of the Quote control you will build in this tutorial: +The following screenshot shows three instances of the Quote control you will build in this tutorial: ![QuoteTypeDisplay](../images/AdminTestimonials.png) @@ -30,16 +30,16 @@ The steps for creating the Quote content type are illustrated and described belo ![Creating Custom Content Types](../images/content-type-overview.svg) -1. **Add configuration**: Create an XML file to define your content type and reference the other files that control the appearance and behavior of your content type. +1. **Add configuration**: Create an XML file to define your content type and reference the other files that control the appearance and behavior of your content type. 2. **Add templates**: Create HTML templates that define the appearance of your content types on the Admin stage (`preview.html`) and the storefront (`master.html`). 3. **Add component**: Create a JavaScript file that defines the behavior of your content type on the Admin stage (`preview.js`) and the storefront (`master.js`). 4. **Add form**: Create a UI component form and a layout so Admin users can edit your content type within the Page Builder editor. -5. **Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront. +5. **Add styles**: Create LESS files to style your content types when rendered in the Admin UI and on the storefront. 6. **Add an icon**: Create an SVG icon to visually identify your content type within the Page Builder panel. ## Quote file structure -Before we get started, take a look at what you will be building. The directory structure on the left shows the basic `PageBuilderQuote` module you will start with (as previously described). The directory structure on the right shows all the files you will add to the `PageBuilderQuote` module throughout this tutorial, labeled by the steps in the process. +Before we get started, take a look at what you will be building. The directory structure on the left shows the basic `PageBuilderQuote` module you will start with (as previously described). The directory structure on the right shows all the files you will add to the `PageBuilderQuote` module throughout this tutorial, labeled by the steps in the process. ![Before and after content type](../images/content-type-files.png) diff --git a/docs/create-custom-content-type/step-1-add-configuration.md b/docs/create-custom-content-type/step-1-add-configuration.md index 1153315..5c8bc29 100644 --- a/docs/create-custom-content-type/step-1-add-configuration.md +++ b/docs/create-custom-content-type/step-1-add-configuration.md @@ -57,18 +57,18 @@ The following configuration is from the Quote content type. An overview of these The `type` element defines the key properties of your content type. The attributes from the previous code example are described here: -| Attribute | Description | -| ------------------- | ------------------------------------------------------------ | -| `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. | -| `label` | Label displayed in the Page Builder panel, option menu, and on the Admin stage. | -| `menu_section` | Menu section or category in the panel menu where your content type is displayed. The default menu sections are Layout, Elements, Media, and Add Content. See [Panel configurations](../how-to/how-to-customize-panel.md) for more details. | -| `component` | View model responsible for rendering the preview and master format. The component does not need to specify the `.js` extension. 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. | -| `preview_component` | JavaScript file (`preview.js` or `preview-collection.js`) that provides rendering logic within the Admin UI. The preview component does not need to specify the `.js` extension.

For _collection_ content types, you need to either reference your own `preview-collection` component or reference Page Builder's `preview-collection` (`preview_component="Magento_PageBuilder/js/content-type/preview-collection"`). If you don't specify the `preview_component`, Page Builder uses the base `Preview` component shown in the code: `Magento_PageBuilder/js/content-type/preview`. | +| Attribute | Description | +|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `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. | +| `label` | Label displayed in the Page Builder panel, option menu, and on the Admin stage. | +| `menu_section` | Menu section or category in the panel menu where your content type is displayed. The default menu sections are Layout, Elements, Media, and Add Content. See [Panel configurations](../how-to/how-to-customize-panel.md) for more details. | +| `component` | View model responsible for rendering the preview and master format. The component does not need to specify the `.js` extension. 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. | +| `preview_component` | JavaScript file (`preview.js` or `preview-collection.js`) that provides rendering logic within the Admin UI. The preview component does not need to specify the `.js` extension.

For _collection_ content types, you need to either reference your own `preview-collection` component or reference Page Builder's `preview-collection` (`preview_component="Magento_PageBuilder/js/content-type/preview-collection"`). If you don't specify the `preview_component`, Page Builder uses the base `Preview` component shown in the code: `Magento_PageBuilder/js/content-type/preview`. | | `master_component` | JavaScript file (`master.js` or `master-collection.js`) that provides rendering logic generic for all appearances of your content type when rendered on the storefront. The master component does not need to specify the `.js` extension.

For _collection_ content types, you need to either reference your own `master-collection` component or reference Page Builder's `master-collection` (`master_component="Magento_PageBuilder/js/content-type/master-collection"`). If you don't specify the `master_component`, Page Builder uses the base `Master` component shown in the code: `Magento_PageBuilder/js/content-type/master`. | -| `form` | UI component form that provides the form controls for editing your content type. | -| `icon` | Optional. Class name for your PNG or SVG image (or font icon) displayed in the Page Builder panel alongside the label. If you don't provide an icon value, the Page Builder panel displays the content type name without an icon. | -| `sortOrder` | Optional. The listed order within the menu section. For example, `sortOrder=21` puts the content type third in the `Elements` menu section, after the content types with `sortOrder` values of 10 and 20. | -| `translate` | Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. | +| `form` | UI component form that provides the form controls for editing your content type. | +| `icon` | Optional. Class name for your PNG or SVG image (or font icon) displayed in the Page Builder panel alongside the label. If you don't provide an icon value, the Page Builder panel displays the content type name without an icon. | +| `sortOrder` | Optional. The listed order within the menu section. For example, `sortOrder=21` puts the content type third in the `Elements` menu section, after the content types with `sortOrder` values of 10 and 20. | +| `translate` | Identifies the attribute you want Magento to translate. Here, the `label` value is set for translation. | ## The `children` element @@ -119,4 +119,3 @@ The `` element as defined within an `appearance` is to map the data fr ## Next [Step 2: Add templates](step-2-add-templates.md) - diff --git a/docs/create-custom-content-type/step-2-add-templates.md b/docs/create-custom-content-type/step-2-add-templates.md index 42e1781..7537158 100644 --- a/docs/create-custom-content-type/step-2-add-templates.md +++ b/docs/create-custom-content-type/step-2-add-templates.md @@ -8,9 +8,9 @@ Content type templates are the HTML files (HTML fragments) that define how your Conventions for adding content type templates are as follows. -- Page Builder requires you to name your templates `preview.html` for the Admin preview template and `master.html` for the master format storefront template. +- Page Builder requires you to name your templates `preview.html` for the Admin preview template and `master.html` for the master format storefront template. -- Page Builder requires the name of an `appearance` to match the name of the directory containing the appearance templates. If they don't match, your content type appearances will not render. +- Page Builder requires the name of an `appearance` to match the name of the directory containing the appearance templates. If they don't match, your content type appearances will not render. For example, if you navigate to the Banner's appearance templates (`PageBuilder/view/adminhtml/web/template/content-type/banner`) you can see that the names of the template directories match the names of the four appearances defined in the `banner.xml` configuration file as shown here: @@ -55,13 +55,13 @@ These files can be blank initially; they just need to exist in their proper loca The following table describes each `appearance` attribute in our example. -| Attribute | Description | -| ------------------ | ------------------------------------------------------------ | -| `name` | As noted by convention, the name of the appearance and the name of the directory for the appearance templates *must* match. | -| `default` | Every content type must have a default appearance. If you only define one appearance for your content type, you must set the default to `true`. | -| `preview_template` | References the `preview.html` (the Admin preview template) for rendering the preview appearance of your content type on the stage within the Admin UI. | +| Attribute | Description | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | As noted by convention, the name of the appearance and the name of the directory for the appearance templates *must* match. | +| `default` | Every content type must have a default appearance. If you only define one appearance for your content type, you must set the default to `true`. | +| `preview_template` | References the `preview.html` (the Admin preview template) for rendering the preview appearance of your content type on the stage within the Admin UI. | | `master_template` | References the `master.html` (the master format storefront template) for rendering the appearance of your content type on the storefront for customers to see. | -| `reader` | Reads content type data from the master format. | +| `reader` | Reads content type data from the master format. | ## Quote `preview_template` @@ -225,4 +225,3 @@ The `html` value is derived from the configuration `element` name (`quote`) and ## Next [Step 3: Add components](step-3-add-components.md) - diff --git a/docs/create-custom-content-type/step-3-add-components.md b/docs/create-custom-content-type/step-3-add-components.md index 68b057c..fd015fa 100644 --- a/docs/create-custom-content-type/step-3-add-components.md +++ b/docs/create-custom-content-type/step-3-add-components.md @@ -12,16 +12,16 @@ Components are JavaScript files that define the behaviors of your content type w Adding custom component files to your content types is completely optional. Whether you need one or not will depend on the complexity of your content type. If you do not add components to your content type, Page Builder will use these defaults: -- Default preview component: `Magento_PageBuilder/js/content-type/preview` -- Default master component: `Magento_PageBuilder/js/content-type/master` +- Default preview component: `Magento_PageBuilder/js/content-type/preview` +- Default master component: `Magento_PageBuilder/js/content-type/master` When you start developing more complex content types, you will need to create custom preview components in order to make these and other functions available on the Admin stage: -- Initiating and using additional 3rd party libraries like sliders and tabs. -- Adding image uploader support. -- Providing dynamic data into your preview templates from the back-end. -- Allowing the back-end to conduct rendering (such as our block and dynamic block content types). -- Declaring special states based on the data stored, for example, showing a disabled state when certain fields are set to specific values. +- Initiating and using additional 3rd party libraries like sliders and tabs. +- Adding image uploader support. +- Providing dynamic data into your preview templates from the back-end. +- Allowing the back-end to conduct rendering (such as our block and dynamic block content types). +- Declaring special states based on the data stored, for example, showing a disabled state when certain fields are set to specific values. Examples of implementing these functions will be add to future tutorials and other topics in this documentation. @@ -31,11 +31,11 @@ Adding your own master component is far less common. The master component is onl The conventions for naming your components and adding them to your module are as follows: -- Your preview component must be named `preview.js` and placed here in your module (`view/adminhtml/web/js/content-type/example-quote/`): +- Your preview component must be named `preview.js` and placed here in your module (`view/adminhtml/web/js/content-type/example-quote/`): ![Create config file](../images/step3-add-component.png) -- Your master component must be named `master.js` and placed here in your module (`view/frontend/web/js/content-type/example-quote/`): +- Your master component must be named `master.js` and placed here in your module (`view/frontend/web/js/content-type/example-quote/`): ![Create config file](../images/step3-add-master-component.png) @@ -62,10 +62,10 @@ In your configuration file, reference your Admin `preview_component` (`preview.j A description of each component-related attribute from the Quote configuration follows: -| Attribute | Description | -| ------------------- | ------------------------------------------------------------ | -| `component` | Page Builder provides 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 (like our Quote). Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children (container content types). You can also create and specify your own component implementations, provided they conform to the Page Builder interfaces. | -| `preview_component` | Optional. The `preview.js` file provides rendering logic to the Admin preview template. If your content type does not require any changes to Page Builder's standard rendering logic, you can omit this attribute from the the `type` element. When you omit the attribute, Page Builder will use `Magento_PageBuilder/js/content-type/preview` by default.

However, if you want to make changes to the option menu for your content type, or other customize other user-interactivity in the Admin, you need to create your own preview component as we have done for the Quote content type. | +| Attribute | Description | +|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `component` | Page Builder provides 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 (like our Quote). Use `Magento_PageBuilder/js/content-type-collection` for content types that can contain children (container content types). You can also create and specify your own component implementations, provided they conform to the Page Builder interfaces. | +| `preview_component` | Optional. The `preview.js` file provides rendering logic to the Admin preview template. If your content type does not require any changes to Page Builder's standard rendering logic, you can omit this attribute from the the `type` element. When you omit the attribute, Page Builder will use `Magento_PageBuilder/js/content-type/preview` by default.

However, if you want to make changes to the option menu for your content type, or other customize other user-interactivity in the Admin, you need to create your own preview component as we have done for the Quote content type. | | `master_component` | Optional. The `master.js` file provides rendering logic to the master format storefront template. As with the `preview_component`, if your content type does not require any specific user-interactivity or other behavior when it's displayed in the storefront, you can simply omit this attribute from the the `type` element. When you omit the attribute, Page Builder will use `Magento_PageBuilder/js/content-type/master` by default.

In the Quote configuration, the `master_component` attribute is only included for discussion. It simply points to the Page Builder default `master.js` component that would be used the attribute was omitted. | ## Quote `preview_component` @@ -176,4 +176,3 @@ As mentioned previously, our Quote content type has no need for a master compone ## Next [Step 4: Add form](step-4-add-form.md) - diff --git a/docs/create-custom-content-type/step-4-add-form.md b/docs/create-custom-content-type/step-4-add-form.md index 36db5e9..b9f7f44 100644 --- a/docs/create-custom-content-type/step-4-add-form.md +++ b/docs/create-custom-content-type/step-4-add-form.md @@ -6,9 +6,9 @@ In this step, we will create a UI component form. This form will give users anot Page Builder provides two base forms that give you a ton of functionality you can inherit from right out-of-the-box: -- `pagebuilder_base_form` +- `pagebuilder_base_form` -- `pagebuilder_base_form_with_background_attributes` (inherits from `pagebuilder_base_form`) +- `pagebuilder_base_form_with_background_attributes` (inherits from `pagebuilder_base_form`) Inheriting from either base form gives you an editor for your content type that slides out from the right side of the Admin screen. @@ -30,13 +30,13 @@ The base form you inherit from depends on the complexity of the content type you The conventions for naming your form and its layout are as follows: -- The name for your form should follow this pattern: `pagebuilder_` + `content_type_name_` + `form.xml`. For example `pagebuilder_example_quote_form.xml`. -- The name for your layout must match the name of your form, in this case: `pagebuilder_example_quote_form.xml`. +- The name for your form should follow this pattern: `pagebuilder_` + `content_type_name_` + `form.xml`. For example `pagebuilder_example_quote_form.xml`. +- The name for your layout must match the name of your form, in this case: `pagebuilder_example_quote_form.xml`. Add your form and layout files to your module in the following locations: -- `view/adminhtml/layout/` -- `view/adminhtml/ui_component/` +- `view/adminhtml/layout/` +- `view/adminhtml/ui_component/` ![Create config file](../images/step4-add-form.png) @@ -53,8 +53,8 @@ In your configuration file, add your form name (without the .xml file extension) ...> ``` -| Attribute | Description | -| --------- | ------------------------------------------------------------ | +| Attribute | Description | +|-----------|------------------------------------------------------------------------------------| | `form` | Name of the UI component form that provides the form editor for your content type. | ## The Quote form @@ -65,11 +65,11 @@ In our Quote form, we will inherit from `pagebuilder_base_form_with_background_a The purpose of each field is described as follows: -| Field | Description | -| ------------- | ------------------------------------------------------------ | -| Quote | A textarea for writing or pasting in the quote's text. | -| Author | A text input field for the author's name. | -| Description | A text input field to describe the author's title or origin of the quote. | +| Field | Description | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Quote | A textarea for writing or pasting in the quote's text. | +| Author | A text input field for the author's name. | +| Description | A text input field to describe the author's title or origin of the quote. | | CSS for Quote | A text input field for end-users to add CSS class names for styling the text in the Quote field. This option is detailed in [Step 5: Add styles](step-5-add-styles.md). | The Quote form is shown in full here for you to copy into your `pagebuilder_example_form.xml` file, followed by descriptions of the key parts. @@ -230,24 +230,24 @@ Again, even though our Quote control doesn't currently define an appearance, we Page Builder requires fields to be grouped within named `
` elements. Fieldsets provide your fields with a basic grouping mechanism and an optional label. You can define as many fieldsets as you want. -| Attribute | Description | -| ----------- | ------------------------------------------------------------ | -| `name` | You can name your fieldset whatever you want. Currently, it has no significance for data binding. | +| Attribute | Description | +|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | You can name your fieldset whatever you want. Currently, it has no significance for data binding. | | `sortOrder` | Determines where Page Builder puts the fieldset within the editor in relation to other fieldsets. Page Builder sets the `sortOrder` for the `pagebuilder_base_form` fieldset to `90`. Setting your fieldset to a value less than that (such as `20`) will put your fieldset above both inherited fieldsets. A value greater than `90` will put your fieldset below the inherited fieldsets. | ### field The `` element creates the actual HTML form element as specified by the `formElement` attribute, such as input, select, textarea, and colorPicker. -| Attribute | Description | -| ------------- | ------------------------------------------------------------ | -| `name` | The name of the field used for data bindings. | +| Attribute | Description | +|---------------|-----------------------------------------------------------------------------------------------| +| `name` | The name of the field used for data bindings. | | `sortOrder` | Determines where Page Builder puts the field within the fieldset in relation to other fields. | -| `formElement` | Determines the HTML form element to render for the field. | +| `formElement` | Determines the HTML form element to render for the field. | ### data source -Defines the data source for the field. The source` node's value corresponds to a key (`page`) in the data array returned by the `\Magento\Framework\View\Element\UiComponent\DataProvider\DataProviderInterface::getData` method of your UI component. +Defines the data source for the field. The source node's value corresponds to a key (`page`) in the data array returned by the `\Magento\Framework\View\Element\UiComponent\DataProvider\DataProviderInterface::getData` method of your UI component. ```xml @@ -272,11 +272,11 @@ The `` element defines the data scope, data type, and label to use for ``` -| Attribute | Description | -| ----------- | ------------------------------------------------------------ | +| Attribute | Description | +|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `dataScope` | Specifies the name of your input field for data binding. The `dataScope` node allows you to change the value of the `name` attribute for your input field. We do not need to change the field name value, so we keep our dataScope value the same as our field name. | -| `dataType` | Specifies the data type for the field's data. Common values are `text` and `boolean`. | -| `label` | Specifies the text label applied to the input field on the form. | +| `dataType` | Specifies the data type for the field's data. Common values are `text` and `boolean`. | +| `label` | Specifies the text label applied to the input field on the form. | ## Quote form layout @@ -333,42 +333,42 @@ The following elements are from our `example_quote.xml` configuration. These ele ``` -#### element +### element The `` element provides a scope for the data bindings within it. -| Attribute | Description | -| --------- | ------------------------------------------------------------ | +| Attribute | Description | +|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | Specifies the name of the element scope for the data binding when applied to template elements. In our example, the element name of `main` is used as the scope for binding styles and other attributes to the top-level `
` element in our template: `
` | -#### style +### style The `