Anteprima alla condivisione — riferimento tecnico
Questa pagina descrive la marcatura, l’origine dei valori, l’output, la superficie di amministrazione e il punto di estensione. Per un’introduzione vedi Panoramica.
Il blocco su una pagina
Il componente sintattico riconosce due notazioni equivalenti dello stesso blocco; le valuta lo stesso lettore. Il blocco non produce alcun output visibile — viene letto durante la costruzione dei metadati della pagina e agisce solo nell’intestazione.
<og> title = ... description = ... image = :wiki:logo.png type = article </og>
%%{{wk:og>title=...|description=...|image=:wiki:logo.png}}%%
wkcore e separa le sue coppie con | anziché con interruzioni di riga. Viene registrata solo se wkcore è installato; in sua assenza resta valida solo la prima forma.
Chiavi riconosciute
| Chiave | Diventa | Predefinito se la pagina non dice nulla |
|---|---|---|
title | og:title, twitter:title | titolo della pagina come lo determina DokuWiki |
description | og:description, twitter:description | catena di sunto, testo predefinito e motto |
image | og:image, twitter:image | impostazione defaultImage |
url | og:url | indirizzo assoluto della pagina |
type | og:type | impostazione defaultType |
site_name | og:site_name | impostazione siteName, altrimenti il titolo del wiki |
type è un caso particolare: la marcatura accetta qualsiasi valore, anche profile o book; l’impostazione per il tipo predefinito conosce solo article e website.
Valori multilingue
Ogni valore può portare più lingue in un solo campo, separate da |, ciascuna come codice di due lettere e due punti. Lo stesso vale per le impostazioni defaultDescription, defaultImage e siteName.
<og> title = de:Kryptographie|en:Cryptography|sl:Kriptografija </og>
Origine di ogni valore
| Stadio | Fonte | Che cosa contribuisce |
|---|---|---|
| 1 | Predefiniti | impostazioni del pacchetto, titolo del wiki, titolo e indirizzo della pagina, sunto |
| 2 | Pagina | il blocco di questa pagina |
| 3 | Pacchetti che contribuiscono | l’evento WKOPENGRAPH_VALUES |
I valori impostati più tardi vincono, quelli vuoti non sovrascrivono mai. Viene consegnato ciò che non è vuoto. Un valore vuoto non produce alcun tag — ed è voluto: un tag vuoto consegnato viene letto come la promessa che la pagina non ha descrizione, invece di indurre a cercarne una.
La catena della descrizione
La descrizione è l’unico valore il cui predefinito è a sua volta una catena: prima il sunto della pagina, altrimenti l’impostazione defaultDescription, altrimenti il motto del wiki.
L’ordine è il punto. Il sunto viene per primo perché è l’unico a descrivere la pagina condivisa; testo predefinito e motto descrivono il wiki e sono uguali su ogni pagina. Senza quel primo stadio il caso più frequente — una pagina senza blocco proprio — non consegnerebbe alcuna descrizione.
Il sunto viene troncato a 200 caratteri su un confine di parola. Il valore sta deliberatamente tra i circa 160 caratteri mostrati dai motori di ricerca e i circa 300 accettati dai lettori Open Graph — così un solo testo serve a entrambi, senza doverne mantenere due.
Gli identificatori delle immagini vengono risolti
Un valore di immagine che inizia con : è un identificatore di file DokuWiki, non un indirizzo pronto. Viene tradotto in un indirizzo assoluto prima della consegna — una rete che recupera l’anteprima non ha contesto wiki e non potrebbe risolvere un identificatore.
Meta tag generati
Vengono consegnati og:title, og:description, og:image, og:url, og:type e og:site_name, oltre agli equivalenti twitter: per titolo, descrizione e immagine. Ogni tag solo se il suo valore non è vuoto.
Schermata di amministrazione
La schermata si trova in ?do=admin&page=wkopengraph. Mostra i valori predefiniti con il loro effetto, offre il blocco di una pagina come modulo e verifica le immagini di anteprima.
Che cosa fa il salvataggio alla configurazione
I valori predefiniti risiedono nella configurazione del wiki. Il modulo li scrive attraverso il normale percorso del gestore della configurazione — non esiste un secondo archivio né un file conosciuto solo da questo pacchetto.
Valori predefiniti
Le impostazioni regolano il testo predefinito, l’immagine predefinita, il tipo predefinito, il nome del sito e le soglie della verifica delle immagini. Un valore non valido non viene assunto; vale allora quello predefinito.
Verifica delle immagini di anteprima
La verifica segnala le immagini di anteprima troppo piccole o con proporzioni sfavorevoli. È una segnalazione, non un blocco: un’immagine non viene mai trattenuta, solo nominata.
Punto di estensione
Altri pacchetti contribuiscono valori propri attraverso l’evento WKOPENGRAPH_VALUES. È lo stadio 3 dell’origine. Chi contribuisce fornisce solo valori; il vocabolario, l’escaping e la decisione su quali tag esistano restano a questo pacchetto — due pacchetti che scrivono nella stessa intestazione produrrebbero proprietà duplicate, che i lettori risolvono in modo incoerente. Così, per esempio, Blog alimenta ogni articolo con i propri valori.
Comportamento nei casi particolari
- Una pagina senza blocco riceve comunque tutti e sei i valori — dai predefiniti.
- Un valore vuoto nel blocco non sovrascrive; lascia in piedi il predefinito.
- Una chiave sconosciuta è valida e senza effetto.
- Senza
wkcorela seconda notazione non esiste; la prima resta.
Raccomandazioni per le immagini di anteprima
Un’immagine di anteprima dovrebbe avere almeno 1200 × 630 punti e proporzioni vicine a 1,91:1 — il formato che le reti diffuse mostrano senza ritaglio. Le immagini più piccole vengono consegnate, ma spesso ingrandite o omesse.