README

A comprehensive bundle that provides Progressive Web App (PWA) support for Contao CMS, enabling modern web application features for your Contao websites.

Features

• Create and register manifest files for each page root
• Generate and register service workers for each page root
• Send custom push notifications from the backend
• Set an offline fallback page for improved user experience
• content elements to manage push notification subscriptions

Installation

Install with Composer

composer require heimrichhannot/contao-pwa-bundle

After installation, update your database.

Requirements

• PHP ^8.2
• Contao ^5.3

Additional Dependency for Push-Notifications

To enable web push notifications, you'll need to install web-push-libs/web-push-php (versions 5 to 10 are supported):

composer require minishlink/web-push:^8.0

Additionally, ensure the following PHP extensions are installed and enabled:

• gmp
• mbstring
• curl
• openssl

Setup

1. If you want to use push notifications, add VAPID keys to your configuration (see VAPID Keys section below).
2. Create a PWA Configuration in the Contao backend (System → PWA Configuration).
3. Add the configuration to a page root:
   • Navigate to page settings
   • Find the "Progressive Web App" section
   • Select "Yes" and choose your configuration
   • Upon saving, the page manifest and service worker will be generated automatically
4. To provide an option for users to register for push notifications, add either:
   • The push subscription button content element, or
   • The push notification popup element to your page

VAPID Keys

For push notifications, you need to add your server VAPID keys to your config file, typically in your project's config.yml. If you don't have VAPID keys yet, you can generate them in the PWA Bundle backend (Contao Backend → System → PWA Configuration → Control → Authentication).

huh_pwa:
    vapid:
        subject: "mailto:your-email@example.org"
        publicKey: "YOUR_PUBLIC_KEY"
        privateKey: "YOUR_PRIVATE_KEY"

Usage

Content Elements

This bundle provide 4 content elements:

• Install Pwa Button: A simple button that can be used to trigger the "Add to homescreen" prompt
• Offline Pages: Show cached offline pages (can be used to show the user all working link on the offline page)
• Push Subscription: Display a button to subscribe/unsubscribe to push notifications
• Push Notification Popup: See description below

Push Notification Popup

This content element can be used to show a popup to the user, asking them to subscribe to push notifications. By default, the popup opens on button click, but you can also set it to open automatically when the page loads. A template for bootstrap 5 modals is included. The templates are prepared to easily create variant of them without overriding greater parts of the template.

Regenerating Files

You can regenerate all manifest and service worker files at once from:

• The PWA Control panel (Contao Backend → System → PWA Configuration → Control → Files → Rebuild files)
• Or by using the command: huh:pwa:build

Development

JavaScript Events

To support custom controls, the bundle provides events and event listeners that can be used. All events are dispatched and listened to on the document object.

Events

Listeners

Complete Configuration

huh_pwa:
    vapid:
        subject: "mailto:your-email@example.org"
        publicKey: "YOUR_PUBLIC_KEY"
        privateKey: "YOUR_PRIVATE_KEY"
    push:
        automatic_padding: 2847 # int (payload size in byte (min 0, max 4078)) or boolean (enable/disable)
    manifest_path: '/pwa' # where the manifest files should be located within web folder
    configfile_path: '/pwa' # where the configuration files should be located within web folder

Commands

Todo

• Image size configuration
• Support for SVG icons
• Selective page precaching
• Customizable "Add to homescreen" and push notification prompts