Add documentation for 7 hooks (#52)

docs/manual/developer/_index.en.md

@@ -6,8 +6,4 @@ aliases:
 weight: 70
 ---
 
-{{% notice note %}}
-The developer docs are only available in english.
-{{% /notice %}}
-
 {{% children %}}

docs/manual/developer/hooks/_index.en.md

@@ -6,6 +6,9 @@ weight: 10
 
 Hooks are entry points into the Isotope core (and some of its extension bundles). Have a look at the hook list of all available hooks. You can register your own callable logic that will be executed as soon as a certain point in the execution flow of the core will be reached. 
 
+
+{{%expand "Registering hooks listeners" %}}
+
 ## Registering hooks listeners
 
 There are two ways of registering hook listeners for isotope.
@@ -64,14 +67,15 @@ class AddProductToCollectionListener
     }
 }
 ```
+{{% /expand%}}
 
 ## Reference
 
 This is a list of all hooks available in isotope (as of version 2.8):
 
 - addAssetImportRegexp
 - addCollectionToTemplate
-- addProductToCollection
+- [addProductToCollection](addProductToCollection)
 - applyAdvancedFilters
 - calculatePrice
 - collectionLocked
@@ -90,28 +94,28 @@ This is a list of all hooks available in isotope (as of version 2.8):
 - generateDocumentTemplate
 - generateFilters
 - generateOrderLog
-- generateProduct
+- [generateProduct](generateProduct)
 - generateProductList
 - getAllowedProductIds
 - getOrderConditionsValue
 - getOrderNotificationTokens
 - initializePostsale
 - itemIsAvailable
 - modifyAddressFields
-- postAddProductToCollection
-- postCheckout
+- [postAddProductToCollection](postAddProductToCollection)
+- [postCheckout](postCheckout)
 - postDeleteCollection
 - postDeleteItemFromCollection
 - postOrderStatusUpdate
 - postUpdateItemInCollection
 - postUpdateProductInCollection
-- preCheckout
-- preOrderStatusUpdate
+- [preCheckout](preCheckout)
+- [preOrderStatusUpdate](preOrderStatusUpdate)
 - priceDisplay
 - productIsAvailable
 - saveCollection
 - updateAddressData
 - updateDraftOrder
-- updateItemInCollection
+- [updateItemInCollection](updateItemInCollection)
 - updateProductInCollection
 - useTaxRate

docs/manual/developer/hooks/addProductToCollection/_index.en.md

@@ -0,0 +1,54 @@
+---
+title: "addProductToCollection"
+---
+
+The `addProductToCollection` hook is triggered every time a product is added to the cart.
+It allows manipulating the number of items added to the cart.
+
+## Parameters
+
+1. \Isotope\Interfaces\IsotopeProduct `$product`
+
+    The product that is added to the collection.
+
+2. int `$quantity`
+
+    The quantity of the product that is added to the collection.
+
+3. \Isotope\Interfaces\IsotopeProductCollection `$collection`
+
+    The collection the product is added to.
+
+4. array `$config`
+
+    The model configuration.
+
+## Example
+
+```php
+// src/EventListener/Isotope/AddProductToCollectionListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Interfaces\IsotopeProduct;
+use Isotope\Interfaces\IsotopeProductCollection;
+use Isotope\ServiceAnnotation\IsotopeHook;
+
+/**
+ * @IsotopeHook("addProductToCollection")
+ */
+class AddProductToCollectionListener 
+{
+    public function __invoke(IsotopeProduct $product, int $quantity, IsotopeProductCollection $collection, array $config): int
+    {
+        // example for allowing max 5 items per product
+        if ($quantity > 5) {
+            return 5;
+        }
+        return $quantity
+    }
+}
+```
+
+## References
+
+* [\Isotope\Model\ProductCollection#L1053-L1059](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Model/ProductCollection.php#L1053-L1059)

docs/manual/developer/hooks/generateProduct/_index.en.md

@@ -0,0 +1,41 @@
+---
+title: "generateProduct"
+---
+
+The `generateProduct` hook is called when the product page (reader) is rendered. It allows to add custom information to the product page.
+
+## Parameters
+
+1. \Isotope\Template `$template`
+
+    The template object.
+
+1. \Isotope\Interfaces\IsotopeProduct `$product`
+
+    The product model.
+
+## Example
+
+```php
+// src/EventListener/Isotope/GenerateProductListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Model\Product\AbstractProduct;
+use Isotope\ServiceAnnotation\IsotopeHook;
+use Isotope\Template;
+
+/**
+ * @IsotopeHook("generateProduct")
+ */
+class GenerateProductListener
+{
+    public function __invoke(Template $template, IsotopeProduct $product): void
+    {
+        $template->customMessage = 'We currently have more orders than usual. Please expect longer waiting times.';
+    }
+}
+```
+
+## References
+
+* [\Isotope\Model\Product\Standard#L643-L647](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Model/Product/Standard.php#L643-L647)

docs/manual/developer/hooks/postAddProductToCollection/_index.en.md

@@ -0,0 +1,50 @@
+---
+title: "postAddProductToCollection"
+---
+
+The `postAddProductToCollection` hook is triggered after a product is added to the cart and can be used to perform additional actions.
+
+
+## Parameters
+
+1. \Isotope\Interfaces\IsotopeProduct `$product`
+
+    The product that was added to the collection.
+
+2. int `$quantity`
+
+    The quantity of the product that was added to the collection.
+
+3. \Isotope\Interfaces\IsotopeProductCollection `$collection`
+
+    The collection the product was added to.
+
+4. array `$config`
+
+    The model configuration.
+
+## Example
+
+```php
+// src/EventListener/Isotope/PostAddProductToCollectionListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Interfaces\IsotopeProduct;
+use Isotope\Interfaces\IsotopeProductCollection;
+use Isotope\ServiceAnnotation\IsotopeHook;
+
+/**
+ * @IsotopeHook("postAddProductToCollection")
+ */
+class PostAddProductToCollectionListener 
+{
+    public function __invoke(IsotopeProduct $product, $quantity, IsotopeProductCollection $collection, array $config): void
+    {
+        // Do something …
+    }
+}
+```
+
+## References
+
+* [\Isotope\Model\ProductCollection#L1112-L1118](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Model/ProductCollection.php#L1112-L1118)

docs/manual/developer/hooks/postCheckout/_index.en.md

@@ -0,0 +1,41 @@
+---
+title: "postCheckout"
+---
+
+The `postCheckout` hook is called after the checkout process is finished.
+
+## Parameters
+
+1. \Isotope\Model\ProductCollection\Order `$order`
+
+    The order object.
+
+2. `array $tokens`
+
+    The notification center tokens.
+
+## Example
+
+```php
+// src/EventListener/Isotope/PostCheckoutListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Model\ProductCollection\Order;
+use Isotope\Module\Checkout;
+use Isotope\ServiceAnnotation\IsotopeHook;
+
+/**
+ * @IsotopeHook("postCheckout")
+ */
+class PostCheckoutListener
+{
+    public function __invoke(Order $order, array $tokens): void
+    {
+        // Do something ...
+    }
+}
+```
+
+## References
+
+* [\Isotope\Module\Checkout#L236-L245](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Module/Checkout.php#L236-L245)

docs/manual/developer/hooks/preCheckout/_index.en.md

@@ -0,0 +1,55 @@
+---
+title: "preCheckout"
+---
+
+The `preCheckout` hook is called before the checkout process is started.
+It allows to abort the checkout process.
+
+## Parameters
+
+1. \Isotope\Model\ProductCollection\Order|null `$order`
+
+    The order object.
+
+1. \Isotope\Module\Checkout `$module`
+
+    The checkout module.
+
+## Return Values
+
+The hook must return a boolean value. If `false` is returned, the checkout process is aborted.
+
+## Example
+
+```php
+// src/EventListener/Isotope/PreCheckoutListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Model\ProductCollection\Order;
+use Isotope\Module\Checkout;
+use Isotope\ServiceAnnotation\IsotopeHook;
+
+/**
+ * @IsotopeHook("preCheckout")
+ */
+class PreCheckoutListener
+{
+    public function __invoke(?Order $order, Checkout $module): bool
+    {
+        if (!$order) {
+            return true;
+        }
+
+        if (count($order->getItems()) > 5) {
+            // only allow max 5 articles per order
+            return false;
+        }
+
+        return true;
+    }
+}
+```
+
+## References
+
+* [\Isotope\Model\ProductCollection\Order#L235-L244](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Model/ProductCollection/Order.php#L235-L244)

docs/manual/developer/hooks/preOrderStatusUpdate/_index.en.md

@@ -0,0 +1,54 @@
+---
+title: "preOrderStatusUpdate"
+---
+
+The `preOrderStatusUpdate` hook is called before the order status is updated.
+
+## Parameters
+
+1. \Isotope\Model\ProductCollection\Order `$order` 
+
+   The order model.
+
+2. \Isotope\Model\OrderStatus `$newStatus`
+
+    The new order status.
+
+3. `array $updates`
+
+    The order status updates.
+
+## Return Values
+
+Return `true` to cancel the order status change.
+
+## Example
+
+```php
+// src/EventListener/Isotope/PreOrderStatusUpdateListener.php
+namespace App\EventListener\Isotope;
+
+use Isotope\Model\OrderStatus;
+use Isotope\Model\ProductCollection\Order;
+use Isotope\ServiceAnnotation\IsotopeHook;
+
+/**
+ * @IsotopeHook("preOrderStatusUpdate")
+ */
+class PreOrderStatusUpdateListener
+{
+    public function __invoke(Order $order, OrderStatus $newsStatus, array $updates): bool
+    {
+        // Cancel the order status change if the order is not paid.
+        if (!$order->isPaid()) {
+            return true;
+        }
+
+        return false;
+    }
+}
+```
+
+## References
+
+* [\Isotope\Model\ProductCollection\Order#L308-L318](https://github.com/isotope/core/blob/2.8/system/modules/isotope/library/Isotope/Model/ProductCollection/Order.php##L308-L318)