Banner options from AMP administration

- added support for banner options defined in the AMP administration
- updated docs
- updated CHANGELOG

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Added support for new banner option `fetchpriority`.
+- Added support for banner options defined in the AMP administration.
 
 ### Changed
 - Updated docs.

demo/index.html

@@ -118,9 +118,6 @@ <h2>Multiple banner added via data attributes:</h2>
             <div data-amp-banner="homepage.top"
                  data-amp-resource-roles="employee, vip"
                  data-amp-resource-apple_products="shop/buy-iphone/iphone-xs"
-                 data-amp-option-loading="lazy"
-                 data-amp-option-loading-offset="1"
-                 data-amp-option-fetchpriority="0:high,low"
                  class="slider--splide">
             </div>
         </div>

docs/integration-guide.md

@@ -10,8 +10,9 @@
   * [Creating banners manually](#creating-banners-manually)
   * [Creating banners using data attributes](#creating-banners-using-data-attributes)
   * [Banners fetching and rendering](#banners-fetching-and-rendering)
-  * [Lazy loading of image banners](#lazy-loading-of-image-banners)
-  * [Fetch priority of image banners](#fetch-priority-of-image-banners)
+  * [Banner options](#banner-options)
+    * [Lazy loading of image banners](#lazy-loading-of-image-banners)
+    * [Fetch priority of image banners](#fetch-priority-of-image-banners)
   * [Loading banners in iframes](#loading-banners-in-iframes)
   * [Integration with banners that are rendered server-side](#integration-with-banners-that-are-rendered-server-side)
   * [Banner states](#banner-states)
@@ -172,7 +173,21 @@ for (let snippet of snippets) {
 AMPClient.fetch();
 ```
 
-### Lazy loading of image banners
+### Banner options
+
+Banners can contain options, which is practically a key-value object with arbitrary data.
+Options are accessible from event handlers and some of them have functionality tied to them.
+Options that are automatically handled by the client are for example `loading`, or `fetchpriority`.
+
+There are several ways to pass options to banners.
+
+1. Using the fourth argument of the method `createBanner()`.
+2. Using data attributes with prefix `data-amp-option-`.
+3. By setting them on the position detail page in the AMP administration.
+
+Options passed directly through the client ( variants 1 and 2) have a higher priority than options set in the AMP administration ( variant 3).
+
+#### 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 banner.
@@ -208,7 +223,7 @@ AMPClient.createBanner(element, 'homepage.top', {}, {
 
 If you prefer a different implementation of lazy loading, it is possible to pass custom templates to the client in the configuration object instead of [the default ones](../src/template) and integrate a different solution in these templates.
 
-### Fetch priority of image banners
+#### Fetch priority of image banners
 
 The [fetchpriority](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) attribute can be set for image and embed banners using the `fetchpriority` option.
 

src/banner/banner.mjs

@@ -95,6 +95,10 @@ export class Banner {
         return null;
     }
 
+    mergeOptions(options) {
+        this.#options.merge(options);
+    }
+
     redrawIfNeeded() {
     }
 

src/banner/managed/managed-banner.mjs

@@ -163,6 +163,10 @@ export class ManagedBanner extends Banner {
             dimensions: responseData['dimensions'] || { width: null, height: null },
         });
 
+        if ('options' in responseData) {
+            this.mergeOptions(responseData.options);
+        }
+
         const banners = [];
 
         for (let i in (responseData.banners || [])) {

src/banner/options.mjs

@@ -10,4 +10,8 @@ export class Options {
     get(optionName, defaultValue = undefined) {
         return this.options[optionName] || defaultValue;
     }
+
+    merge(options) {
+        this.options = {...this.options, ...options};
+    }
 }

src/client/standard/client.mjs

@@ -227,6 +227,10 @@ export class Client {
                 }
 
                 if ('embed' === positionData.mode) {
+                    if ('options' in positionData) {
+                        banner.mergeOptions(positionData.options);
+                    }
+
                     this.createBanner(banner.element, banner.position, banner.rawResources, banner.options.options, positionData.mode);
                     this.#bannerManager.removeBanner(banner);