# Pielgrzymka Edukacji Domowej — mapa modlitwy i szkół

Wtyczka WordPressa dla **pielgrzymkaed.pl**. Daje trzy rzeczy:

1. **mapę Polski**, na której zapala się światło w diecezji, z której ktoś się modli,
2. **fragment Pisma Świętego** losowany przy każdej zapalonej świecy,
3. **bazę szkół przyjaznych edukacji domowej** z formularzem, którym każdy może
   dopisać nową szkołę albo poprawić dane istniejącej.

---

## Instalacja

1. Weź gotowy **`pielgrzymka-mapa.zip`** (12,5 MB — z pieśniami).
   Gdyby serwer odrzucił plik tej wielkości, użyj **`pielgrzymka-mapa-bez-piesni.zip`**
   (1,1 MB) i wgraj oba pliki mp3 przez FTP do `wp-content/plugins/pielgrzymka-mapa/assets/piesn/`.
2. W WordPressie: **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer** → wybierz ZIP → **Zainstaluj**.
3. **Włącz**. Przy włączeniu tworzą się trzy tabele i wsypuje się baza 343 szkół.
4. Wstaw skrót `[ped_mapa]` na stronie, na której ma być mapa.

Nic więcej nie trzeba — moduł nie łączy się z żadnym zewnętrznym serwerem.

---

## Skróty do wstawiania

| Skrót | Co pokazuje |
|---|---|
| `[ped_mapa]` | mapa + statystyki + formularz świecy + Słowo + pieśń + intencje + formularz zgłaszania szkół |
| `[ped_piesn]` | sama pieśń z przenikającymi się obrazami |
| `[ped_szkoly]` | sam wykaz szkół z wyszukiwarką |
| `[ped_zglos]` | sam formularz zgłaszania szkół |

Ustawienia `[ped_mapa]`:

```
[ped_mapa tytul="Modlitwa w drodze na Jasną Górę"
          wysokosc="540"        wysokość mapy w pikselach
          szkoly="tak|nie"      warstwa szkół i formularz zgłoszeń
          udostepnianie="tak|nie"
          piesn="tak|nie"       pieśń pod Słowem
          logo="tak|nie"        znak pielgrzymki w nagłówku
          watek="rodzina|modlitwa|droga|wychowanie|maryja"]
```

`watek` zawęża losowanie Pisma do jednego wątku. Bez niego losuje ze wszystkich
123 fragmentów. Można więc mieć osobną podstronę „Modlitwa za rodziny”
z `[ped_mapa watek="rodzina"]` i osobną „W drodze” z `watek="droga"`.

`[ped_szkoly woj="małopolskie"]` zawęża wykaz do województwa.

---

## Baza Pisma Świętego

123 fragmenty w przekładzie Biblii Tysiąclecia, w pięciu wątkach:

| wątek | ile | o czym |
|---|---|---|
| `rodzina` | 30 | dom, małżeństwo, dzieci, wzajemna miłość |
| `modlitwa` | 30 | wytrwałość, ufność, wysłuchanie |
| `droga` | 32 | pielgrzymowanie, prowadzenie, bieg do mety |
| `wychowanie` | 22 | przekazywanie wiary, mądrość, nauka |
| `maryja` | 9 | Jasna Góra jest celem drogi |

Fragmenty siedzą w `assets/pismo.json`. **Dopisanie kolejnych to dodanie pozycji
do listy** — nic więcej nie trzeba zmieniać:

```json
{ "watek": "rodzina", "sigla": "Ps 128, 6", "tekst": "Oglądaj dzieci twoich synów…" }
```

Moduł nigdy nie odda tego samego fragmentu dwa razy pod rząd.

> Sigla i brzmienie sprawdzono z przekładem Biblii Tysiąclecia. Przed drukiem
> materiałów pielgrzymkowych warto dać komuś do przeczytania jeszcze raz —
> tekst liturgiczny to nie miejsce na literówkę.

---

## Pieśń do modlitwy

Pod wylosowanym fragmentem Pisma stoi odtwarzacz z **dwiema pieśniami do wyboru**:
„Granice dobra" (3:46) i „Jasna Góra" (4:53). W tle przenikają się zdjęcia,
zmieniane co 7 sekund.

**Nic nie gra samo z siebie.** Dźwięk włączający się bez pytania jest na stronie
modlitewnej gorszy niż brak dźwięku — ktoś ją otwiera w pracy albo w kościele.
Odtwarzanie zaczyna się po naciśnięciu przycisku. Przełączenie pieśni w trakcie
grania podejmuje nową od razu; przełączenie przy zatrzymanym odtwarzaczu tylko
podmienia nagranie.

### Dokładanie pieśni i obrazów

Skopiuj plik do katalogu — moduł sam go zobaczy, nic nie trzeba zmieniać w kodzie:

```
assets/piesn/   *.mp3, *.ogg, *.m4a   → kolejny przycisk wyboru
assets/madonna/ *.jpg, *.png, *.webp  → kolejny obraz w przenikaniu
```

Nazwy plików **bez polskich znaków** (część serwerów je przekręca przy pobieraniu).
Właściwy tytuł podaje się w `assets/piesn/nazwy.json`:

```json
{ "piesn": { "granice-dobra": "Granice dobra", "jasna-gora": "Jasna Góra" } }
```

> **Obrazy do wymiany.** W katalogu `madonna/` leżą na razie zdjęcia z materiałów
> pielgrzymki (Jasna Góra nocą, rodziny). Wizerunku Matki Bożej Częstochowskiej
> nie było wśród wgranych plików — po jego dorzuceniu wejdzie automatycznie.
> Uwaga: Jasna Góra ogranicza rozpowszechnianie reprodukcji Ikony, więc warto
> potwierdzić prawa do konkretnego pliku, zanim trafi na stronę publiczną.
> To samo dotyczy praw do obu nagrań.

---

## Baza szkół

**343 szkół** z bazy FED (stan 1.07.2026), ze wszystkich 16 województw,
z przypisaną diecezją. Braki w danych źródłowych, jawnie pokazane w module:

| brak | ilu szkół dotyczy |
|---|---|
| adres | 25 |
| telefon | 37 |
| e-mail | 17 |
| strona WWW | 43 |
| niepewna diecezja | 11 |

11 szkół miało w źródle diecezję z dopiskiem „(do potw.)”. Są oznaczone
osobno — mają pomarańczową krawędź i podpis „przypisanie do diecezji wymaga
potwierdzenia”. To nie usterka, tylko lista pierwszych rzeczy do zrobienia.

### Jak baza rośnie

1. Ktoś wypełnia formularz — obowiązkowa jest **tylko nazwa szkoły**.
2. Zgłoszenie trafia do kolejki i na e-mail administratora witryny.
3. W kokpicie (**Pielgrzymka ED** w menu WordPressa) jest do zatwierdzenia
   albo odrzucenia z uzasadnieniem.
4. Dopiero zatwierdzone trafia na mapę. **Nic nie publikuje się samo.**

Formularz przyjmuje też **poprawki** do szkół już wpisanych — po zatwierdzeniu
nadpisuje dane i zdejmuje znacznik „do potwierdzenia”.

---

## Co moduł zapisuje o ludziach

Przy zapalonej świecy: **diecezja, godzina, wylosowany fragment Pisma** i —
jeśli ktoś ją napisał — **jawna intencja**. Imię jest nieobowiązkowe.

Czego **nie** zapisuje: adresu IP, konta, ciasteczek śledzących. W tabeli
`ped_swiece` nie ma na to kolumn — brak tych kolumn jest zabezpieczeniem,
nie przeoczeniem.

Przycisk „Wskaż moją okolicę” pyta przeglądarkę o położenie, zamienia je na
diecezję **na urządzeniu użytkownika** i wysyła na serwer wyłącznie kod diecezji.
Współrzędne nigdzie nie wychodzą.

Zabezpieczenia: nonce WordPressa przy każdym zapisie, próg 30 s między świecami
i 60 s między zgłoszeniami, wycinanie znaczników HTML z każdego pola.

---

## Udostępnianie w mediach społecznościowych

Po zapaleniu świecy pojawiają się trzy przyciski:

- **Facebook** — otwiera okno udostępnienia strony,
- **Instagram** — kopiuje gotowy tekst z fragmentem Pisma (Instagram nie
  przyjmuje wpisów z przeglądarki, więc tekst trzeba wkleić w aplikacji),
- **Pobierz obrazek** — rysuje kwadrat 1080 × 1080 px ze znakiem pielgrzymki
  w złotej poświacie, fragmentem Pisma i licznikiem świec; format, który
  Instagram przyjmuje bez przycinania.

---

## Pliki

```
pielgrzymka-mapa.php        wtyczka: tabele, zapisy, skróty, kokpit
widok-mapa.php              widok [ped_mapa]
widok-zglos.php             widok [ped_zglos] — formularz zgłaszania szkół
widok-szkoly.php            widok [ped_szkoly] — wykaz z wyszukiwarką
widok-piesn.php             widok [ped_piesn] — pieśń i przenikające się obrazy
widok-kokpit.php            ekran moderacji w panelu WordPressa
assets/pielgrzymka-mapa.css wygląd (barwy w zmiennych, do nadpisania w motywie)
assets/pielgrzymka-mapa.js  rysowanie mapy, wysyłka, udostępnianie
assets/kontury.json         41 diecezji Polski + przekształcenie współrzędnych
assets/szkoly.json          343 szkół — baza startowa
assets/pismo.json           123 fragmenty Pisma w pięciu wątkach
assets/logo-pionowe.png     znak pielgrzymki (nagłówek, obrazek na Instagram)
assets/logo-poziome.png     znak w układzie poziomym, do własnych zastosowań
assets/piesn/               nagrania — dorzucenie pliku dodaje przycisk wyboru
assets/madonna/             obrazy przenikające się pod pieśnią
```

## Barwy

Wzięte wprost ze znaku pielgrzymki — odczytane z pliku logo, nie dobrane na oko:

| | |
|---|---|
| granat (wieża, napisy) | `#093E7A` |
| błękit (księga, podpisy) | `#2B84BE` |
| złoto (aureola, płomień świecy) | `#FDC845` |

Diecezja bez świecy ma chłodny błękit, zapalona rozgrzewa się do złota —
ciepło rozlewające się po chłodnym kraju czyta się od razu, bez legendy.

Wszystko siedzi w zmiennych CSS. Żeby cokolwiek przestawić, w motywie potomnym:

```css
.ped, .ped-zglos, .ped-wykaz {
  --ped-atrament: #093e7a;
  --ped-plomien:  #fdc845;
}
```

## Wymagania

WordPress 5.8+, PHP 7.4+. Rozszerzenie `mbstring` **nie** jest wymagane.
Moduł nie potrzebuje żadnej biblioteki z zewnątrz — mapa to zwykły SVG.
