modal-popup

Univerzální modul pro správu vyskakovacích oken (modalů) a informačních barů pro Nette Framework.

Instalace

composer require czechgroup/modal-popup

Konfigurace

Přidejte do konfigurace aplikace (config/common.neon):

extensions:
    modalPopup: Czechgroup\ModalPopup\DI\ModalPopupExtension

modalPopup:
    # ID menu, ze kterého se načítají položky pro modaly/bary (povinné)
    menuId: 17

    # ID supplementu, který určuje typ - modal/bar (povinné)
    typeSupplementId: 42

    # ID supplementu, který určuje šablonu (volitelné)
    templateSupplementId: 43

    # ID supplementu pro custom delay v sekundách (volitelné)
    delaySupplementId: 44

    # ID supplementu pro custom expiraci cookie v hodinách (volitelné)
    expirationSupplementId: 45

    # ID supplementu pro perex (volitelné)
    perexSupplementId: 8

    # ID supplementu pro text tlačítka (volitelné)
    # Tlačítko odkazuje na URL položky (viz linkService)
    buttonTextSupplementId: 5

    # ID supplementu pro nastavení, zda kliknutí na tlačítko zastaví zobrazování modalu (volitelné)
    # Hodnota supplementu: "1"/"true"/"yes"/"ano" = zastaví, jinak ne
    buttonStopsShowingSupplementId: 110

    # Výchozí hodnota pro buttonStopsShowing, pokud není nastaveno přes supplement (výchozí: true)
    buttonStopsShowingDefault: true

    # Pattern pro cestu k obrázku - <id> bude nahrazeno skutečným ID menu_item
    imagePathPattern: '/userfiles/menuitem/big/img-<id>-4.jpg'

    # Služba pro generování odkazů (volitelné)
    # Používá se pro generování URL tlačítka z url položky
    linkService: Filters\Link

    # Výchozí delay v sekundách (výchozí: 5)
    defaultDelay: 5

    # Výchozí expirace cookie v hodinách (výchozí: 8760 = 1 rok)
    defaultExpiration: 8760

    # Mapování typů na šablony
    templates:
        modal: 'modal.latte'
        bar: 'bar.latte'
        header-bar: 'header-bar.latte'

    # Cesta k custom šablonám v projektu (přepisuje výchozí)
    customTemplatePath: '%appDir%/presenters/Front/templates/components/modalPopup'

Použití

1. Registrace komponenty v presenteru

// BasePresenter.php

use Czechgroup\ModalPopup\Control\ModalPopupControl;
use Czechgroup\ModalPopup\Control\ModalPopupControlFactory;

abstract class BasePresenter extends Presenter
{
    #[Inject]
    public ModalPopupControlFactory $modalPopupFactory;

    protected function createComponentModalPopup(): ModalPopupControl
    {
        $control = $this->modalPopupFactory->create();
        $control->setLang($this->lang); // nastavení aktuálního jazyka
        return $control;
    }
}

2. Vykreslení v šabloně

V @layout.latte nebo jiné šabloně:

{* Vykreslí všechny modaly a bary *}
{control modalPopup}

{* Nebo odděleně *}
{control modalPopup:modals}
{control modalPopup:bars}

{* Nebo konkrétní položku podle ID *}
{control modalPopup:item, 123}

3. Přidání SCSS stylů

Importujte SCSS soubory do svého projektu nebo jej zkopírujte do svého projektu:

// importujte SCSS modulu
@import 'vendor/czechgroup/modal-popup/assets/scss/modal-popup';

V případě kopírování nastavte proměnné v souboru _variables.scss. Jinak upravte ve svém SCSS souboru před importem z vendoru.

4. Přidání JavaScriptu

Zkopírujte soubor assets/js/modal-popup.js do svého projektu a načtěte ho:

<script src="/js/modal-popup.js"></script>

JavaScript se automaticky inicializuje, pokud najde globální proměnnou _modalPopupConfig, kterou generuje komponenta.

Databázová struktura

Modul očekává následující tabulky:

menu_item

CREATE TABLE menu_item (
    id INT UNSIGNED NOT NULL,
    lang TINYINT(2) NOT NULL,
    menu_id INT UNSIGNED NOT NULL,
    hidden TINYINT(2) NOT NULL DEFAULT 0,
    name VARCHAR(255) NOT NULL,
    text TEXT,
    url VARCHAR(255),
    position INT NOT NULL,
    date_enable TIMESTAMP NULL,
    date_disable TIMESTAMP NULL,
    PRIMARY KEY (id, lang)
);

menu_item_x_supplement

CREATE TABLE menu_item_x_supplement (
    supplement_id INT UNSIGNED NOT NULL,
    menu_item_id INT UNSIGNED NOT NULL,
    lang TINYINT(2) NOT NULL,
    value TEXT NOT NULL,
    PRIMARY KEY (supplement_id, menu_item_id, lang)
);

supplement

CREATE TABLE supplement (
    id INT UNSIGNED PRIMARY KEY,
    lang TINYINT(2) NOT NULL,
    name VARCHAR(255)
);

Filtrování položek

Modul automaticky filtruje položky podle:

• hidden = 0 - pouze viditelné položky
• date_enable - pokud je nastaveno, položka se zobrazí až po tomto datu
• date_disable - pokud je nastaveno, položka se přestane zobrazovat po tomto datu
• position - položky s vyšší pozicí překrývají položky s nižší pozicí (vyšší z-index)

Supplementy

Modul používá supplementy pro nastavení jednotlivých položek:

Tlačítko v modalu

Modul podporuje zobrazení tlačítka v modalu s následující logikou:

1. Text tlačítka - načítá se ze supplementu (buttonTextSupplementId)
2. URL tlačítka - generuje se z url položky pomocí linkService (pokud je nakonfigurováno)
3. Chování po kliknutí - lze nastavit, zda kliknutí na tlačítko:
   • Uloží cookie a zastaví další zobrazování modalu (buttonStopsShowing: true)
   • Pouze zavře modal bez uložení cookie (buttonStopsShowing: false)

Tlačítko používá CSS třídy button button--brand z vašeho projektu.

Typy barů

Modul obsahuje dva typy informačních lišt:

Bar (výchozí)

• Pozice: Fixovaný dole na stránce
• Šablona: bar.latte
• CSS třída: .bar
• Animace: Vysouvá se zespodu

Header Bar

• Pozice: Pod hlavičkou stránky (není fixovaný)
• Šablona: header-bar.latte
• CSS třída: .header-bar
• Animace: Vysouvá se shora
• Použití: Ideální pro upozornění zobrazená hned pod navigací

Pro použití header-bar nastavte v supplementu Typ hodnotu header-bar nebo použijte šablonu header-bar.

Obrázky

Obrázky se načítají pomocí patternu definovaného v konfiguraci:

• imagePathPattern: '/userfiles/menuitem/big/img-<id>-4.jpg'
• <id> je nahrazeno skutečným ID menu_item

Přepsání šablon

Vytvořte soubory v cestě definované v customTemplatePath:

V případě, že je nadefinovaný customTemplatePath, pak je šablona nejprve hledána zde a poté případně až v defaultTemplatePath.

app/presenters/Front/templates/components/modalPopup/
├── control.latte     # hlavní šablona
├── modal.latte       # šablona modalu
├── bar.latte         # šablona baru (fixovaný dole)
├── header-bar.latte  # šablona header baru (pod hlavičkou)
└── newsletter.latte  # custom šablona

Dostupné proměnné v šablonách

V custom šablonách se doporučuje includovat templateType:

{templateType Czechgroup\ModalPopup\templates\ModalParameters}

{* V modal.latte a bar.latte *}
{var $item} - ModalItem objekt:
  - $item->id          int       ID položky
  - $item->lang        int       ID jazyka
  - $item->name        string    Název/titulek
  - $item->text        ?string   HTML obsah
  - $item->perex       ?string   Krátký popis
  - $item->url         ?string   URL odkaz
  - $item->type        string    Typ (modal/bar)
  - $item->template    string    Název šablony
  - $item->delay       int       Zpoždění zobrazení (s)
  - $item->expiration  int       Expirace cookie (h)
  - $item->contentHash string    Hash obsahu
  - $item->image       ?string   Cesta k obrázku
  - $item->position    int       Pozice (pro z-index)
  - $item->buttonText  ?string   Text tlačítka
  - $item->buttonUrl   ?string   URL tlačítka
  - $item->buttonStopsShowing bool Zda klik na tlačítko zastaví zobrazování
  - $item->supplements array     Pole supplementů [name => value]

Cookie logika

• Po zavření modalu/baru se uloží cookie s hashem obsahu
• Pokud se obsah změní (jiný hash), modal se znovu zobrazí
• Expirace je konfigurovatelná globálně i per-položka
• Kliknutí na tlačítko může (dle nastavení) také uložit cookie

Z-index a překrývání

Modaly s vyšší hodnotou position překrývají modaly s nižší hodnotou:

• position: 1 → z-index: 10000
• position: 2 → z-index: 10001
• atd.

JavaScript API

// Instance handleru je dostupná jako:
window._modalPopupHandler

// Manuální zavření položky
_modalPopupHandler.closeItem({id: 123, type: 'modal', hash: '...'});

// Smazání cookie (pro debugging)
_modalPopupHandler.deleteCookie(123);

// Zrušení naplánovaných zobrazení
_modalPopupHandler.cancelAll();

Integrace s custom_modal.js

Pokud máte v projektu custom_modal.js, modul automaticky použije jeho API:

• element.customModal().openModal()
• element.customModal().closeModal()

Pokud custom_modal.js není k dispozici, použije se fallback s display: block/none.

SCSS proměnné

Můžete přepsat následující proměnné před importem SCSS:

// Colors
$modal-content-bg: $color__bg;
$modal-text-color: $color__text;
$modal-text-muted: $color__text-gray;
$modal-border-color: $color__border;
$modal-overlay-bg: rgba($color__bg-dark, 0.5);

// Close button
$modal-close-color: #fff;
$modal-close-hover-color: #fff;
$modal-close-size: 24px;
$modal-close-bg: rgba(0, 0, 0, 0.4);
$modal-close-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);

// Button colors (fallback, přednostně použije button--brand)
$modal-btn-primary-bg: $color__primary;
$modal-btn-primary-color: $color__text-light;
$modal-btn-primary-hover-bg: $color__link-dark;

// Bar colors (fixovaný dole)
$bar-bg: $color__link-dark;
$bar-text-color: $color__text-light;
$bar-link-color: $color__text-light;

// Header bar colors (pod hlavičkou)
$header-bar-bg: $color__primary;
$header-bar-text-color: $color__text-light;
$header-bar-link-color: $color__text-light;

// Spacing
$modal-padding: 30px;
$modal-padding-mobile: 20px;
$modal-border-radius: 8px;

// Sizing
$modal-max-width: 900px;   // Max width when image is present
$modal-min-width: 600px;   // Min/default width without image
$modal-width: fit-content; // Width based on content (image)

// Shadows
$modal-box-shadow: $shadow__main;

// Animation
$modal-animation-duration: 0.3s;
$bar-animation-duration: 0.3s;

// Breakpoints
$modal-breakpoint-mobile: 768px;

Licence

Proprietary - CZECHGROUP