Merge pull request #5287 from magento/ds_sync-with-master

Sync develop with master

Author: dshevtsov

_data/toc/javascript-developer-guide.yml

@@ -46,6 +46,9 @@ pages:
         - label: Alert widget
           url: /javascript-dev-guide/widgets/widget_alert.html
 
+        - label: Breadcrumbs widget
+          url: /javascript-dev-guide/widgets/widget-breadcrumbs.html
+
         - label: Calendar widget
           url: /javascript-dev-guide/widgets/widget_calendar.html
 
@@ -79,6 +82,9 @@ pages:
         - label: Modal widget
           url: /javascript-dev-guide/widgets/widget_modal.html
 
+        - label: Multiselect widget
+          url: /javascript-dev-guide/widgets/widget-multiselect.html
+
         - label: Navigation widget
           url: /javascript-dev-guide/widgets/widget_navigation.html
 
@@ -97,6 +103,9 @@ pages:
         - label: RedirectUrl widget
           url: /javascript-dev-guide/widgets/widget_redirectUrl.html
 
+        - label: RowBuilder widget
+          url: /javascript-dev-guide/widgets/widget-row-builder.html
+
         - label: Tabs widget
           url: /javascript-dev-guide/widgets/widget_tabs.html
 

_data/toc/php-developer-guide.yml

@@ -256,6 +256,10 @@ pages:
         - label: Adapters
           url: /extension-dev-guide/adapters.html
 
+        - label: View models
+          include_versions: ["2.2", "2.3"]
+          url: /extension-dev-guide/view-models.html
+
         - label: Variable Pool
           include_versions: ["2.3"]
           url: /extension-dev-guide/variable-pool/

_includes/config/split-deploy/example_save-shared-config.md

@@ -31,7 +31,7 @@
     ```
 
     {:.bs-callout .bs-callout-warning}
-    Do _not_ submit changes to the `generated`, `pub/media`, or `pub/static` directories to source control. You'll generate those files on your build system. The production system likely has code, themes, and so on that aren't ready to use on production.
+    Do _not_ submit changes to the `generated`, `pub/media`, or `pub/static` directories to source control. You'll generate those files on your build system. The development system likely has code, themes, and so on that are not ready for use on the production system.
 
 1.  Check in your changes to `app/etc/config.php` only to source control.
 

_includes/mrg/note.md

@@ -1,4 +1,3 @@
-<div class="bs-callout bs-callout-info" markdown="1">
+{: .bs-callout-info }
 This topic is generated automatically from the corresponding README in the Magento codebase.
 If you want to contribute, refer to [Magento Code Contributions]({{ page.baseurl] }}/contributor-guide/contributing.html).
-</div>

_includes/reference/cli-template.md

@@ -12,80 +12,82 @@ The initial list is auto generated using the `{{ tool }} list` command at the {{
 
 {{ intro }}
 
+## Reference
+
+{: .bs-callout-info }
+This reference is generated from the Magento codebase. To add or update the content, you must update the source code for the corresponding CLI command in the [Magento 2 codebase](https://github.com/magento/magento2) repository and submit your changes for review.  For contribution guidelines, see [Magento Code Contributions]({{ page.baseurl] }}/contributor-guide/contributing.html).
+
 {% for command in commands %}
   {% assign arguments = command.definition.arguments %}
   {% assign options = command.definition.options %}
 
-## `{{ command.name }}`
+### `{{ command.name }}`
 
 {{ command.description }}
 
 ```bash
 {{ tool }} {{ command.usage }}
 ```
 
-  {% unless arguments.size == 0 %}
+{% unless arguments.size == 0 %}
 
-### Arguments
-{: .no_toc}
+#### Arguments
 
-  {% for argument in arguments %}
+{% for argument in arguments %}
   {% for item in argument %}
-  {% if item.name %}
-
-  {% if item.default == empty %}
-  {% endif %}
-
-#### `{{ item.name }}`
-
-- Description: {{ item.description }}
-{% unless item.default == nil %}
-  {% if item.default == false or (item.default == empty and item.default != '') %}
-- Default: `{{ item.default | inspect }}`
-  {% else %}
-- Default: `{{ item.default }}`
-  {% endif %}
-{% endunless %}
-  {% if item.is_required %}
-- Required
-  {% endif %}
-  {% if item.is_array %}
-- Array
-  {% endif %}
-  {% endif %}
-  {% endfor %}
-  {% endfor %}
-
-### Options
-{: .no_toc}
+    {% if item.name %}
+      {% if item.default == empty %}
+      {% endif %}
+
+##### `{{ item.name }}`
+
+-  Description: {{ item.description }}
+   {% unless item.default == nil %}
+   {% if item.default == false or (item.default == empty and item.default != '') %}
+-  Default: `{{ item.default | inspect }}`
+   {% else %}
+-  Default: `{{ item.default }}`
+   {% endif %}
+   {% endunless %}
+   {% if item.is_required %}
+-  Required
+   {% endif %}
+   {% if item.is_array %}
+-  Array
+   {% endif %}
+   {% endif %}
+   {% endfor %}
+   {% endfor %}
+
+#### Options
 
  {% for option in options %}
  {% assign opt = option[1] %}
 
-#### {{ option[0] }}
-
-- Option: `{{ opt.name }}`
-{% if opt.shortcut contains '-' %}
-- Shortcut: `{{ opt.shortcut }}`
-{% endif %}
-- Description: {{ opt.description }}
-{% unless opt.default == nil %}
-  {% if opt.default == false or (opt.default == empty and opt.default != '') %}
-- Default: `{{ opt.default | inspect }}`
-  {% else %}
-- Default: `{{ opt.default }}`
-  {% endif %}
-{% endunless %}
-{% if opt.is_value_required %}
-- Requires a value
-{% elsif opt.accept_value and opt.is_multiple %}
-- Accepts multiple values
-{% elsif opt.accept_value and opt.is_multiple == false %}
-- Accepts a value
-{% else %}
-- Does not accept a value
-{% endif %}
-{% endfor %}
+##### `{{ option[0] }}`
+
+-  Option: `{{ opt.name }}`
+   {% if opt.shortcut contains '-' %}
+-  Shortcut: `{{ opt.shortcut }}`
+   {% endif %}
+-  Description: {{ opt.description }}
+   {% unless opt.default == nil %}
+   {% if opt.default == false or (opt.default == empty and opt.default != '') %}
+-  Default: `{{ opt.default | inspect }}`
+   {% else %}
+-  Default: `{{ opt.default }}`
+   {% endif %}
+   {% endunless %}
+   {% if opt.is_value_required %}
+-  Requires a value
+   {% elsif opt.accept_value and opt.is_multiple %}
+-  Accepts multiple values
+   {% elsif opt.accept_value and opt.is_multiple == false %}
+-  Accepts a value
+   {% else %}
+-  Does not accept a value
+   {% endif %}
+   {% endfor %}
 
 {% endunless %}
 {% endfor %}

common/images/ui_comps/discount_component.png

@@ -157,7 +157,13 @@ For an upgrade, you delete the `config.php` file. Once this file is added to you
 
 ## Verify and upgrade your extensions {#extensions}
 
-If you need to upgrade any third-party extensions and modules that support version 2.2, we recommend working in a new Integration branch with your extensions disabled. Review your third-party extension and module pages in Marketplace or other company sites to verify support for {{site.data.var.ee}} and {{site.data.var.ece}} version 2.2.
+{%
+include note.html
+type='info'
+content='Review your third-party extension and module pages in Marketplace or other company sites to verify support for Magento Commerce and Magento Commerce Cloud version 2.2.
+
+If you need to upgrade any third-party extensions and modules that support version 2.2, we recommend working in a new Integration branch with your extensions disabled.'
+%}
 
 1. Create a new branch on your local workstation.
 

common/images/widget/breadcrumb-list-item-html.png

@@ -353,6 +353,49 @@ See [sensitive and environment settings]({{ page.baseurl }}/extension-dev-guide/
 *   [Sensitive and system-specific configuration paths reference]({{ page.baseurl }}/config-guide/prod/config-reference-sens.html)
 *   [Magento Enterprise B2B Extension configuration paths reference]({{ page.baseurl }}/config-guide/prod/config-reference-b2b.html)
 
+## Get dependency injection configuration information for a class
+
+Use the [dev:di:info]({{ page.baseurl }}/reference/cli/magento.html#devdiinfo) command to retrieve information about dependency injection configuration for a class. The following example retrieves the dependency injection configuration information for the `Magento\Quote\Model\Quote\Item\ToOrderItem` class:
+
+```bash
+bin/magento dev:di:info "Magento\Quote\Model\Quote\Item\ToOrderItem"
+```
+
+```terminal
+DI configuration for the class Magento\Quote\Model\Quote\Item\ToOrderItem in the GLOBAL area
+
+Preference: Magento\Quote\Model\Quote\Item\ToOrderItem
+
+Constructor Parameters:
++-------------------+--------------------------------------------------+------------------+
+| Name              | Requested Type                                   | Configured Value |
++-------------------+--------------------------------------------------+------------------+
+| orderItemFactory  | Magento\Sales\Api\Data\OrderItemInterfaceFactory |                  |
+| objectCopyService | Magento\Framework\DataObject\Copy                |                  |
+| dataObjectHelper  | Magento\Framework\Api\DataObjectHelper           |                  |
++-------------------+--------------------------------------------------+------------------+
+
+
+Plugins:
++-----------------------------------------------------+---------+--------+
+| Plugin                                              | Method  | Type   |
++-----------------------------------------------------+---------+--------+
+| Magento\Catalog\Model\Plugin\QuoteItemProductOption | convert | before |
+| Magento\GiftMessage\Model\Plugin\QuoteItem          | convert | after  |
+| Magento\Bundle\Model\Plugin\QuoteItem               | convert | after  |
++-----------------------------------------------------+---------+--------+
+
+
+Plugins for the Preference:
++-----------------------------------------------------+---------+--------+
+| Plugin                                              | Method  | Type   |
++-----------------------------------------------------+---------+--------+
+| Magento\Catalog\Model\Plugin\QuoteItemProductOption | convert | before |
+| Magento\GiftMessage\Model\Plugin\QuoteItem          | convert | after  |
+| Magento\Bundle\Model\Plugin\QuoteItem               | convert | after  |
++-----------------------------------------------------+---------+--------+
+```
+
 ## Related topics
 
 * [ObjectManager]({{ page.baseurl }}/extension-dev-guide/object-manager.html)

common/images/widget/breadcrumbs-widget-result.png

@@ -21,3 +21,4 @@ Magento 2 is flexible and as a result has varied functionality, so developing a
 * [Routing]({{ page.baseurl }}/extension-dev-guide/routing.html)
 * [Indexing]({{ page.baseurl }}/extension-dev-guide/indexing.html)
 * [Configure a service as a web API]({{ page.baseurl }}/extension-dev-guide/service-contracts/service-to-web-service.html#configure-webapi)
+* [ViewModels]({{ page.baseurl }}/extension-dev-guide/view-models.html)

common/images/widget/loader-widget-result.png

@@ -57,6 +57,44 @@ By applying code before, after, or around a public method, a plugin extends or m
 
 The first argument for the before, after, and around methods is an object that provides access to all public methods of the observed method's class.
 
+### Plugin method naming convention
+
+It is a Magento best practice to capitalize the first letter of the class method name for which you want to create a plugin before adding `before`, `around` or `after` prefixes to it.
+
+For example, to create a plugin for the `setName` method of some class:
+
+```php
+...
+    public function setName($name)
+    {
+        ...
+    }
+...
+```
+
+In the plugin class, the `setName` method may have one of the following names:
+- `beforeSetName`
+- `aroundSetName`
+- `afterSetName`
+
+If the first letter in the name of the class method name for which you want to create a plugin is the `underscore` character, then you do not need to capitalize it in the plugin class.
+
+For example, to create a plugin for the `_construct` method of some class:
+
+```php
+...
+    public function _construct()
+    {
+        ...
+    }
+...
+```
+
+Use the following method names for the `_construct` method in the plugin class:
+- `before_construct`
+- `around_construct`
+- `after_construct`
+
 #### Before methods
 
 Magento runs all before methods ahead of the call to an observed method. These methods must have the same name as the observed method with 'before' as the prefix.

common/images/widget/multiselect-widget-result.png

@@ -0,0 +1,64 @@
+---
+title: View models
+contributor_name: Space 48
+contributor_link: https://www.space48.com/
+group: php-developer-guide
+---
+
+A view model is an abstraction of the view exposing public properties and commands. It allows developers to offload features and business logic from block classes into separate classes that are easier to maintain, test, and reuse.
+
+## When to use view models
+
+Use this approach anytime you need to inject functionality into template files and your code does not need to be backwards compatible with Magento 2.1.
+
+{: .bs-callout-info }
+View models are available in Magento 2.2 onwards. If your code must be compatible with older versions of Magento, consider adding your logic to blocks. For more information about backward compatibility, see [Backward compatibility]({{ page.baseurl }}/contributor-guide/backward-compatible-development/).
+
+## How to write view models
+
+The following example shows how to add functionality to a core template with custom logic using a view model in the `cart/item/default.phtml` template, which is located in the `Magento/Checkout/view/frontend/layout/checkout_cart_item_renderers.xml` file:
+
+```xml
+<?xml version="1.0"?>
+<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
+<body>
+  <referenceBlock name="checkout.cart.item.renderers.default">
+    <arguments>
+      <argument name="viewModel" xsi:type="object">Vendor\CustomModule\ViewModel\MyClass</argument>
+    </arguments>
+  </referenceBlock>
+</body>
+```
+
+You must implement the right interface in your `viewModel` class (for example `ArgumentInterface`):
+
+```php
+namespace Vendor\CustomModule\ViewModel;
+
+class MyClass implements \Magento\Framework\View\Element\Block\ArgumentInterface
+{
+  public function getTitle()
+  {
+    return 'Hello World'
+  {
+}
+```
+
+Finally, in the `cart/item/default.phtml` template, you can access the public methods of your view model:
+
+```html
+<?php
+
+/** @var $viewModel \Vendor\CustomModule\ViewModel\MyClass */
+
+$viewModel = $block->getViewModel();
+
+?>
+<h1><?= $block->escapeHtml($viewModel->getTitle()); ?></h1>
+
+```
+
+## Examples of View models in Magento
+
+- [Magento_Catalog]({{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Catalog/view/frontend/layout/catalog_product_view.xml#L34){:target="_blank"}
+This `viewModel` is used to inject breadcrumb JSON with HTML-escaped names into the template file.