symfony/ux-swup

Swup integration for Symfony

Installs: 10 096

Dependents: 0

Suggesters: 0

Security: 0

Stars: 21

Watchers: 7

Forks: 4

Language:JavaScript

Type:symfony-bundle

v1.3.0 2021-05-20 17:58 UTC

This package is auto-updated.

Last update: 2021-10-07 19:29:29 UTC


README

Symfony UX Swup is a Symfony bundle integrating Swup in Symfony applications. It is part of the Symfony UX initiative.

Swup is a complete and easy to use page transition library for Web applications. It creates a Single Page Application feel to Web applications without having to change anything on the server and without bringing the complexity of a React/Vue/Angular application.

Installation

Symfony UX Swup does not use any PHP and can be installed with any PHP/Symfony version.

You can install this bundle using Composer and Symfony Flex:

composer require symfony/ux-swup

# Don't forget to install the JavaScript dependencies as well and compile
yarn install --force
yarn encore dev

Also make sure you have at least version 2.0 of @symfony/stimulus-bridge in your package.json file.

Usage

In order to implement page transitions, Swup works by transforming the links of your application in AJAX calls to the target in their href. Once the AJAX call result is received, Swup is able to swap the content of the current page with the new content received by AJAX. When doing this swap, it is therefore able to animate a transition between pages.

The main usage of Symfony UX Swup is to use its Stimulus controller to initialize Swup:

<html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body {{ stimulus_controller('symfony/ux-swup/swup') }}>
        {# ... #}

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>

Note The stimulus_controller() function comes from WebpackEncoreBundle v1.10.

That's it! Swup now reacts to a link click and run the default fade-in transition.

By default, Swup will use the #swup selector as a container, meaning it will only swap the content of this container from one page to another. If you wish, you can configure additional containers, for instance to have a navigation menu that updates when changing pages:

<html lang="en">
    <head>
        <title>Swup</title>

        {% block javascripts %}
            {{ encore_entry_script_tags('app') }}
        {% endblock %}
    </head>
    <body
        {{ stimulus_controller('symfony/ux-swup/swup') }}
        data-containers="#swup #nav" {# list of selectors separated by spaces #}
    >
        {# ... #}

        <nav id="nav">
            {# ... #}
        </nav>

        <main id="swup">
            {# ... #}
        </main>
    </body>
</html>

You can configure several other options using data-attributes on the body tag:

<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 #}
    >
        {# ... #}
    </body>
</html>

Extend the default behavior

Symfony UX Swup allows you to extend its default behavior using a custom Stimulus controller:

// assets/controllers/myswup_controller.js

import { Controller } from 'stimulus';

export default class extends Controller {
    connect() {
        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);
    }

    _onConnect(event) {
        // Swup has just been intialized and you can access details from the event
        console.log(event.detail.swup); // Swup instance
        console.log(event.detail.options); // Options used to initialize Swup
    }
}

Then in your template, add your controller to the HTML attribute:

<html lang="en">
    <head>
        <title>Swup</title>
        {# ... #}
    </head>
    <body {{ stimulus_controller({
        myswup: {},
        'symfony/ux-swup/swup': {}
    }) }}>
        {# ... #}
    </body>
</html>

Note: be careful to add your controller before the Swup controller so that it is executed before and can listen on the swup:connect event properly.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

However it is currently considered experimental, meaning it is not bound to Symfony's BC policy for the moment.

Run tests

PHP tests

php vendor/bin/phpunit

JavaScript tests

cd Resources/assets
yarn test