From 52f390118e520962c002f3efedbb052e1096c19c Mon Sep 17 00:00:00 2001
From: Lukas Gaechter <lukas.gaechter@mind.ch>
Date: Thu, 12 Jan 2023 21:25:26 +0100
Subject: [PATCH] Update documentation

---
 docs/mini-cart.md | 61 ++++++++++++++++++-----------------------------
 docs/usage.md     | 53 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 38 deletions(-)

diff --git a/docs/mini-cart.md b/docs/mini-cart.md
index f8e7bc4..c290ace 100644
--- a/docs/mini-cart.md
+++ b/docs/mini-cart.md
@@ -6,47 +6,32 @@ menu:
     parent: "woocommerce"
 ---
 
-If you want to display a "mini cart", sometimes also called "card fragments", that displays the cart contents count and total price, you can [use the `woocommerce_add_to_cart_fragments`](https://docs.woocommerce.com/document/show-cart-contents-total/) hook. Here’s a class you can use:
+If you want to display a "mini cart", sometimes also called "card fragments", that displays the cart contents count and total price, you can [use the `woocommerce_add_to_cart_fragments`](https://docs.woocommerce.com/document/show-cart-contents-total/) hook.
 
-```php
-<?php
-
-use Timber\Timber;
-
-class ThemeMiniCart {
-    /**
-     * Init hooks.
-     */
-    public function init() {
-        add_filter( 'woocommerce_add_to_cart_fragments', [ $this, 'cart_link_fragment' ] );
-    }
-
-    /**
-     * Cart Fragments.
-     *
-     * Ensure cart contents update when products are added to the cart via AJAX.
-     *
-     * @param  array $fragments Fragments to refresh via AJAX.
-     * @return array            Fragments to refresh via AJAX.
-     */
-    public function cart_link_fragment( $fragments ) {
-        $fragments['a.cart-mini-contents'] = Timber::compile(
-            'woocommerce/cart/fragment-link.twig',
-            [ 'cart' => WC()->cart ]
-        );
-
-        return $fragments;
-    }
-}
-```
-
-Don’t forget to require and initialize it in your **functions.php** file:
+**functions.php
 
 ```php
-( new Theme_Mini_Cart() )->init();
+add_filter( 'woocommerce_add_to_cart_fragments', 'cart_link_fragment' );
+
+/**
+ * Cart Fragments.
+ *
+ * Ensure cart contents update when products are added to the cart via AJAX.
+ *
+ * @param  array $fragments Fragments to refresh via AJAX.
+ * @return array            Fragments to refresh via AJAX.
+ */
+function cart_link_fragment( $fragments ) {
+    $fragments['a.cart-mini-contents'] = Timber::compile(
+        'woocommerce/cart/fragment-link.twig',
+        [ 'cart' => WC()->cart ]
+    );
+
+    return $fragments;
+}
 ```
 
-In the `cart_link_fragment` method, you can see that we compile a Twig template, that looks like this:
+In the `cart_link_fragment()` function, you can see that we compile a Twig template, that looks like this:
 
 **views/woocommerce/cart/fragment-link.twig**
 
@@ -61,12 +46,12 @@ In the `cart_link_fragment` method, you can see that we compile a Twig template,
 </a>
 ```
 
-See that the link with the class `cart-mini-contents` is added to the `$fragments` global in the `cart_link_fragment` method? That will be a JavaScript selector that updates the contents in the link through AJAX. WooCommerce needs to know the HTML to update the cart with. We can make use of `Timber::compile()` to use the same Twig template that we also use to display the cart fragment in our theme.
+See that the link with the class `cart-mini-contents` is added to the `$fragments` global in the `cart_link_fragment()` function? That will be a JavaScript selector that updates the contents in the link through AJAX. WooCommerce needs to know the HTML to update the cart with. We can make use of `Timber::compile()` to use the same Twig template that we also use to display the cart fragment in our theme.
 
 So, to display the mini cart in your theme – for example in your header – you can include it as follows:
 
 **Twig**
 
 ```Twig
-{% include 'woocommerce/cart/fragment-link.twig' %}
+{{ include('woocommerce/cart/fragment-link.twig') }}
 ```
diff --git a/docs/usage.md b/docs/usage.md
index 1ef5717..81287d9 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -232,6 +232,59 @@ It’s up to you then, whether you want to create a `loop/loop-start.twig` and `
 </div>
 ```
 
+## Working with Post Collections
+
+If you have a collection of product posts that you want to convert to Timber posts, you can use `Timber::get_posts()`. Timber will automatically return `Timber\Integration\WooCommerce\Product` posts.
+
+Then, you will have to wrap your posts in a `Timber\PostCollection`. That will make sure that the correct `$product` global will be set up when you loop over your posts. (If you don’t do this, you will run into errors where the permalink or the price of all products in a loop will be the same.)
+
+Here’s an example where we get the featured products and convert them to a collection you can use.
+
+```php
+use Timber\PostCollection;
+
+$posts = Timber::get_posts( wc_get_featured_product_ids() );
+$posts = new PostCollection( $posts );
+```
+
+You could use this to display the posts on a page.
+
+**page.php**
+
+```php
+<?php
+
+use Timber\PostCollection;
+
+$context = Timber::get_context();
+
+$context['featured_products'] = new PostCollection(
+    Timber::get_posts( wc_get_featured_product_ids() )
+);
+
+Timber::render( 'page.twig', $context );
+```
+
+**page.twig**
+
+```twig
+{{ include('woocommerce/products.twig', {
+    posts: featured_products
+}) }}
+```
+
+**woocommerce/products.twig**
+
+```twig
+{{ fn('woocommerce_product_loop_start') }}
+
+{% for post in posts %}
+    {{ fn('wc_get_template_part', 'content', 'product' ) }}
+{% endfor %}
+
+{{ fn('woocommerce_product_loop_end') }}
+```
+
 ## Filter posts from Twig
 
 Normally when working with Timber, you’d want to filter post data before you pass it to a Twig template. With WooCommerce, this is maybe a little more complicated. You could write your own **woocommerce.php** that handles all the data. But remember, we want to interfere with WooCommerce as little as possible.