MAGEDOC-1020. Ready for spell check and final review

Author: Steve Johnson

guides/v2.0/config-guide/cache/cache-priv-cacheable.md

@@ -58,7 +58,5 @@ To specify uncacheable pages, add `cacheable="false"` to the block definition in
 
 [Example]({{ site.mage2000url }}app/code/Magento/Paypal/view/frontend/layout/paypal_payflow_returnurl.xml){:target="_blank"}
 
-{% endhighlight %}
-
 #### Next
 [Public and private content]({{ page.baseurl }}config-guide/cache/cache-priv-priv.html)

guides/v2.0/config-guide/cache/cache-priv-context.md

@@ -19,7 +19,7 @@ Context variables are used by the Magento application to render different conten
 
 Context variables must not be specific to exactly one user, because variables are used in cache keys for public content. In other words, a context variable per user results in a separate copy of content for each user cached on the server.
 
-Magento combines context variables in a string, generates the cache from that string, and sets it as the value of the `X-Magento-Vary` cookie. HTTP proxies can be configured to calculate a unique identifier for cache based on the cookie and URL. For example, [our sample Varnish 4 configuration]({{ site.mage2000url }}app/code/Magento/PageCache/etc/varnish4.vcl){:target="_blank"} uses the following: 
+Magento combines context variables in a string, generates the cache from that string, and sets it as the value of the `X-Magento-Vary` cookie. HTTP proxies can be configured to calculate a unique identifier for cache based on the cookie and URL. For example, [our sample Varnish 4 configuration]({{ site.mage2000url }}app/code/Magento/PageCache/etc/varnish4.vcl#L63-L68){:target="_blank"} uses the following: 
 
 {% highlight xml %}
 sub vcl_hash {

guides/v2.0/config-guide/cache/cache-priv-over.md

@@ -59,8 +59,7 @@ For content to be cacheable, it must meet the following criteria:
 *	Must use only the HTTP [GET or HEAD]({{ page.baseurl }}config-guide/cache/cache-priv-cacheable.html#config-page-cache) request method
 *	Must render only cacheable blocks (which is the default behavior)
 *	Contains no sensitive or private data (in other words, session and customer [Data Transfer Objects (DTO)](https://en.wikipedia.org/wiki/Data_transfer_object){:target="_blank"} objects are empty)
-*	Current session (customer) and pages should be written using JavaScript. For example, a related product listing should exclude items that are already in the shopping cart.
-*	All private content blocks must be marked as private using the [`_isScopePrivate` attribute]({{ page.baseurl }}config-guide/cache/cache-priv-priv.html#config-cache-priv-how)
+*	Implement all customer-specific information using private blocks
 *	Models and blocks should identify themselves for [invalidation support]({{ page.baseurl }}config-guide/cache/cache-priv-inval.html)
 *	To show different public content on the same URL based on custom parameters, you should declare a custom [HTTP context variable]({{ page.baseurl }}config-guide/cache/cache-priv-context.html) if you plan to show different public content on the same URL
 

guides/v2.0/config-guide/cache/cache-priv-priv.md

@@ -28,67 +28,91 @@ Many Magento pages contain personal or sensitive information that should be deli
 	Examples of private content include the wishlist, shopping cart, customer name, and addresses. Private content should be limited to a small portion of the total content on a page.
 
 ## Specify private content {#config-cache-priv-how}
-To specify a block as private, use `$isScopePrivate` as follows:
-
-{% highlight php startinline=true %}
-namespace Magento\Wishlist\Block;
-class Link
-{
-    /**
-     * One way to specify isScopePrivate
-     */
-    protected $_isScopePrivate = true;
- 
-    public function __construct()
-    {
-        /** Another way to do the same thing */
-        $this->_isScopePrivate = true;
-    }
-}
-{% endhighlight %}
+To specify a block as private and have the Magento application render it in browser, do the following:
+
+*   [Step 1: Create a section source](#config-cache-priv-how-source)
+*   [Step 2: Create a block and template](#config-cache-priv-how-block)
+*   [Step 3: Configure a UI component](#config-cache-priv-how-ui) 
+*   [Step 4: Invalidate private content](#config-cache-priv-how-inval)
+
+### Step 1: Create a section source {#config-cache-priv-how-source}
+The section source class is responsible for retrieving data for the section. As a best practice, we recommend you implement your code using the `Vendor/ModuleName/CustomerData` namespace. Your classes must implement the [`Magento\Customer\Model\CustomerData\SectionSourceInterface`]({{ site.mage2000url }}app/code/Magento/Customer/CustomerData/SectionSourceInterface.php){:target="_blank"} interface. 
+
+The public method `getSectionData` must return an associative array with data for private block. 
 
-Magento uses JavaScript to work with private content as follows:
+[Example]({{ site.mage2000url }}app/code/Magento/Catalog/CustomerData/CompareProducts.php#L36-L45){:target="_blank"}
 
-1.  Magento substitutes private content for variables in the HTTP response
-2.  JavaScript collects these variables in the browser and requests private content from the server
-3.  The response with private content is cached in the browser until one of the following happens:
+Add the following to your component's dependency injection configuration (`di.xml`):
 
-	*  The browser sends an HTTP POST request to Magento (for example, to add more items to the cart)
-	*  The user clears their browser's cache
-4.  JavaScript replaces the variables in the HTML with content received from the preceding step
+{% highlight xml %}
+<type name="Magento\Customer\CustomerData\SectionPoolInterface">
+    <arguments>
+        <argument name="sectionSourceMap" xsi:type="array">
+            <item name="compare-products" xsi:type="string">Magento\Catalog\CustomerData\CompareProducts</item>
+        </argument>
+    </arguments>
+</type>
+{% endhighlight %}
 
-Using JavaScript has the following advantages over ESI, which uses an include URL for each piece of private content:
+### Step 2: Create a block and template {#config-cache-priv-how-block}
+To render private content, create a *template* to display user-agnostic information and *blocks* to contain private content.
 
-*   A single AJAX call can fetch all the private user content on a page instead of one request per part of a page to be replaced (as is done with ESI). 
+The user-agnostic data will be replaced with user specific data by the UI component.
 
-    This reduces the number of HTTP requests.
-*   The private content is cacheable by the web browser. 
+<div class="bs-callout bs-callout-info" id="info">
+  <p>Do <em>not</em> use the <code>$_isScopePrivate</code> property in your blocks. This property is obsolete and won't work properly.</p>
+</div>
 
-    A customer’s name is not likely to change for example, so why not keep it in the web browser cache and avoid future AJAX calls?
+Replace private data in blocks with placeholders (using [Knockout JavaScript](http://knockoutjs.com/documentation/introduction.html){:target="_blank"} syntax). The init scope on the root element is `data-bind="scope: 'compareProducts'"`, where you define the scope name (`compareProducts` in this example)in your layout.
 
-Following is an example of JavaScript that displays the customer's full name or a default message if the customer's full name is not known:
+Initialize the component as follows:
 
 {% highlight javascript %}
-  
-<!-- ko if: customer().fullname -->
-<span data-bind="text: new String('Welcome, %1!').replace('%1', customer().firstname)">
-</span>
-<!-- /ko -->
-<!-- ko ifnot: customer().fullname -->
-<span data-bind="html:'Default welcome msg!'"></span>
-<!-- /ko -->
+<script type="text/x-magento-init">
+    {"<css-selector>": {"Magento_Ui/js/core/app": <?php echo $block->getJsLayout();?>}}
+</script>
+{% endhighlight %}
+
+[Example]({{ site.mage2000url }}app/code/Magento/Catalog/view/frontend/templates/product/compare/sidebar.phtml){:target="_blank"}
+
+### Step 3: Configure a UI component {#config-cache-priv-how-ui}
+The UI component renders block data on the Magento storefront. To initialize the UI component, you must call the initialization method `_super()`. [Example]({{ site.mage2000url }}app/code/Magento_Catalog/view/frontend/web/js/view/compare-products.js){:target="_blank"}
+
+All properties are available in the template. 
+
+[Example of defining a UI component in a layout]({{ site.mage2000url }}app/code/Magento/Catalog/view/frontend/layout/default.xml#L11-L22){:target="_blank"}
+
+### Step 4: Invalidate private content {#config-cache-priv-how-inval}
+Specify actions that trigger cache invalidation for private content blocks in a `sections.xml` configuration file in the `Vendor/ModuleName/etc/frontend` directory. Cache is invalidated on a POST or PUT request, such as a customer adding items to a cart.
+
+The following example adds comments to [app/code/Magento/Catalog/etc/frontend/sections.xml]({{ site.mage2000url }}app/code/Magento/Catalog/etc/frontend/sections.xml){:target="_blank"} to show you what happens.
+
+{% highlight xml %}
+<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../../Magento/Customer/etc/sections.xsd">
+ 
+    <!-- will invalidate "compare-products" section, when user perform "catalog/product_compare/add" POST request -->
+    <action name="catalog/product_compare/add">
+        <section name="compare-products"/>
+    </action>
+    
+    <!-- will invalidate all sections -->
+    <action name="customer/account/logout"/>
+ 
+    <!-- will invalidate section for each POST request  -->
+    <action name="*">
+        <section name="message"/>
+    </action>
+ 
+</config>
 {% endhighlight %}
 
 <div class="bs-callout bs-callout-info" id="info">
   <ul><li>Use only HTTP <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5" target="_blank">POST</a> or <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6" target="_blank">PUT</a> methods to change state (for example, adding to a shopping cart, adding to a wishlist, and so on.) POST and PUT requests are <em>not</em> cached.</li>
-  	<li>Only HTTP <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3" target="_blank">GET</a> and <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.4" target="_blank">HEAD</a> requests are cacheable.</li>
-  	<li>For more information about caching, see <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html" target="_blank">RFC-2616 section 13</a>.</li>
+    <li>Only HTTP <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.3" target="_blank">GET</a> and <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.4" target="_blank">HEAD</a> requests are cacheable.</li>
+    <li>For more information about caching, see <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html" target="_blank">RFC-2616 section 13</a>.</li>
 
   </ul>
 </div>
 
-## Considerations for public content {#config-cache-public}
-@@@
-
 #### Next
 [HTTP context]({{ page.baseurl }}config-guide/cache/cache-priv-context.html)