webgis-lohne/public/js/onboarding.js

// =====================================================================
// WebGIS Citizen Participation Portal — Onboarding Tour
// Guides Users through the Participation Portal
// =====================================================================


// =================================================================
// Block 1: Onboarding Configuration
// =================================================================

// ONBOARDING_MODE — Controls when the Tutorial is shown:
const ONBOARDING_MODE = 'once';
//     'once'    — Shown on first Visit, stored in localStorage
//     'session' — Shown per Browser Session, stored in sessionStorage
//     'always'  — Shows always, nothing stored

// Prevents double Initialization
let onboardingStarted = false;


// =================================================================
// Block 2: Tour Initialization
// =================================================================

function initOnboardingTour() {

    // Checks if Tutorial should be shown based on Onboarding Mode
    if (ONBOARDING_MODE === 'once' && localStorage.getItem('webgis_onboarding_done')) {
        return;
    }
    if (ONBOARDING_MODE === 'session' && sessionStorage.getItem('webgis_onboarding_done')) {
        return;
    }

    // Waits for Welcome and Login Modals to be closed
    waitForModalsToClose(function () {
        setTimeout(startTour, 600);
    });
}


// =================================================================
// Block 3: Modal Watcher — Starts Tour other Welcome and Login Modals closed
// =================================================================

function waitForModalsToClose(callback) {
    const welcomeModal = document.getElementById('welcome-modal');
    const loginModal = document.getElementById('login-modal');

    const checkInterval = setInterval(function () {
        const welcomeHidden = !welcomeModal || welcomeModal.style.display === 'none' || welcomeModal.style.display === '';
        const loginHidden = !loginModal || loginModal.style.display === 'none' || loginModal.style.display === '';

        if (welcomeHidden && loginHidden) {
            clearInterval(checkInterval);
            callback();
        }
    }, 300);

    // Safety Timeout
    setTimeout(function () {
        clearInterval(checkInterval);
        callback();
    }, 30000);
}


// =================================================================
// Block 4: Tour Definition
// =================================================================

function startTour() {
    // Prevents double Start
    if (onboardingStarted) return;
    onboardingStarted = true;

    const tour = new Shepherd.Tour({
        useModalOverlay: true,
        defaultStepOptions: {
            cancelIcon: { enabled: true },
            scrollTo: false,
            classes: 'onboarding-step',
            popperOptions: {
                modifiers: [
                    { name: 'offset', options: { offset: [0, 14] } }
                ]
            }
        }
    });


    // -----------------------------------------------------------------
    // Step 1: Welcome
    // -----------------------------------------------------------------
    tour.addStep({
        id: 'welcome',
        title: '<i class="fa-solid fa-hand-wave"></i> Wilkommen bei der Mitmachkarte!',
        text: 'Dieses interaktive Tutorial zeigt Ihnen die Kernfunktionen der Mitmachkarte.' +
              '<br><br><span style="font-size:0.8rem;color:var(--color-text-secondary);">Sie können das Tutorial jederzeit durch den Hilfe-Tab der Seitenleiste wiederholen.</span>',
        buttons: [
            {
                text: 'Überspringen',
                action: tour.cancel,
                classes: 'shepherd-button-secondary'
            },
            {
                text: 'Los geht\'s <i class="fa-solid fa-arrow-right"></i>',
                action: tour.next,
                classes: 'shepherd-button-primary'
            }
        ]
    });


    // -----------------------------------------------------------------
    // Step 2: Drawing Tools
    // -----------------------------------------------------------------
    tour.addStep({
        id: 'drawing-tools',
        title: '<i class="fa-solid fa-pencil"></i> Beitrag hinzufügen',
        text: 'Verwenden Sie die <strong>Zeichenwerkzeuge</strong>, um Hinweise, Anregungen und Vorschläge auf der Mitmachkarte als Punkte, Linien oder Flächen hinzuzufügen.',
        attachTo: {
            element: '.leaflet-pm-toolbar',
            on: 'left'
        },
        beforeShowPromise: function () {
            return new Promise(function (resolve) {
                sidebar.close();
                setTimeout(resolve, 300);
            });
        },
        buttons: [
            {
                text: '<i class="fa-solid fa-arrow-left"></i> Zurück',
                action: tour.back,
                classes: 'shepherd-button-secondary'
            },
            {
                text: 'Weiter <i class="fa-solid fa-arrow-right"></i>',
                action: tour.next,
                classes: 'shepherd-button-primary'
            }
        ]
    });


    // -----------------------------------------------------------------
    // Step 3: Address Search
    // -----------------------------------------------------------------
    tour.addStep({
        id: 'address-search',
        title: '<i class="fa-solid fa-magnifying-glass"></i> Adresssuche',
        text: 'Verwenden Sie die <strong>Adresssuche</strong>, um schnell den richtigen Ort auf der Mitmachkarte zu finden.',
        attachTo: {
            element: '.leaflet-control-geocoder',
            on: 'left'
        },
        buttons: [
            {
                text: '<i class="fa-solid fa-arrow-left"></i> Zurück',
                action: tour.back,
                classes: 'shepherd-button-secondary'
            },
            {
                text: 'Weiter <i class="fa-solid fa-arrow-right"></i>',
                action: tour.next,
                classes: 'shepherd-button-primary'
            }
        ]
    });


    // -----------------------------------------------------------------
    // Step 4: Layer Control
    // -----------------------------------------------------------------
    tour.addStep({
        id: 'layer-control',
        title: '<i class="fa-solid fa-layer-group"></i> Kartenansicht',
        text: 'Wechseln Sie zwischen verschiedenen <strong>Hintergrundkarten</strong> und <strong>Satellitenbildern</strong>.',
        attachTo: {
            element: '.leaflet-control-layers',
            on: 'left'
        },
        buttons: [
            {
                text: '<i class="fa-solid fa-arrow-left"></i> Zurück',
                action: tour.back,
                classes: 'shepherd-button-secondary'
            },
            {
                text: 'Weiter <i class="fa-solid fa-arrow-right"></i>',
                action: tour.next,
                classes: 'shepherd-button-primary'
            }
        ]
    });


    // -----------------------------------------------------------------
    // Step 5: Sidebar
    // -----------------------------------------------------------------
    tour.addStep({
        id: 'sidebar',
        title: '<i class="fa-solid fa-bars"></i> Seitenleiste',
        text: 'In der Seitenleiste finden Sie <strong>Hilfestellungen</strong>, <strong>Listenansichten</strong> und <strong>Neuigkeiten</strong>.',
        attachTo: {
            element: '#sidebar',
            on: 'right'
        },
        beforeShowPromise: function () {
            return new Promise(function (resolve) {
                sidebar.open('tab-help');
                setTimeout(resolve, 400);
            });
        },
        buttons: [
            {
                text: '<i class="fa-solid fa-arrow-left"></i> Zurück',
                action: tour.back,
                classes: 'shepherd-button-secondary'
            },
            {
                text: 'Tutorial abschließen <i class="fa-solid fa-check"></i>',
                action: tour.next,
                classes: 'shepherd-button-primary'
            }
        ]
    });


    // -----------------------------------------------------------------
    // Completion and Cancellation
    // -----------------------------------------------------------------
    tour.on('complete', function () {
        markOnboardingDone();
        onboardingStarted = false;
    });

    tour.on('cancel', function () {
        markOnboardingDone();
        onboardingStarted = false;
    });

    tour.start();
}


// =================================================================
// Marks Onboarding as completed
// =================================================================

function markOnboardingDone() {
    if (ONBOARDING_MODE === 'once') {
        localStorage.setItem('webgis_onboarding_done', 'true');
    } else if (ONBOARDING_MODE === 'session') {
        sessionStorage.setItem('webgis_onboarding_done', 'true');
    }
}


// =================================================================
// Manual Tour Restart
// =================================================================

function restartOnboarding() {
    localStorage.removeItem('webgis_onboarding_done');
    sessionStorage.removeItem('webgis_onboarding_done');
    onboardingStarted = false;
    startTour();
}


// =================================================================
// Auto-Start on Page Load
// =================================================================

initOnboardingTour();