Merge branch 'master' into event-observers-warning-about-unique-name

Author: shrielenee

src/_includes/config/install-java8.md

@@ -30,16 +30,12 @@ Java version 8 might not be available for all operating systems. For example, yo
 
 To install JDK 1.8 on Ubuntu, enter the following commands as a user with `root` privileges:
 
-```bash
-add-apt-repository -y ppa:webupd8team/java
-```
-
 ```bash
 apt-get -y update
 ```
 
 ```bash
-apt-get install -y oracle-java8-installer
+apt-get install -y openjdk-8-jdk
 ```
 
 For other options, see [Oracle documentation](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html).

src/cloud/docker/docker-config.md

@@ -97,7 +97,7 @@ You can run composer using the `docker` command before you create the container
 When you run composer with Docker commands, you must use the [Docker Hub PHP Image Tag] that matches the Magento application version. The following example uses PHP 7.3. You run this command from the project root directory.
 
 ```bash
-docker run -it  -v $(pwd):/app/ -v ~/.composer/:/root/.composer/ magento/magento-cloud-docker-php:7.3-cli-1.1 bash -c "composer install&&chown www. /app/"
+docker run -it  -v $(pwd):/app/:delegated -v ~/.composer/:/root/.composer/:delegated magento/magento-cloud-docker-php:7.3-cli-1.1 bash -c "composer install&&chown www. /app/"
 ```
 
 This command passes in the current working directory as `/app/`, includes composer from `~/.composer/`, and runs the `composer install` command in the container. After this set up, the command  fixes the permissions on the files that have been added or changed.

src/cloud/project/log-locations.md

@@ -13,7 +13,7 @@ Logs are useful for troubleshooting problems related to {{site.data.var.ece}} [b
 Magento-specific logs are in the `<magento-root-dir>/var/` directory. See [Magento Logging][configlog] in the _Configuration guide_.
 
 {:.bs-callout-tip}
-You can [set up log-based Slack and email notifications][slacklog] when configuring your Cloud environment.
+When you configure your Cloud environment, you can [set up log-based Slack and email notifications][slacklog] for build and deploy actions.
 
 ## Viewing logs
 

src/cloud/project/project-upgrade.md

@@ -6,25 +6,25 @@ functional_areas:
   - Upgrade
 ---
 
-You can upgrade the core {{site.data.var.ee}} code base to a newer version. It is best to review the summary of the updated [technology stack] before upgrading your project. If you need to upgrade from a version older than 2.1, you must upgrade to a supported version first. See [Upgrades and patches] for upgrade path details.
+You can upgrade the core {{site.data.var.ee}} code base to a newer version. Before upgrading your project, review the [{{site.data.var.ece}} service versions][version compatibility matrix] information for the latest software version requirements. If you need to upgrade from a version older than 2.1, you must upgrade to a supported version first. See [Upgrades and patches] for upgrade path details.
 
 {% include cloud/note-upgrade.md %}
 
 {% include cloud/note-ece-tools-package.md %}
 
-## Upgrading from older versions of the Magento application
+## Upgrade from older versions of the Magento application
 
-If you are upgrading from 2.1.4 or later to 2.2.x or later, review the [Magento technology stack requirements]. Your upgrade tasks may include the following:
+If you are upgrading from 2.1.4 or later to 2.2.x or later, review the [{{site.data.var.ece}} service versions][version compatibility matrix] information for the latest software version requirements. Your upgrade tasks may include the following:
 
 -  Upgrade your PHP version
 -  Convert an older configuration management file
 -  Update the `.magento.app.yaml` file with new settings for hooks and environment variables
--  Upgrade to the latest supported version of Fastly
+-  Upgrade third-party extensions to the latest supported version
 -  Update the `.gitignore` file
 
 ### Configuration management
 
-If you are upgrading from 2.1.4 or later to 2.2.x or later and use [Configuration Management], you need to migrate the `config.local.php` file. Older versions used a `config.local.php` file for Configuration Management, but version 2.2.0 and later use the `config.php` file. This file works exactly as the `config.local.php` file, with additional settings that include a list of your enabled modules, additional configurations, and a different name.
+If you are upgrading from 2.1.4 or later to 2.2.x or later and use [Configuration Management], you need to migrate the `config.local.php` file. Older versions used a `config.local.php` file for Configuration Management, but version 2.2.0 and later use the `config.php` file. This file works exactly like the `config.local.php` file, but it has different configuration settings that include a list of your enabled modules and additional configuration options.
 
 {:.procedure}
 To create a temporary `config.php` file:
@@ -86,9 +86,9 @@ To update the `.magento.app.yaml` file:
 
 1. Continue with the upgrade process.
 
-## Upgrading the Magento application
+## Upgrade the Magento application
 
-Review the [Magento technology stack requirements] before upgrading your Magento application.
+Review the [service versions][version compatibility matrix] information for the latest software version requirements before upgrading your Magento application.
 
 ### Back up the database
 
@@ -173,7 +173,7 @@ To create a system-specific configuration file:
 {:.bs-callout-warning}
 For an upgrade, you delete the `config.php` file. Once this file is added to your code, you should **not** delete it. If you need to remove or edit settings, you must edit the file manually.
 
-### Upgrading extensions
+### Upgrade extensions
 
 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}}. If you need to upgrade any third-party extensions and modules, we recommend working in a new Integration branch with your extensions disabled.
 
@@ -197,7 +197,9 @@ To verify and upgrade your extensions:
 1. Push to the Staging environment to test in a pre-production environment.
 
 We strongly recommend upgrading your Production environment _before_ including the upgraded extensions in your go-live process.
-We also recommend upgrading to the latest version of the Fastly CDN module for Magento 2.
+
+{:.bs-callout-info}
+When you upgrade your Magento version, the upgrade process updates to the latest version of the [Fastly CDN module for Magento 2] automatically.
 
 ## Troubleshoot upgrade
 
@@ -222,11 +224,11 @@ To resolve the error:
    git add -A && git commit -m "Fixed deployment failure" && git push magento <branch-name>
    ```
 
-[technology stack]: {{site.baseurl}}/guides/v2.3/install-gde/system-requirements-tech.html
+[version compatibility matrix]: {{site.baseurl}}/cloud/project/project-conf-files_services.html#service-versions
 [Upgrades and patches]: {{site.baseurl}}/cloud/project/project-upgrade-parent.html
-[Magento technology stack requirements]: {{site.baseurl}}/guides/v2.3/install-gde/system-requirements-tech.html
 [Configuration Management]: {{site.baseurl}}/cloud/live/sens-data-over.html
 [extensions section of the .magento.app.yaml file]: {{site.baseurl}}/cloud/project/project-conf-files_magento-app.html#configure-php-options
 [.magento.app.yaml]: {{site.baseurl}}/cloud/project/project-conf-files_magento-app.html
 [version constraint syntax]: {{site.baseurl}}/cloud/project/ece-tools-upgrade-project.html#metapackage
+[Fastly CDN module for Magento 2]: {{site.baseurl}}/cloud/cdn/cloud-fastly.html#fastly-cdn-module-for-magento-2
 [Examine the logs]: {{site.baseurl}}/cloud/project/log-locations.html

src/cloud/requirements/cloud-requirements.md

@@ -62,7 +62,7 @@ You cannot upgrade the software, but you can configure the following services:
 *  [Elasticsearch]({{ site.baseurl }}/cloud/project/project-conf-files_services-elastic.html)
 
  {:.bs-callout-info}
-See [Magento technology stack requirements]({{ site.baseurl }}/guides/v2.3/install-gde/system-requirements-tech.html) for the latest software version requirements.
+See the [{{site.data.var.ece}} service versions][version compatibility matrix] information for the latest software version requirements.
 
 For Staging and Production environments, you use the Fastly CDN module for Magento 2 for CDN and caching services. See [Configure Fastly services]({{ site.baseurl }}/cloud/cdn/cloud-fastly.html#fastly-cdn-module-for-magento-2).
 
@@ -133,3 +133,6 @@ Your {{site.data.var.ee}} account must *authenticate* using any of the following
 *  Bitbucket
 *  Google
 *  Create your own Cloud account
+
+<!--link definitions-->
+[version compatibility matrix]: {{site.baseurl}}/cloud/project/project-conf-files_services.html#service-versions

src/common/images/body-class-result.png

@@ -5,9 +5,9 @@ contributor_name: Ziffity
 contributor_link: https://www.Ziffity.com/
 ---
 
-Access Control List (ACL) rules allow an admin to limit the permissions of users in Magento. For example, you can use ACL rules to authorize the users to access menus, controllers, and API endpoints.
+Access Control List (ACL) rules allow an admin to limit the permissions of users in Magento. For example, you can use ACL rules to authorize the users to access menus, controllers, API endpoints and conditionally render [layout](https://glossary.magento.com/layout) [blocks](https://glossary.magento.com/block).
 
-In this tutorial, we are creating three custom resources (Custom Menu, Create, Delete), then creating a role that has access to these resources, and taking steps to restrict access by three entities (Admin users, controllers, and web APIs).
+In this tutorial, we are creating four custom resources (Custom Menu, Create, Delete, View), then creating a role that has access to these resources, and taking steps to restrict access by four entities (Admin users, controllers, web APIs and layout block).
 
 ## Step 1. Define the custom resources
 
@@ -20,8 +20,11 @@ In this tutorial, we are creating three custom resources (Custom Menu, Create, D
         <resources>
            <resource id="Magento_Backend::admin">
               <resource id="Vendor_MyModule::menu" title="Custom Menu" sortOrder="10" >
-                 <resource id="Vendor_MyModule::create" title="Create" sortOrder="0" />
+                 <resource id="Vendor_MyModule::create" title="Create" sortOrder="50" />
                  <resource id="Vendor_MyModule::delete" title="Delete" sortOrder="100" />
+                 <resource id="Vendor_MyModule::view" title="View" sortOrder="150">
+                    <resource id="Vendor_MyModule::view_additional" title="View Additional Information" sortOrder="10" />
+                 </resource>
               </resource>
            </resource>
         </resources>
@@ -31,9 +34,9 @@ In this tutorial, we are creating three custom resources (Custom Menu, Create, D
 
    | Attribute | Description |
    | --------- | ----------- |
-   | `id` | Unique string and should be in this format: `Vendor_ModuleName::resourceName` |
-   | `title` | Title which is display on menu bar |
-   | `sortOrder` | Position in which menu to be disaplay |
+   | `id` | Unique string. Should be in the format `Vendor_ModuleName::resourceName` |
+   | `title` | Title which is displayed in the menu bar |
+   | `sortOrder` | Position in which menu is displayed |
 
 1. Clean the cache by clicking **System** > **Cache Management** > **Flush Magento Cache** or by entering the following command:
 
@@ -66,19 +69,20 @@ In your module, create the `etc/adminhtml/menu.xml` file. This file defines a me
      <add id="Vendor_MyModule::menu" title="Custom Menu" module="Vendor_MyModule" sortOrder="10" resource="Vendor_MyModule::menu"/>
      <add id="Vendor_MyModule::create" title="Create" module="Vendor_MyModule" sortOrder="10" parent="Vendor_MyModule::menu" action="custommenu/create/index" resource="Vendor_MyModule::create"/>
      <add id="Vendor_MyModule::delete" title="Delete" module="Vendor_MyModule" sortOrder="20" parent="Vendor_MyModule::menu" action="custommenu/delete/index" resource="Vendor_MyModule::delete"/>
+     <add id="Vendor_MyModule::view" title="View" module="Vendor_MyModule" sortOrder="30" parent="Vendor_MyModule::menu" action="custommenu/view/index" resource="Vendor_MyModule::view"/>
     </menu>
 </config>
 ```
 
 | Attribute | Description |
 | --------- | ----------- |
-| `id` | Unique string and should be in this format: `Vendor_ModuleName::resourceName` |
-| `title` | Title which is display on menu bar|
+| `id` | Unique string. Should be in the format: `Vendor_ModuleName::resourceName` |
+| `title` | Title which is displayed in menu bar|
 | `module` | Module which containing the current menu |
-| `sortOrder` | Position in which menu to be disaplay |
+| `sortOrder` | Position in which menu to be displayed |
 | `parent` | The another menu which is parent of current menu |
-| `action` | Url of the page which needs to be display after click the menu. It should be in following format: `front_name/controller_path/action` |
-| `resource` | To restrict using ACL rule |
+| `action` | Url of the page which needs to be displayed after clicking the menu. It should be in following format: `front_name/controller_path/action` |
+| `resource` | ACL rule to restrict the access |
 
 Clean the cache by clicking **System** > **Cache Management** > **Flush Magento Cache** or by entering the following command:
 
@@ -88,7 +92,7 @@ bin/magento cache:clean
 
 The menu displays as follows:
 
-![custom menu]({{ site.baseurl }}/common/images/ext-best-practices/custom_menu.png)
+![custom menu]({{ site.baseurl }}/common/images/ext-best-practices/custom_menu.jpg)
 
 ### Restrict admin controllers
 
@@ -112,7 +116,54 @@ protected function _isAllowed()
 }
 ```
 
-If the user doesn't have permission, the action page displays an "Access Denied" message.
+If the user does not have permission, the action page displays an "Access Denied" message.
+
+### Content restrictions for admin users
+
+With the ACL it is also possible to [render layout blocks dynamically]({{ page.baseurl }}/frontend-dev-guide/layouts/xml-manage.html#ref_config_block) on the page.
+
+It is enough to set the block's value for `aclResource` attribute:
+
+```xml
+<block class="Vendor\MyModule\Block\Adminhtml\Type" name="block.example" aclResource="Vendor_MyModule::view_additional">
+    <!-- ... -->
+</block>
+```
+
+The `view/adminhtml/layout/custommenu_view_index.xml` example file below contains two blocks that display information to the end-user, one of which is accessible only to users with ACL `Vendor_MyModule::view_additional` permissions.
+
+```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">
+    <referenceBlock name="page.title">
+        <action method="setPageTitle">
+            <argument name="title" xsi:type="string">View</argument>
+        </action>
+    </referenceBlock>
+    <body>
+        <referenceContainer name="content">
+            <block class="Magento\Framework\View\Element\Text">
+                <arguments>
+                    <argument name="text" xsi:type="string">Page Content </argument>
+                </arguments>
+            </block>
+            <block class="Magento\Framework\View\Element\Text" aclResource="Vendor_Module::view_additional">
+                <arguments>
+                    <argument name="text" xsi:type="string"> - additional</argument>
+                </arguments>
+            </block>
+        </referenceContainer>
+    </body>
+</page>
+```
+
+When the ACL resource for `Vendor_ModuleName::view_additional` is enabled, the result is:
+
+![admin page full content]({{ site.baseurl }}/common/images/ext-best-practices/acl-admin-page-content-full-access.jpg)
+
+When the ACL resource is disabled, the content on the page differs:
+
+![admin page content limited]({{ site.baseurl }}/common/images/ext-best-practices/acl-admin-limited-page-content.jpg)
 
 ## Step 3. Restrict web API access
 
@@ -136,3 +187,5 @@ We can restrict users from accessing API endpoints by using the ACL rule. By cre
 *  [Creating a Magento admin page]({{ page.baseurl }}/ext-best-practices/extension-coding/example-module-adminpage.html)
 
 *  [Authentication]({{ page.baseurl }}/get-started/authentication/gs-authentication.html)
+
+*  [Layout block dynamic visibility using ACL Resource]({{ page.baseurl }}/frontend-dev-guide/layouts/xml-manage.html#ref_config_block)

src/common/images/ext-best-practices/acl-admin-limited-page-content.jpg

@@ -23,7 +23,7 @@ Following are some common module directories:
 *  `etc`: contains configuration files; in particular, `module.xml`, which is required.
 *  `Model`: contains PHP model classes as part of MVC vertical implementation of module logic.
 *  `Setup`: contains classes for module database structure and data setup which are invoked when installing or upgrading.
-*  `ViewModel`: contains PHP model clasees as part of a model-view-viewmodel (MVVM) implementation. It allows developers to offload features and business logic from block classes into separate classes that are easier to maintain, test, and reuse.
+*  `ViewModel`: contains PHP model classes as part of a model-view-viewmodel (MVVM) implementation. It allows developers to offload features and business logic from block classes into separate classes that are easier to maintain, test, and reuse.
 
 #### Additional directories
 {:.no_toc}

src/common/images/ext-best-practices/acl-admin-page-content-full-access.jpg

@@ -109,7 +109,7 @@ To extend a Module's styles in your theme:
    │   ├── web/
    │   │   ├── css/
    │   │   │   ├── source/
-               ├──_extend.less
+                  ├──_extend.less
    ...
    ```
 

src/common/images/ext-best-practices/custom_menu.jpg

@@ -182,6 +182,8 @@ The following table describes the instructions specific for page configuration f
           <li><code>&lt;css&gt;</code></li>
           <li><code>&lt;font&gt;</code></li>
           <li><code>&lt;script&gt;</code></li>
+          <li><code>&lt;remove&gt;</code></li>
+          <li><code>&lt;attribute&gt;</code></li>
         </ul>
       </td>
       <td colspan="1" />

src/common/images/ext-best-practices/custom_menu.png

@@ -229,13 +229,13 @@ To set attributes for the HTML `body` tag use the `<attribute>` instruction.
 **Example:** Add a new class to the `body` tag.
 
 ```xml
-<page>
     <body>
         <attribute name="class" value="my-new-body-class"/>
     </body>
-</page>
 ```
 
+![Block Class]({{ site.baseurl }}/common/images/body-class-result.png)
+
 **Example:** Add a custom attribute to the `body` tag.
 
 ```xml

src/guides/v2.3/ext-best-practices/tutorials/create-access-control-list-rule.md

@@ -221,32 +221,6 @@ Syntax option | Description
 `@doc(description)` | Describes the purpose of the mutation
 `@deprecated(reason: "description")` | Use `@deprecated` to mark a query, mutation, or attribute as deprecated
 
-{:.bs-callout-tip}
-It is a good practice to define separate types for input and output data. This practice permits additional extension points, so every input and output type can be extended by adding additional fields to the definition.
-
-#### Example
-
-**Wrong approach:**
-
-```text
-type Mutation {
-    mutationQueryName(param1: String, param2: Int, ...): MutationQueryOutput @resolver(class: "Magento\\<module_name>\\Model\\Resolver\\MutationResolverModel") @doc(description:"Mutation query description")
-}
-```
-
-**Correct approach:**
-
-```text
-type Mutation {
-    mutationQueryName(inputParam: InputParamsType): MutationQueryOutput @resolver(class: "Magento\\<module_name>\\Model\\Resolver\\MutationResolverModel") @doc(description:"Mutation query description")
-}
-
-type InputParamsType {
-    param1: String
-    param2: Int
-}
-```
-
 ### Resolver class
 
 Use the following sample code as a template for the GraphQL resolver mutation class:

src/guides/v2.3/extension-dev-guide/build/module-file-structure.md

@@ -89,7 +89,7 @@ The `AddConfigurableProductsToCartInput` object contains the following attribute
 
 Attribute | Type | Description
 --- | --- | ---
-`cart_id` | String | The unique ID that identifies the customer's cart
+`cart_id` | String! | The unique ID that identifies the customer's cart
 `cart_items` | [[ConfigurableProductCartItemInput]](#configProdCartItemInput) | An array of configurable items to add to the cart
 
 ### ConfigurableProductCartItemInput object {#configProdCartItemInput}