====== WvdS.DokuWiki.OpenGraph Plugin ======

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

----

===== Definizione =====

Il plugin **wvdsopengraph** genera meta tag Open Graph e Twitter Card per una visualizzazione ottimale nella condivisione sui social media. Supporta contenuti multilingue e override specifici per pagina.

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

  * **Condivisione social media** - Anteprima ottimizzata su Facebook, LinkedIn, Twitter
  * **Miglioramento SEO** - Metadati strutturati per motori di ricerca
  * **Wiki multilingue** - Rilevamento automatico lingua per meta tag
  * **Branding** - Aspetto uniforme nei link condivisi

----

===== Sintassi =====

<code>
<og>
title = Titolo pagina
description = Descrizione
image = :wiki:logo.png
type = article
</og>
</code>

==== Parametri ====

^ Parametro ^ Tipo ^ Default ^ Descrizione ^
| ''title'' | string | //(Titolo pagina)// | Titolo per social media |
| ''description'' | string | //(Tagline)// | Descrizione (max. 160 caratteri) |
| ''image'' | string | //(Immagine default)// | Percorso DokuWiki Media |
| ''type'' | string | article | Tipo Open Graph |

----

===== Valori multilingue =====

Tutti i valori supportano il formato pipe:

<code>
<og>
title = de:Kryptographie|en:Cryptography|it:Crittografia
description = de:Einführung|en:Introduction|it:Introduzione
</og>
</code>

Il plugin rileva automaticamente la lingua dal percorso del namespace.

----

===== Tag automatici =====

Senza blocco ''<og>'' il plugin genera automaticamente:

^ Tag ^ Sorgente ^
| ''og:title'' | Titolo pagina (H1) |
| ''og:description'' | Tagline wiki o defaultDescription |
| ''og:url'' | URL pagina corrente |
| ''og:site_name'' | Titolo wiki |
| ''og:type'' | article |
| ''og:image'' | defaultImage dalla configurazione |

----

===== Esempi =====

==== Esempio 1: Override semplice ====

**Requisito:** Meta tag personalizzati per una pagina progetto.

<code>
<og>
title = Il mio progetto
description = Una descrizione completa del progetto
image = :progetti:banner.jpg
</og>

====== Il mio progetto ======

Contenuto pagina...
</code>

**Risultato:**
  * Titolo Open Graph: "Il mio progetto"
  * Descrizione: "Una descrizione completa del progetto"
  * Immagine anteprima: progetti:banner.jpg

==== Esempio 2: Multilingue ====

**Requisito:** Titoli e descrizioni diverse per ogni lingua.

<code>
<og>
title = de:OpenSSL Dokumentation|en:OpenSSL Documentation|it:Documentazione OpenSSL
description = de:Umfassende Anleitung|en:Comprehensive guide|it:Guida completa
image = :crypto:openssl-banner.png
</og>
</code>

**Risultato (pagina italiana):**
  * Titolo: "Documentazione OpenSSL"
  * Descrizione: "Guida completa"

==== Esempio 3: Configurazione minimale ====

**Requisito:** Override solo dell'immagine, resto automatico.

<code>
<og>
image = :articoli:feature-image.jpg
</og>
</code>

**Risultato:**
  * Titolo, descrizione, URL: generati automaticamente
  * Immagine: articoli:feature-image.jpg

----

===== Tag HTML generati =====

<code html>
<!-- Open Graph -->
<meta property="og:title" content="Documentazione OpenSSL">
<meta property="og:description" content="Guida completa">
<meta property="og:image" content="https://example.com/lib/exe/fetch.php?media=crypto:openssl-banner.png">
<meta property="og:url" content="https://example.com/doku.php?id=it:crypto:openssl">
<meta property="og:site_name" content="Base di conoscenza">
<meta property="og:type" content="article">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Documentazione OpenSSL">
<meta name="twitter:description" content="Guida completa">
<meta name="twitter:image" content="https://example.com/lib/exe/fetch.php?media=crypto:openssl-banner.png">
</code>

----

===== Funzionamento =====

==== Pipeline di elaborazione ====

<code>
1. Analisi pagina
   └── Cerca blocco <og>...</og> all'inizio della pagina

2. Estrazione parametri
   └── Parsa coppie chiave = valore
   └── Riconosce formato de:X|en:Y

3. Rilevamento lingua
   └── Determina lingua dal namespace
   └── Estrae valore corrispondente

4. Generazione meta tag
   └── Crea tag og:* e twitter:*
   └── Inserisce in <head>
</code>

==== Risoluzione URL immagine ====

Il plugin converte DokuWiki Media-ID in URL completi:

^ Input ^ Output ^
| '':wiki:logo.png'' | ''https://domain/lib/exe/fetch.php?media=wiki:logo.png'' |
| '':progetti:banner.jpg'' | ''https://domain/lib/exe/fetch.php?media=progetti:banner.jpg'' |

----

===== Configurazione =====

==== Impostazioni amministratore ====

Tramite **Admin → Configurazione → wvdsopengraph**:

^ Impostazione ^ Tipo ^ Default ^ Descrizione ^
| ''defaultDescription'' | Testo | //(Tagline)// | Descrizione predefinita (multilingue) |
| ''defaultImage'' | Testo | //(vuoto)// | Media-ID immagine predefinita |
| ''twitterSite'' | Testo | //(vuoto)// | @username Twitter per twitter:site |
| ''enableTwitterCards'' | On/Off | On | Genera tag Twitter Card |

==== Configurazione consigliata ====

<code>
defaultDescription = de:Wissensdatenbank für Entwickler|en:Knowledge base for developers|it:Base di conoscenza per sviluppatori
defaultImage = :wiki:og-default.png
twitterSite = @miaazienda
enableTwitterCards = 1
</code>

----

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

^ Scenario ^ Comportamento ^
| Nessun blocco <og> | Usa valori automatici |
| Immagine non trovata | Usa defaultImage |
| Lingua non valida | Fallback al primo valore |
| Valore vuoto | Tag non viene generato |

----

===== Best practice =====

  * **Descrizione:** Massimo 160 caratteri
  * **Titolo:** Massimo 60 caratteri
  * **Immagine:** Almeno 1200×630 pixel per visualizzazione ottimale
  * **Formato:** JPEG o PNG per le immagini

==== Requisiti immagini ====

^ Piattaforma ^ Dimensione consigliata ^ Proporzioni ^
| Facebook | 1200×630 px | 1.91:1 |
| Twitter | 1200×600 px | 2:1 |
| LinkedIn | 1200×627 px | 1.91:1 |

----

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

^ Versione ^ Data ^ Modifiche ^
| 1.0.0 | 2025-01-06 | Prima pubblicazione |

----

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

  * [[.:wvdsi18n]] - Traduzioni multilingue
  * [[.:wvdsimage]] - Ottimizzazione immagini
  * [[https://ogp.me/|Open Graph Protocol]]
  * [[https://developer.twitter.com/en/docs/twitter-for-websites/cards|Twitter Cards]]

----

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

==== Classe: syntax_plugin_wvdsopengraph ====

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

^ Metodo ^ Descrizione ^
| ''getType()'' | Restituisce ''substition'' |
| ''getSort()'' | Restituisce ''50'' (anticipato) |
| ''handle($match, ...)'' | Parsa blocco <og> |
| ''render($mode, ...)'' | Nessun output (solo meta tag) |

==== Classe: action_plugin_wvdsopengraph ====

**File:** ''lib/plugins/wvdsopengraph/action.php''

^ Metodo ^ Descrizione ^
| ''register()'' | Registra evento TPL_METAHEADER_OUTPUT |
| ''addMetaTags()'' | Aggiunge meta tag nell'header |

==== Tipi Open Graph supportati ====

^ Tipo ^ Utilizzo ^
| ''article'' | Post blog, documentazione (default) |
| ''website'' | Pagine principali, homepage |
| ''profile'' | Profili utente |
| ''book'' | Libri, pubblicazioni |

----

<wvds:audit stack="doku" title="wvdsopengraph 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~~