feat: prima versione del plugin, blocco e shortcode con iframe stampato lato server

README.md

@@ -0,0 +1,50 @@
+# Piazza in Festa, plugin WordPress
+
+Il calendario degli eventi dei comuni italiani dentro un sito WordPress: un blocco, uno shortcode, si aggiorna da solo.
+
+E' il terzo modo di consumare il widget di [piazzainfesta.it](https://piazzainfesta.it/widget), dopo lo snippet `<script>` e l'iframe a mano. Esiste perche' WordPress filtra i tag `<script>` e `<iframe>` in base ai permessi: passano solo per gli amministratori di installazioni self-hosted, mentre il redattore che nella pratica incolla le cose se li vede sparire senza spiegazioni. Il plugin stampa l'iframe lato server, quindi non c'e' niente da filtrare e funziona per chiunque possa scrivere un articolo.
+
+## Come e' fatto
+
+| File | Cosa fa |
+|---|---|
+| `piazza-in-festa.php` | header del plugin, costanti, registrazione degli asset |
+| `includes/render.php` | costruisce l'URL del widget e stampa l'iframe. Unico posto dove si sanifica e unico posto che produce markup |
+| `includes/shortcode.php` | `[piazza-in-festa comuni="alba,barolo" limite="5"]` |
+| `includes/block.php` | blocco dinamico: il markup lo fa PHP a ogni caricamento, quindi gli eventi sono sempre quelli di oggi |
+| `includes/settings.php` | Impostazioni > Piazza in Festa, un campo solo: la chiave per la versione senza marchio |
+| `blocks/eventi/index.js` | pannello dell'editor, `wp.element.createElement` senza JSX e senza build step: quello che leggi e' quello che gira |
+| `assets/js/resize.js` | ascolta l'altezza che arriva da dentro l'iframe e adatta il riquadro |
+
+Niente build: non c'e' `npm`, non c'e' webpack, non c'e' codice minificato. E' una richiesta esplicita delle linee guida di WordPress.org (niente sorgenti nascoste) ed e' anche comodo per noi.
+
+## Vincoli da non rompere
+
+Sono le regole che decidono se il plugin resta nella directory:
+
+- **Niente limitazioni artificiali** (linee guida 5 e 6). Ogni funzione del plugin funziona senza chiave. La chiave e' un'opzione del *servizio*: la inoltra e basta, non abilita niente nel codice.
+- **Niente codice eseguibile scaricato da fuori** (linea guida 8). Il JS di resize e' locale, non e' il nostro `/widget.js` remoto. Se un domani serve altro JS, va nel plugin, non caricato dal nostro dominio.
+- **Servizio esterno dichiarato**. La sezione `== External services ==` del `readme.txt` dice cosa parte dal browser del visitatore e verso dove. Se cambiano i parametri inviati, si aggiorna quella sezione.
+- **Tutto sanificato e tutto in escape**, prefisso `pinfesta_` su ogni funzione e opzione.
+
+## Build
+
+```bash
+./build.sh          # -> dist/piazza-in-festa.zip
+```
+
+Lo zip contiene una sola cartella `piazza-in-festa/`, ed e' quello che si carica sia su WordPress.org sia in "Aggiungi plugin > Carica plugin".
+
+## Traduzioni
+
+Le stringhe sorgente sono in inglese (e' la lingua della directory), l'italiano e' in `languages/`. Le stringhe PHP stanno nel `.mo`, quelle dell'editor in un `.json` a parte perche' vivono in JavaScript. Dopo aver toccato le stringhe:
+
+```bash
+msgfmt languages/piazza-in-festa-it_IT.po -o languages/piazza-in-festa-it_IT.mo
+```
+
+e rigenera i due `.json` (stesso contenuto, due nomi: WordPress cerca prima per handle dello script, poi per md5 del percorso).
+
+## Pubblicazione su WordPress.org
+
+Lo slug lo decide il campo `Plugin Name` alla prima revisione e **non si cambia piu'** dopo l'approvazione. Dopo il via libera si lavora su SVN: `trunk/` piu' un tag per versione, e `.wordpress-org/` per icona e banner.