====== WvdS.DokuWiki.Snippet Plugin ======

**Plugin:** wvdssnippet\\
**Versione:** 2.0.0\\
**Namespace:** ''lib/plugins/wvdssnippet/''\\
**Autore:** Wolfgang van der Stille <zeljko.petrusic@outlook.de>\\
**Licenza:** GPL 2

----

===== Definizione =====

Il plugin **wvdssnippet** consente blocchi HTML riutilizzabili (snippet) con gestione centralizzata. Fornisce un'alternativa sicura a ''htmlok'' e permette la combinazione di HTML con traduzioni multilingue.

===== Casi d'uso =====

  * **Menu di navigazione** - Gestione centralizzata di menu principale e sidebar
  * **Elementi ripetitivi** - Footer, intestazioni, pulsanti
  * **Componenti localizzati** - HTML con supporto multilingue integrato
  * **Blocchi widget** - Link social media, box di contatto
  * **Estensioni template** - Strutture HTML complesse nelle pagine wiki

----

===== Sintassi =====

<code>
{{wvds:snippet>key}}
</code>

==== Parametri ====

^ Parametro ^ Tipo ^ Descrizione ^
| **key** | string | Nome file dello snippet (senza estensione .html) |

----

===== Definizione snippet =====

==== Archiviazione basata su file ====

Gli snippet vengono salvati come singoli file HTML nella directory del plugin:

**Directory:** ''lib/plugins/wvdssnippet/snippets/''

**Formato file:** ''{key}.html''

<code>
lib/plugins/wvdssnippet/snippets/
├── main_menu.html
├── go_back.html
├── social_links.html
├── contact_box.html
└── footer.html
</code>

==== Regole ====

^ Regola ^ Descrizione ^
| Nome file | Corrisponde alla chiave snippet (es. ''main_menu.html'' → ''<nowiki>{{wvds:snippet>main_menu}}</nowiki>'') |
| Contenuto | Codice HTML completo nel file |
| Multilinea | Numero arbitrario di righe possibile |
| wvdsi18n | I tag ''<nowiki>{{wvds:i18n>...}}</nowiki>'' vengono elaborati |
| HTML | HTML completo consentito |

==== Contenuti consentiti ====

^ Tipo contenuto ^ Esempio ^
| Tag HTML | ''<div>'', ''<nav>'', ''<ul>'', ecc. |
| Classi CSS | ''class="my-class"'' |
| Stili inline | ''style="color: red;"'' |
| JavaScript | ''onclick="..."'' (con cautela) |
| Font Awesome | ''<i class="fa fa-home"></i>'' |
| Tag wvdsi18n | ''<nowiki>{{wvds:i18n>menu_home}}</nowiki>'' |
| Traduzioni inline | ''<nowiki>{{wvds:i18n>de:Text|en:Text}}</nowiki>'' |

----

===== Configurazione =====

==== Impostazioni amministratore ====

Tramite **Admin → Configurazione → wvdssnippet**:

^ Impostazione ^ Tipo ^ Default ^ Descrizione ^
| ''allowPhp'' | On/Off | Off | Consenti codice PHP negli snippet (rischio sicurezza!) |

==== Interfaccia amministratore ====

Tramite **Admin → WvdS Snippets** è possibile gestire direttamente gli snippet:

^ Funzione ^ Descrizione ^
| Lista snippet | Mostra tutti gli snippet disponibili con anteprima |
| Modifica snippet | Modifica contenuto HTML nell'editor textarea |
| Nuovo snippet | Crea nuova chiave snippet |
| Elimina snippet | Rimuovi file snippet (con conferma) |

==== Esempio snippet (main_menu.html) ====

**File:** ''lib/plugins/wvdssnippet/snippets/main_menu.html''

<code html>
<nav class="main-menu">
    <ul class="menu-list">
        <li class="menu-item"><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li class="menu-item"><a href="?id=docs">{{wvds:i18n>menu_docs}}</a></li>
        <li class="menu-item"><a href="?id=contact">{{wvds:i18n>menu_contact}}</a></li>
    </ul>
</nav>
</code>

==== Esempio snippet (go_back.html) ====

**File:** ''lib/plugins/wvdssnippet/snippets/go_back.html''

<code html>
<div class="go-back">
    <i class="fa fa-arrow-left"></i>
    <a href="javascript:history.back()">{{wvds:i18n>menu_back}}</a>
</div>
</code>

----

===== Esempi =====

==== Esempio 1: Menu principale nella sidebar ====

**Requisito:** Menu di navigazione centrale per tutte le pagine.

**File snippet:** ''lib/plugins/wvdssnippet/snippets/main_menu.html''
<code html>
<nav class="main-menu">
    <ul>
        <li><a href="?id=start">{{wvds:i18n>menu_home}}</a></li>
        <li><a href="?id=it:docs:start">{{wvds:i18n>menu_docs}}</a></li>
    </ul>
</nav>
</code>

**Utilizzo in sidebar.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>main_menu}}
</code>

**Risultato:**
  * Il menu appare su tutte le pagine
  * Le traduzioni vengono applicate automaticamente
  * Modifiche tramite interfaccia admin o direttamente nel file

==== Esempio 2: Link indietro con icona ====

**Requisito:** Link "indietro" uniforme nei sotto-namespace.

**File snippet:** ''lib/plugins/wvdssnippet/snippets/go_back.html''
<code html>
<div class="go-back" style="margin-bottom: 1em;">
    <i class="fa fa-arrow-left" style="margin-right: 0.5em;"></i>
    <a href="javascript:history.back()">{{wvds:i18n>de:Zurück|en:Back|it:Indietro}}</a>
</div>
</code>

**Utilizzo in sidebar1.txt:**
<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== Esempio 3: Box contatto ====

**Requisito:** Informazioni di contatto riutilizzabili.

**File snippet:** ''lib/plugins/wvdssnippet/snippets/contact_box.html''
<code html>
<div class="contact-box">
    <h4>{{wvds:i18n>de:Kontakt|en:Contact|it:Contatto}}</h4>
    <p>
        <i class="fa fa-envelope"></i> info@example.com<br>
        <i class="fa fa-phone"></i> +49 123 456789
    </p>
</div>
</code>

**Utilizzo:**
<code>
{{wvds:snippet>contact_box}}
</code>

==== Esempio 4: Footer multilingue ====

**Requisito:** Footer con anno dinamico e link localizzati.

**File snippet:** ''lib/plugins/wvdssnippet/snippets/footer.html''
<code html>
<footer class="site-footer">
    <div class="footer-content">
        <p>&copy; 2026 {{wvds:i18n>conf:title}}</p>
        <nav class="footer-links">
            <a href="?id=impressum">{{wvds:i18n>menu_imprint}}</a> |
            <a href="?id=datenschutz">{{wvds:i18n>menu_privacy}}</a> |
            <a href="?id=sitemap">{{wvds:i18n>menu_sitemap}}</a>
        </nav>
    </div>
</footer>
</code>

----

===== Funzionamento =====

==== Pipeline di elaborazione ====

<code>
1. Riconoscimento sintassi
   └── Trova tutti i tag {{wvds:snippet>...}}

2. Ricerca snippet
   └── Cerca file snippet: snippets/{key}.html
   └── Carica contenuto HTML dal file

3. Elaborazione wvdsi18n
   └── Sostituisce i tag {{wvds:i18n>...}} nello snippet
   └── Applica la lingua corrente

4. Output HTML
   └── Inserisce codice HTML elaborato nella pagina
   └── Nessun escaping aggiuntivo (Raw HTML)
</code>

==== Ordine di elaborazione ====

^ Priorità ^ Plugin ^ Valore Sort ^
| 1 | wvdsi18n | 305 |
| 2 | wvdssnippet | 310 |
| 3 | wvdsimage | 319 |

<note>
wvdsi18n viene elaborato **prima** di wvdssnippet affinché le traduzioni negli snippet funzionino.
</note>

----

===== Integrazione =====

==== Con wvdsi18n ====

Gli snippet supportano tutte le sintassi wvdsi18n:

**File:** ''lib/plugins/wvdssnippet/snippets/multilingual_block.html''
<code html>
<div class="info">
    {{wvds:i18n>greeting}}
    {{wvds:i18n>de:Hallo|en:Hello|it:Ciao}}
    {{wvds:lang:en>english_only_text}}
</div>
</code>

==== Con wvdsacmenu ====

Struttura tipica della sidebar:

<code>
~~NOCACHE~~
{{wvds:snippet>go_back}}
{{wvds:acmenu}}
</code>

==== Con wvdsimage ====

Gli snippet possono contenere anche immagini:

**File:** ''lib/plugins/wvdssnippet/snippets/logo_block.html''
<code html>
<div class="logo">
    {{wvds:image>wiki:logo.png|width=100%|maxwidth=200}}
</div>
</code>

----

===== Sicurezza =====

==== Vantaggi rispetto a htmlok ====

^ Aspetto ^ htmlok ^ wvdssnippet ^
| Input HTML | Libero in ogni pagina | Solo tramite Admin |
| Rischio sicurezza | Alto (XSS, Injection) | Basso (controllato) |
| Audit | Difficile (disperso) | Semplice (centralizzato) |
| Permessi utente | Chiunque con modifica | Solo amministratori |

==== Best practice ====

  * **JavaScript minimale** - Solo se assolutamente necessario
  * **Link esterni con target="_blank"** - Sicurezza con ''rel="noopener"''
  * **Nessun dato sensibile** - Nessuna chiave API, password negli snippet
  * **Nomi univoci** - Scegliere nomi snippet descrittivi

----

===== Gestione errori =====

==== Comportamento in caso di errori ====

^ Scenario ^ Comportamento ^
| Snippet non trovato | Restituisce ''[snippet_name not found]'' |
| Snippet vuoto | Non restituisce nulla |
| Formato non valido | Ignora righe non valide |
| Errore wvdsi18n | Restituisce chiave (fallback) |

==== Debugging ====

In caso di problemi verificare:

  * Il nome dello snippet è scritto correttamente?
  * Esiste il file ''lib/plugins/wvdssnippet/snippets/{key}.html''?
  * Il file ha l'estensione ''.html''?
  * È impostato ''~~NOCACHE~~'' per contenuti dinamici?
  * I tag wvdsi18n funzionano singolarmente?

----

===== Performance =====

==== Raccomandazioni ====

| Scenario | Raccomandazione |
| Snippet statici | Lasciare cache attivata |
| Snippet dinamici (lingua) | Usare ''~~NOCACHE~~'' |
| Snippet grandi | Dividere in più piccoli |
| Molti snippet | Non più di 50 definiti |

==== Caching ====

<note tip>
Le pagine con snippet dipendenti dalla lingua dovrebbero avere ''~~NOCACHE~~'' all'inizio per visualizzare la versione linguistica corretta.
</note>

----

===== Note sulla versione =====

^ Versione ^ Data ^ Modifiche ^
| 2.1.0 | 2026-01-26 | Interfaccia admin, archiviazione basata su file (file HTML) |
| 2.0.0 | 2026-01-06 | Rinominato da wvdschunk a wvdssnippet |
| 1.0.0 | 2025-01-06 | Prima pubblicazione |

----

===== Vedi anche =====

  * [[.:wvdsi18n]] - Traduzioni multilingue
  * [[.:wvdsacmenu]] - Menu ad accordion
  * [[.:wvdsimage]] - Immagini responsive
  * [[.:flat]] - Estensioni template

----

===== Riferimento tecnico =====

==== Classe: syntax_plugin_wvdssnippet ====

**File:** ''lib/plugins/wvdssnippet/syntax.php''

^ Metodo ^ Descrizione ^
| ''getType()'' | Restituisce ''substition'' |
| ''getSort()'' | Restituisce ''310'' (dopo wvdsi18n) |
| ''connectTo($mode)'' | Registra pattern ''\\{\\{wvds:snippet>[^}]+\\}\\}'' |
| ''handle($match, ...)'' | Estrae nome snippet |
| ''render($mode, ...)'' | Restituisce contenuto HTML |

==== Classe: helper_plugin_wvdssnippet ====

**File:** ''lib/plugins/wvdssnippet/helper.php''

^ Metodo ^ Parametri ^ Ritorno ^ Descrizione ^
| ''getSnippets()'' | - | array | Carica tutti gli snippet dalla directory snippets |
| ''get()'' | $name | string | Restituisce contenuto snippet |

==== Classe: admin_plugin_wvdssnippet ====

**File:** ''lib/plugins/wvdssnippet/admin.php''

^ Metodo ^ Descrizione ^
| ''html()'' | Renderizza interfaccia admin |
| ''handle()'' | Elabora azioni form (salva, elimina, crea) |

==== Struttura file ====

<code>
lib/plugins/wvdssnippet/
├── admin.php          → Interfaccia admin
├── helper.php         → Caricamento ed elaborazione snippet
├── syntax.php         → Wiki syntax parser
├── conf/
│   ├── default.php    → Impostazioni predefinite
│   └── metadata.php   → Metadati Admin UI
└── snippets/          → File HTML snippet
    ├── main_menu.html
    ├── go_back.html
    └── ...
</code>

----

<wvds:audit stack="doku" title="wvdssnippet Plugin">
  <wvds:include ref="code:qualitaet" critical="true">[x][x][x][x]</wvds:include>
  <wvds:include ref="stacks:dokuwiki-php">[x][x][x][x][x]</wvds:include>
  <wvds:include ref="sicherheit:kritis" critical="true">[x][x][x][-][-]</wvds:include>
</wvds:audit>

~~DISCUSSION~~