Banner options, Native lazy loading

- added ability to provide custom options for each banner through Renderer or Latte macro
- added support for native lazy loading
- updated default templates due to implementation of custom banner options and native lazy loading
- added and fixed tests
- updated docs
- updated CHANGELOG

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 1.0.0 - 2023-12-01
+### Added
+- Added ability to provide custom options for each banner through Renderer or Latte macro.
+- Added support for native lazy loading. Feature can be enabled through banner options `'loading' => 'lazy'` and `'loading-offset' => <offset>` (for multiple positions only).
+
+### Changed
+- Updated default templates due to implementation of custom banner options and native lazy loading.
+- Updated docs.
+
 ## 1.0.0 - 2023-11-30
 ### Added
 

docs/integration-with-nette-framework.md

@@ -116,8 +116,16 @@ extensions:
 Now the macro `{banner}` is available in the application and can be used in templates:
 
 ```latte
+{*
+    Available arguments are:
+    * `resources` - An array of banner resources,
+    * `options` - An array of custom options. Can be also used for enabling native lazy loading.
+    * `attributes` - An array of HTML attributes
+    * `mode` - Allows to switch a rendering mode. See the "Using multiple rendering modes" section below
+*}
+
 {banner homepage.top}
-{banner homepage.promo, resources: ['role' => 'guest']}
+{banner homepage.promo, resources: ['role' => 'guest'], options: ['loading' => 'lazy']}
 {banner homepage.bottom, attributes: ['class' => 'my-awesome-class']}
 ```
 

docs/integration-without-framework.md

@@ -10,6 +10,7 @@
 * [Fetching banners](#fetching-banners)
 * [Rendering banners](#rendering-banners)
   * [Rendering banners on the client side](#rendering-banners-on-the-client-side)
+  * [Lazy loading of image banners](#lazy-loading-of-image-banners)
   * [Templates overwriting](#templates-overwriting)
   * [Rendering banners using Latte](#rendering-banners-using-latte)
 * [Latte templating system integration](#latte-templating-system-integration)
@@ -165,7 +166,14 @@ echo $renderer->render($response->getPosition('homepage.top'));
 The second argument can be used to pass an array of attributes to be contained in the banner's HTML wrapper element.
 
 ```php
-echo $renderer->render($response->getPosition('homepage.top', ['class' => 'my-awesome-class']));
+echo $renderer->render($response->getPosition('homepage.top'), ['class' => 'my-awesome-class']);
+```
+
+The third argument can be used to provide custom options.
+These options are available in the banner templates and will also be available to the JavaScript client, so they can be accessed in event handlers.
+
+```php
+echo $renderer->render($response->getPosition('homepage.top'), [], ['customOption' => 'customValue']);
 ```
 
 ### Rendering banners on the client side
@@ -184,6 +192,42 @@ echo $renderer->renderClientSide(new Position('homepage.promo'), ['class' => 'my
 
 Banners rendered in this way will be loaded by the JavaScript client when its `attachBanners()` function is called.
 
+### Lazy loading of image banners
+
+The default client templates support [native lazy loading](https://developer.mozilla.org/en-US/docs/Web/Performance/Lazy_loading#images_and_iframes) of images.
+To activate lazy loading the option `'loading' => 'lazy'` must be passed to the renderer.
+
+```php
+# server-side rendering:
+echo $renderer->render($response->getPosition('homepage.top'), [], [
+    'loading' => 'lazy',
+]);
+
+# client-side rendering:
+echo $renderer->renderClientSide(new Position('homepage.top'), [], [
+    'loading' => 'lazy',
+]);
+```
+
+A special case is a position of type `multiple`, where it may be desirable to lazily load all banners except the first.
+This can be achieved by adding the option `loading-offset`, whose value specifies from which banner the attribute `loading` should be rendered.
+
+```php
+# server-side rendering:
+echo $renderer->render($response->getPosition('homepage.top'), [], [
+    'loading' => 'lazy',
+    'loading-offset' => 1,
+]);
+
+# client-side rendering:
+echo $renderer->renderClientSide(new Position('homepage.top'), [], [
+    'loading' => 'lazy',
+    'loading-offset' => 1,
+]);
+```
+
+If you prefer a different implementation of lazy loading, it is possible to use own templates instead of the default ones and integrate a different solution in these templates.
+
 ### Templates overwriting
 
 The default templates are written as `.phtml` templates and can be found [here](../src/Renderer/Phtml/Templates). Templates can be also overwritten:
@@ -211,7 +255,7 @@ new Templates([
     Templates::Multiple => '/multiple.phtml', # for positions with the display type "multiple"
     Templates::Random => '/random.phtml', # for positions with the display type "random"
     Templates::NotFound => '/notFound.phtml',  # for positions that were not found
-    Templates::ClientSide => '/clientSide.phtml',
+    Templates::ClientSide => '/clientSide.phtml', # for positions that should be rendered by JS client
 ])
 ```
 
@@ -276,8 +320,16 @@ $engine->render(__DIR__ . '/template.latte');
 ```latte
 {* ./template.latte *}
 
+{*
+    Available arguments are:
+    * `resources` - An array of banner resources,
+    * `options` - An array of custom options. Can be also used for enabling native lazy loading.
+    * `attributes` - An array of HTML attributes
+    * `mode` - Allows to switch a rendering mode. See the "Using multiple rendering modes" section below
+*}
+
 {banner homepage.top}
-{banner homepage.promo, resources: ['role' => 'guest']}
+{banner homepage.promo, resources: ['role' => 'guest'], options: ['loading' => 'lazy']}
 {banner homepage.bottom, attributes: ['class' => 'my-awesome-class']}
 ```
 

src/Bridge/Latte/RendererProvider.php

@@ -37,6 +37,7 @@ final class RendererProvider
     private const OptionResources = 'resources';
     private const OptionAttributes = 'attributes';
     private const OptionMode = 'mode';
+    private const OptionOptions = 'options';
 
     private AmpClientInterface $client;
 
@@ -279,8 +280,9 @@ private function renderPosition(ResponsePosition $position, array $options): str
     {
         try {
             $elementAttributes = (array) ($options[self::OptionAttributes] ?? []);
+            $bannerOptions = (array) ($options[self::OptionOptions] ?? []);
 
-            return $this->renderer->render($position, $elementAttributes);
+            return $this->renderer->render($position, $elementAttributes, $bannerOptions);
         } catch (RendererException $e) {
             if ($this->debugMode) {
                 throw $e;
@@ -303,8 +305,9 @@ private function renderClientSidePosition(RequestPosition $position, array $opti
     {
         try {
             $elementAttributes = (array) ($options[self::OptionAttributes] ?? []);
+            $bannerOptions = (array) ($options[self::OptionOptions] ?? []);
 
-            return $this->renderer->renderClientSide($position, $elementAttributes);
+            return $this->renderer->renderClientSide($position, $elementAttributes, $bannerOptions);
         } catch (RendererException $e) {
             if ($this->debugMode) {
                 throw $e;

src/Renderer/Latte/Helpers.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SixtyEightPublishers\AmpClient\Renderer\Latte;
+
+use SixtyEightPublishers\AmpClient\Request\ValueObject\Position as RequestPosition;
+
+final class Helpers
+{
+    private function __construct() {}
+
+    /**
+     * @return array<string, string>
+     */
+    public static function createResourceAttributes(RequestPosition $position): array
+    {
+        $attributes = [];
+
+        foreach ($position->getResources() as $resource) {
+            $attributes['data-amp-resource-' . $resource->getCode()] = implode(',', $resource->getValues());
+        }
+
+        return $attributes;
+    }
+
+    /**
+     * @param array<string, scalar> $options
+     *
+     * @return array<string, scalar>
+     */
+    public static function createOptionAttributes(array $options): array
+    {
+        $attributes = [];
+
+        foreach ($options as $name => $value) {
+            $attributes['data-amp-option-' . $name] = $value;
+        }
+
+        return $attributes;
+    }
+}

src/Renderer/Latte/LatteRendererBridge.php

@@ -15,7 +15,6 @@
 use SixtyEightPublishers\AmpClient\Request\ValueObject\Position as RequestPosition;
 use SixtyEightPublishers\AmpClient\Response\ValueObject\Banner;
 use SixtyEightPublishers\AmpClient\Response\ValueObject\Position as ResponsePosition;
-use function implode;
 
 final class LatteRendererBridge implements RendererBridgeInterface
 {
@@ -52,49 +51,43 @@ public function overrideTemplates(Templates $templates): self
         return $renderer;
     }
 
-    public function renderNotFound(ResponsePosition $position, array $elementAttributes = []): string
+    public function renderNotFound(ResponsePosition $position, array $elementAttributes = [], array $options = []): string
     {
         return $this->getLatte()->renderToString(
             $this->templates->getTemplateFile(Templates::NotFound),
-            new NotFoundTemplate($position, $elementAttributes),
+            new NotFoundTemplate($position, $elementAttributes, $options),
         );
     }
 
-    public function renderSingle(ResponsePosition $position, ?Banner $banner, array $elementAttributes = []): string
+    public function renderSingle(ResponsePosition $position, ?Banner $banner, array $elementAttributes = [], array $options = []): string
     {
         return $this->getLatte()->renderToString(
             $this->templates->getTemplateFile(Templates::Single),
-            new SingleTemplate($position, $banner, $elementAttributes),
+            new SingleTemplate($position, $banner, $elementAttributes, $options),
         );
     }
 
-    public function renderRandom(ResponsePosition $position, ?Banner $banner, array $elementAttributes = []): string
+    public function renderRandom(ResponsePosition $position, ?Banner $banner, array $elementAttributes = [], array $options = []): string
     {
         return $this->getLatte()->renderToString(
             $this->templates->getTemplateFile(Templates::Random),
-            new RandomTemplate($position, $banner, $elementAttributes),
+            new RandomTemplate($position, $banner, $elementAttributes, $options),
         );
     }
 
-    public function renderMultiple(ResponsePosition $position, array $banners, array $elementAttributes = []): string
+    public function renderMultiple(ResponsePosition $position, array $banners, array $elementAttributes = [], array $options = []): string
     {
         return $this->getLatte()->renderToString(
             $this->templates->getTemplateFile(Templates::Multiple),
-            new MultipleTemplate($position, $banners, $elementAttributes),
+            new MultipleTemplate($position, $banners, $elementAttributes, $options),
         );
     }
 
-    public function renderClientSide(RequestPosition $position, array $elementAttributes = []): string
+    public function renderClientSide(RequestPosition $position, array $elementAttributes = [], array $options = []): string
     {
-        $resourceAttributes = [];
-
-        foreach ($position->getResources() as $resource) {
-            $resourceAttributes['data-amp-resource-' . $resource->getCode()] = implode(',', $resource->getValues());
-        }
-
         return $this->getLatte()->renderToString(
             $this->templates->getTemplateFile(Templates::ClientSide),
-            new ClientSideTemplate($position, $resourceAttributes, $elementAttributes),
+            new ClientSideTemplate($position, $elementAttributes, $options),
         );
     }
 

src/Renderer/Latte/Templates/ClientSideTemplate.php

@@ -10,23 +10,23 @@ final class ClientSideTemplate
 {
     public Position $position;
 
-    /** @var array<string, string> */
-    public array $resourceAttributes;
-
     /** @var array<string, scalar|null> */
     public array $elementAttributes;
 
+    /** @var array<string, scalar> */
+    public array $options;
+
     /**
-     * @param array<string, string>      $resourceAttributes
      * @param array<string, scalar|null> $elementAttributes
+     * @param array<string, scalar>      $options
      */
     public function __construct(
         Position $position,
-        array $resourceAttributes,
-        array $elementAttributes
+        array $elementAttributes,
+        array $options
     ) {
         $this->position = $position;
-        $this->resourceAttributes = $resourceAttributes;
         $this->elementAttributes = $elementAttributes;
+        $this->options = $options;
     }
 }

src/Renderer/Latte/Templates/MultipleTemplate.php

@@ -17,17 +17,23 @@ final class MultipleTemplate
     /** @var array<string, scalar|null> */
     public array $elementAttributes;
 
+    /** @var array<string, scalar> */
+    public array $options;
+
     /**
      * @param array<int, Banner>         $banners
      * @param array<string, scalar|null> $elementAttributes
+     * @param array<string, scalar>      $options
      */
     public function __construct(
         Position $position,
         array $banners,
-        array $elementAttributes
+        array $elementAttributes,
+        array $options
     ) {
         $this->position = $position;
         $this->banners = $banners;
         $this->elementAttributes = $elementAttributes;
+        $this->options = $options;
     }
 }

src/Renderer/Latte/Templates/NotFoundTemplate.php

@@ -13,14 +13,20 @@ final class NotFoundTemplate
     /** @var array<string, scalar|null> */
     public array $elementAttributes;
 
+    /** @var array<string, scalar> */
+    public array $options;
+
     /**
      * @param array<string, scalar|null> $elementAttributes
+     * @param array<string, scalar>      $options
      */
     public function __construct(
         Position $position,
-        array $elementAttributes
+        array $elementAttributes,
+        array $options
     ) {
         $this->position = $position;
         $this->elementAttributes = $elementAttributes;
+        $this->options = $options;
     }
 }

src/Renderer/Latte/Templates/RandomTemplate.php

@@ -16,16 +16,22 @@ final class RandomTemplate
     /** @var array<string, scalar|null> */
     public array $elementAttributes;
 
+    /** @var array<string, scalar> */
+    public array $options;
+
     /**
      * @param array<string, scalar|null> $elementAttributes
+     * @param array<string, scalar>      $options
      */
     public function __construct(
         Position $position,
         ?Banner $banner,
-        array $elementAttributes
+        array $elementAttributes,
+        array $options
     ) {
         $this->position = $position;
         $this->banner = $banner;
         $this->elementAttributes = $elementAttributes;
+        $this->options = $options;
     }
 }

src/Renderer/Latte/Templates/SingleTemplate.php

@@ -16,16 +16,22 @@ final class SingleTemplate
     /** @var array<string, scalar|null> */
     public array $elementAttributes;
 
+    /** @var array<string, scalar> */
+    public array $options;
+
     /**
      * @param array<string, scalar|null> $elementAttributes
+     * @param array<string, scalar>      $options
      */
     public function __construct(
         Position $position,
         ?Banner $banner,
-        array $elementAttributes
+        array $elementAttributes,
+        array $options
     ) {
         $this->position = $position;
         $this->banner = $banner;
         $this->elementAttributes = $elementAttributes;
+        $this->options = $options;
     }
 }