feature #192 [Swup] Convert options to values (weaverryan)

tgalopin · tgalopin · commit 72527fec8079 · 2021-12-07T19:37:54.000+01:00
This PR was merged into the 2.x branch. Discussion ---------- [Swup] Convert options to values | Q | A | ------------- | --- | Bug fix? | no | New feature? | yes | Tickets | none | License | MIT Simple: * Converts all `data-` options to the values API * Also added a `swup:pre-connect` event Cheers! Commits ------- 257d480 [Swup] Converting options to values
diff --git a/src/Swup/CHANGELOG.md b/src/Swup/CHANGELOG.md
@@ -5,7 +5,10 @@
 -   Support for `stimulus` version 2 was removed and support for `@hotwired/stimulus`
     version 3 was added. See the [@symfony/stimulus-bridge CHANGELOG](https://github.com/symfony/stimulus-bridge/blob/main/CHANGELOG.md#300)
     for more details.
--   Support added for Symfony 6
+-   All options were changed from `data-` attributes to Stimulus values. See
+    The README for updated instructions.
+-   Added a new `swup:pre-connect` event.
+-   Support added for Symfony 6.
 
 ## 1.3
 
diff --git a/src/Swup/README.md b/src/Swup/README.md
@@ -72,8 +72,9 @@ additional containers, for instance to have a navigation menu that updates when
         {% endblock %}
     </head>
     <body
-        {{ stimulus_controller('symfony/ux-swup/swup') }}
-        data-containers="#swup #nav" {# list of selectors separated by spaces #}
+        {{ stimulus_controller('symfony/ux-swup/swup', {
+            containers: ['#swup', '#nav']
+        }) }}
     >
         {# ... #}
 
@@ -88,26 +89,37 @@ additional containers, for instance to have a navigation menu that updates when
 </html>
 ```
 
-You can configure several other options using data-attributes on the `body` tag:
+You can configure several other options using values on the controller.
+Most of these correspond to [Swup Options](https://swup.js.org/options),
+but there are a few extra added:
 
 ```twig
 <html lang="en">
     <head>
         <title>Swup</title>
     </head>
     <body
-        {{ stimulus_controller('symfony/ux-swup/swup') }}
-        data-containers="#swup #nav"
-        data-theme="slide" {# or "fade", the default #}
-        data-debug="data-debug" {# add this attribute to enable debug #}
-        data-cache="data-cache" {# add this attribute to enable local cache: be careful, it only makes sense for mostly static websites #}
-        data-animate-history-browsing="data-animate-history-browsing" {# add this attribute to animate history browsing #}
+        {{ stimulus_controller('symfony/ux-swup/swup', {
+            containers: ['#swup', '#nav'],
+            animateHistoryBrowsing: true
+            animationSelector: '[class*="transition-"]',
+            cache: true,
+            linkSelector: '...',
+
+            theme: 'slide',
+            debug: true,
+        }) }}
     >
         {# ... #}
     </body>
 </html>
 ```
 
+The extra options are:
+
+-   `theme`: either `slide` or `fade` (the default);
+-   `debug`: add this attribute to enable debug.
+
 ### Extend the default behavior
 
 Symfony UX Swup allows you to extend its default behavior using a custom Stimulus controller:
@@ -119,12 +131,19 @@ import { Controller } from '@hotwired/stimulus';
 
 export default class extends Controller {
     connect() {
+        this.element.addEventListener('swup:pre-connect', this._onPreConnect);
         this.element.addEventListener('swup:connect', this._onConnect);
     }
 
     disconnect() {
         // You should always remove listeners when the controller is disconnected to avoid side-effects
-        this.element.removeEventListener('swup:connect', this._onConnect);
+        this.element.removeEventListener('swup:pre-connect', this._onConnect);
+        this.element.removeEventListener('swup:connect', this._onPreConnect);
+    }
+
+    _onPreConnect(event) {
+        // Swup has not been initialized - options can be changed
+        console.log(event.detail.options); // Options that will be used to initialize Swup
     }
 
     _onConnect(event) {
diff --git a/src/Swup/Resources/assets/dist/controller.js b/src/Swup/Resources/assets/dist/controller.js
@@ -5,29 +5,31 @@ import SwupFormsPlugin from '@swup/forms-plugin';
 import SwupFadeTheme from '@swup/fade-theme';
 import SwupSlideTheme from '@swup/slide-theme';
 
-class controller extends Controller {
+class default_1 extends Controller {
     connect() {
         const options = {
             containers: ['#swup'],
-            cache: this.element.hasAttribute('data-cache'),
-            animateHistoryBrowsing: this.element.hasAttribute('data-animate-history-browsing'),
-            plugins: [
-                'slide' === this.element.getAttribute('data-theme') ? new SwupSlideTheme() : new SwupFadeTheme(),
-                new SwupFormsPlugin(),
-            ],
+            plugins: ['slide' === this.themeValue ? new SwupSlideTheme() : new SwupFadeTheme(), new SwupFormsPlugin()],
         };
-        if (this.element.getAttribute('data-containers')) {
-            options.containers = this.element.getAttribute('data-containers').split(' ');
+        if (this.hasAnimateHistoryBrowsingValue) {
+            options.animateHistoryBrowsing = this.animateHistoryBrowsingValue;
         }
-        if (this.element.getAttribute('data-link-selector')) {
-            options.linkSelector = this.element.getAttribute('data-link-selector');
+        if (this.hasAnimationSelectorValue) {
+            options.animationSelector = this.animationSelectorValue;
         }
-        if (this.element.getAttribute('data-animation-selector')) {
-            options.animationSelector = this.element.getAttribute('data-animation-selector');
+        if (this.hasCacheValue) {
+            options.cache = this.cacheValue;
         }
-        if (this.element.hasAttribute('data-debug')) {
+        if (this.hasContainersValue) {
+            options.containers = this.containersValue;
+        }
+        if (this.hasLinkSelectorValue) {
+            options.linkSelector = this.linkSelectorValue;
+        }
+        if (this.debugValue) {
             options.plugins.push(new SwupDebugPlugin());
         }
+        this._dispatchEvent('swup:pre-connect', { options });
         const swup = new Swup(options);
         this._dispatchEvent('swup:connect', { swup, options });
     }
@@ -37,5 +39,14 @@ class controller extends Controller {
         this.element.dispatchEvent(userEvent);
     }
 }
+default_1.values = {
+    animateHistoryBrowsing: Boolean,
+    animationSelector: String,
+    cache: Boolean,
+    containers: Array,
+    linkSelector: String,
+    theme: String,
+    debug: Boolean,
+};
 
-export { controller as default };
+export { default_1 as default };
diff --git a/src/Swup/Resources/assets/src/controller.ts b/src/Swup/Resources/assets/src/controller.ts
@@ -17,33 +17,45 @@ import SwupFadeTheme from '@swup/fade-theme';
 import SwupSlideTheme from '@swup/slide-theme';
 
 export default class extends Controller {
+    static values = {
+        animateHistoryBrowsing: Boolean,
+        animationSelector: String,
+        cache: Boolean,
+        containers: Array,
+        linkSelector: String,
+
+        // custom values
+        theme: String,
+        debug: Boolean,
+    };
+
     connect() {
         const options = {
             containers: ['#swup'],
-            cache: this.element.hasAttribute('data-cache'),
-            animateHistoryBrowsing: this.element.hasAttribute('data-animate-history-browsing'),
-            plugins: [
-                'slide' === this.element.getAttribute('data-theme') ? new SwupSlideTheme() : new SwupFadeTheme(),
-                new SwupFormsPlugin(),
-            ],
+            plugins: ['slide' === this.themeValue ? new SwupSlideTheme() : new SwupFadeTheme(), new SwupFormsPlugin()],
         };
 
-        if (this.element.getAttribute('data-containers')) {
-            options.containers = this.element.getAttribute('data-containers').split(' ');
+        if (this.hasAnimateHistoryBrowsingValue) {
+            options.animateHistoryBrowsing = this.animateHistoryBrowsingValue;
         }
-
-        if (this.element.getAttribute('data-link-selector')) {
-            options.linkSelector = this.element.getAttribute('data-link-selector');
+        if (this.hasAnimationSelectorValue) {
+            options.animationSelector = this.animationSelectorValue;
         }
-
-        if (this.element.getAttribute('data-animation-selector')) {
-            options.animationSelector = this.element.getAttribute('data-animation-selector');
+        if (this.hasCacheValue) {
+            options.cache = this.cacheValue;
         }
-
-        if (this.element.hasAttribute('data-debug')) {
+        if (this.hasContainersValue) {
+            options.containers = this.containersValue;
+        }
+        if (this.hasLinkSelectorValue) {
+            options.linkSelector = this.linkSelectorValue;
+        }
+        if (this.debugValue) {
             options.plugins.push(new SwupDebugPlugin());
         }
 
+        this._dispatchEvent('swup:pre-connect', { options });
+
         const swup = new Swup(options);
 
         this._dispatchEvent('swup:connect', { swup, options });
diff --git a/src/Swup/Resources/assets/test/controller.test.ts b/src/Swup/Resources/assets/test/controller.test.ts
@@ -14,9 +14,15 @@ import { getByTestId, waitFor } from '@testing-library/dom';
 import { clearDOM, mountDOM } from '@symfony/stimulus-testing';
 import SwupController from '../src/controller';
 
+let actualSwupOptions: any = null;
+
 // Controller used to check the actual controller was properly booted
 class CheckController extends Controller {
     connect() {
+        this.element.addEventListener('swup:pre-connect', (event) => {
+            actualSwupOptions = event.detail.options;
+        });
+
         this.element.addEventListener('swup:connect', () => {
             this.element.classList.add('connected');
         });
@@ -42,12 +48,12 @@ describe('SwupController', () => {
                     <div 
                         data-testid="body"
                         data-controller="check swup"
-                        data-containers="#swup #nav"
-                        data-link-selector="a"
-                        data-animation-selector="[transition-*]"
-                        data-debug="data-debug"
-                        data-cache="data-cache"
-                        data-animate-history-browsing="data-animate-history-browsing">
+                        data-swup-containers-value="[&quot;#swup&quot;, &quot;#nav&quot;]"
+                        data-swup-link-selector-value="a"
+                        data-swup-animation-selector-value="[transition-*]"
+                        data-swup-debug-value="data-debug"
+                        data-swup-cache-value="data-cache"
+                        data-swup-animate-history-browsing-value="data-animate-history-browsing">
                         <div id="nav"></div>
                         <div id="swup">
                             <a href="/">Link</a>
@@ -60,12 +66,19 @@ describe('SwupController', () => {
 
     afterEach(() => {
         clearDOM();
+        actualSwupOptions = null;
     });
 
     it('connect', async () => {
-        expect(getByTestId(container, 'body')).not.toHaveClass('connected');
+        const bodyElement = getByTestId(container, 'body');
+        expect(bodyElement).not.toHaveClass('connected');
 
         startStimulus();
-        await waitFor(() => expect(getByTestId(container, 'body')).toHaveClass('connected'));
+        await waitFor(() => expect(bodyElement).toHaveClass('connected'));
+        expect(actualSwupOptions.containers).toEqual(['#swup', '#nav']);
+        expect(actualSwupOptions.linkSelector).toBe('a');
+        expect(actualSwupOptions.animationSelector).toBe('[transition-*]');
+        expect(actualSwupOptions.cache).toBe(true);
+        expect(actualSwupOptions.animateHistoryBrowsing).toBe(true);
     });
 });
