EG Fediverso Box

Plugin WordPress per mostrare un box che permette agli utenti di seguire l'autore nel Fediverso (Mastodon, Pleroma, Pixelfed, ecc.) con pannello amministrazione completo e supporto i18n.

---

Novità Versione 3.0.1

• Supporto internazionalizzazione (i18n) completo
• Traduzioni italiano e inglese incluse
• Interfaccia admin ripulita (rimossi box informativi inutili)
• Tutte le stringhe utente ora traducibili
• File .pot, .po per nuove traduzioni

---

Caratteristiche

• Privacy-First - Nessun tracker o servizio esterno
• Fediverso-Native - Supporto completo ActivityPub (Mastodon, Pleroma, Pixelfed, ecc.)
• Multilingua - Supporto i18n con italiano e inglese inclusi
• Pannello Amministrazione - Configurazione completa da interfaccia WordPress
• Validazione Configurazione - Controlli per evitare errori di setup
• Inserimento Dinamico - JavaScript compatibile con DOM dinamico
• Responsive - Design moderno e mobile-friendly
• Leggero - CSS e JS minimali, zero dipendenze
• Debug Mode - Console logging attivabile per troubleshooting
• Open Source - Codice completamente trasparente e verificabile
• Isolato - Non interferisce con altri plugin o temi
• Multiuso - Supporta shortcode, funzione PHP e inserimento dinamico

---

Installazione

Via WordPress (Caricamento ZIP)

1. Scarica l'ultima versione: eg-fediverso-box.zip
2. Vai in WordPress → Plugin → Aggiungi nuovo → Carica plugin
3. Seleziona il file ZIP scaricato
4. Clicca "Installa ora" → "Attiva plugin"
5. Vai in Impostazioni → EG Fediverso Box e configura l'handle (OBBLIGATORIO)

Via FTP

1. Scarica l'ultima versione: eg-fediverso-box.zip
2. Estrai la cartella eg-fediverso-box
3. Carica in /wp-content/plugins/ via FTP
4. Attiva il plugin dal pannello WordPress
5. Vai in Impostazioni → EG Fediverso Box e configura l'handle (OBBLIGATORIO)

---

Configurazione

Pannello Amministrazione

Posizione: Impostazioni → EG Fediverso Box

Il plugin richiede configurazione obbligatoria tramite pannello amministrazione. Una volta attivato, apparirà un banner di avviso finché non configuri almeno l'handle del Fediverso.

Campi Disponibili:

1. Handle Account Fediverso (OBBLIGATORIO)

   • Il tuo handle completo del Fediverso
   • Formato: nomeutente@istanza.dominio
   • Esempio: emanuelegori@emanuelegori.uno
   • Senza questo campo, gli utenti non potranno seguirti correttamente

2. Link "Non conosci il Fediverso?" (opzionale)

   • URL informativo sul Fediverso
   • Default: https://fediverso.info/

3. Link Registrazione Account (opzionale)

   • Dove gli utenti possono creare un account
   • Default: https://mastodon.uno/auth/sign_up
   • Alternativa: https://joinmastodon.org

4. Testo Link Registrazione (opzionale)

   • Personalizza il testo del link
   • Default: "Crea un profilo gratuito"

Validazione:

Il plugin valida che l'handle sia nel formato corretto e non permette di salvare impostazioni incomplete. Se provi a salvare senza handle, riceverai un errore e le impostazioni non verranno applicate.

---

Utilizzo

Una volta configurato il plugin, puoi inserire il box nei tuoi articoli.

Tramite Shortcode (raccomandato)

Inserisci nel contenuto dell'articolo:

[eg_fediverso_box]

Tramite PHP nel tema

Inserisci nei file template del tema (es. single.php):

<?php if (function_exists('eg_fediverso_box')) { eg_fediverso_box(); } ?>

Inserimento Dinamico (Custom Plugin)

Il plugin è compatibile con sistemi di inserimento dinamico nel DOM grazie alla funzione globale window.initEGFediversoBox().

---

Internazionalizzazione

Lingue Incluse

• Italiano (it_IT) - Traduzione completa
• Inglese (en_US) - Traduzione completa

Cambiare Lingua

WordPress seleziona automaticamente la lingua in base alle impostazioni:

1. Vai in Impostazioni → Generali
2. Seleziona "Lingua del sito"
3. Il plugin si adatta automaticamente

Aggiungere Nuove Traduzioni

File necessari nella cartella /languages:

• eg-fediverso-box.pot - Template
• eg-fediverso-box-{LOCALE}.po - Traduzione editabile
• eg-fediverso-box-{LOCALE}.mo - Traduzione compilata

---

Badge Informativo

Il box include un badge "?" in basso a destra che rimanda al repository del plugin. Questo permette agli utenti curiosi di scoprire come funziona il plugin e conoscere Forgejo.

---

Come Funziona

1. L'Utente Inserisce la Propria Istanza

L'utente inserisce solo il dominio della propria istanza Fediverso (es: mastodon.uno).

2. Validazione Input

Il plugin valida che l'input sia un dominio valido:

• Solo caratteri alfanumerici, punti e trattini
• Deve contenere almeno un TLD valido (.com, .it, .social, ecc.)

3. Apertura URL Authorize Interaction

Il plugin costruisce l'URL standard ActivityPub per seguire un account:

https://[istanza-utente]/authorize_interaction?uri=[handle-autore]

Esempio:

https://mastodon.uno/authorize_interaction?uri=emanuelegori@emanuelegori.uno

4. L'Utente Segue dall'Istanza

L'utente viene portato sulla propria istanza Mastodon/Pleroma/Pixelfed dove può confermare di voler seguire l'autore.

---

Debug Mode

Attivazione

Modifica in eg-fediverso-box.php:

define('EG_FEDIVERSO_BOX_DEBUG', true);

Cosa Mostra

Con debug attivo, il plugin logga in console:

• Inizializzazione del plugin
• Stato elementi DOM
• URL generati per authorize_interaction
• Eventuali errori o avvisi

Disattivazione in Produzione

IMPORTANTE: In produzione lascia sempre:

define('EG_FEDIVERSO_BOX_DEBUG', false);

---

Personalizzazione

Cambiare Colori

Modifica eg-fediverso-box.css:

/* Colore principale */
.eg-fediverso-box {
    border-left: 4px solid #6364FF;
}

.eg-fediverso-box #egFediFollowBtn {
    background-color: #6364FF;
}

.eg-fediverso-box #egFediFollowBtn:hover {
    background-color: #4F50E0;
}

Cambiare Testi

I testi principali del box sono configurabili dal pannello amministrazione. Per modificare altri testi statici, usa i file di traduzione in /languages.

---

Aggiornamenti

Questo plugin NON è disponibile su WordPress.org Store, quindi NON si aggiorna tramite il sistema standard di WordPress. Hai due opzioni:

Manuale

1. Scarica la nuova versione: eg-fediverso-box.zip
2. Disattiva il plugin in WordPress
3. Elimina la vecchia cartella /wp-content/plugins/eg-fediverso-box/
4. Carica la nuova versione (ZIP o FTP)
5. Riattiva il plugin

Nota: Le configurazioni salvate nel database NON vengono perse

Automatico via Git Updater (Raccomandato)

Setup iniziale:

1. Scarica Git Updater (gratuito, nessun abbonamento richiesto)
2. Installa Git Updater in WordPress
3. Nessuna configurazione richiesta (repository pubblico)

Funzionamento:

• Git Updater controlla periodicamente nuove release su Gitea
• Le notifiche appaiono in WordPress > Dashboard > Aggiornamenti
• Click "Aggiorna" per installare automaticamente la nuova versione
• Le configurazioni vengono mantenute

---

Requisiti

• WordPress: 5.0 o superiore
• PHP: 7.2 o superiore
• Account Fediverso: Per configurare il tuo handle

---

Compatibilità Fediverso

Il plugin dovrebbe essere teoricamente compatibile con le piattaforme ActivityPub che supportano l'endpoint /authorize_interaction:

• Mastodon (testato)
• Pleroma (compatibilità teorica, non testato)
• Pixelfed (compatibilità teorica, non testato)
• Misskey (compatibilità teorica, non testato)
• Akkoma (fork di Pleroma, compatibilità teorica, non testato)
• GoToSocial (compatibilità teorica, non testato)
• Altre piattaforme ActivityPub (non testate)

L'importante è che la piattaforma supporti l'endpoint /authorize_interaction. Se la tua piattaforma lo supporta, il plugin dovrebbe funzionare correttamente.

---

Troubleshooting

Il Box Non Appare

1. Verifica che il plugin sia attivo
2. Controlla di aver configurato l'handle in Impostazioni → EG Fediverso Box
3. Verifica lo shortcode: [eg_fediverso_box] (con underscore!)
4. Svuota cache browser e sito
5. Attiva debug mode e controlla console browser

Banner "Configurazione Richiesta"

Se vedi il banner rosso in admin:

1. Vai in Impostazioni → EG Fediverso Box
2. Inserisci il tuo handle completo (es: tuonome@mastodon.uno)
3. Salva le impostazioni
4. Il banner scomparirà automaticamente

"Nessun Account"

L'utente deve:

1. Cliccare sul link "Crea un profilo gratuito"
2. Registrarsi su un'istanza Mastodon (o altra piattaforma Fediverso)
3. Tornare sul tuo sito e inserire l'istanza

JavaScript Non Funziona

1. Apri console browser (F12)
2. Attiva debug mode
3. Controlla errori JavaScript
4. Verifica che non ci siano conflitti con altri plugin

Errore "Inserisci solo il dominio"

L'utente ha inserito caratteri non validi. Deve inserire solo:

• Dominio (es: mastodon.uno)
• NON inserire https://
• NON inserire @nomeutente

Il Form Non Invia

1. Attiva debug mode
2. Verifica console browser
3. Controlla che window.initEGFediversoBox() sia presente
4. Verifica compatibilità tema/page builder

---

Struttura del Repository

eg-fediverso-box/
├── eg-fediverso-box.php      # File principale del plugin
├── eg-fediverso-box.css      # Stili CSS
├── languages/                # Traduzioni
│   ├── eg-fediverso-box.pot  # Template traduzioni
│   ├── eg-fediverso-box-it_IT.po  # Italiano
│   ├── eg-fediverso-box-it_IT.mo  # Italiano (compilato)
│   ├── eg-fediverso-box-en_US.po  # Inglese
│   └── eg-fediverso-box-en_US.mo  # Inglese (compilato)
├── README.md                 # Questa documentazione
├── readme.txt                # Documentazione WordPress standard
├── CHANGELOG.md              # Storico versioni
├── LICENSE.md                # Licenza GPL v2 (inglese - ufficiale)
├── LICENSE.IT.md             # Licenza GPL v2 (italiano - traduzione)
├── .gitignore                # File da ignorare
└── .gitattributes            # Export pulito

---

Licenza

Questo plugin è rilasciato sotto licenza GPL v2 or later.

GNU General Public License v2

Questo programma è software libero; puoi redistribuirlo e/o modificarlo secondo i termini della GNU General Public License come pubblicata dalla Free Software Foundation; versione 2 della Licenza, o (a tua scelta) qualsiasi versione successiva.

Questo programma è distribuito nella speranza che sia utile, ma SENZA ALCUNA GARANZIA; senza neppure la garanzia implicita di COMMERCIABILITÀ o IDONEITÀ PER UN PARTICOLARE SCOPO. Vedi la Licenza Pubblica Generale GNU per maggiori dettagli.

Testo completo licenza:

• Inglese (ufficiale): LICENSE.md
• Italiano (traduzione): LICENSE.IT.md
• Online: https://www.gnu.org/licenses/gpl-2.0.html

---

Supporto

Documentazione

• README.md - Questa documentazione
• CHANGELOG.md - Storico versioni
• readme.txt - Documentazione WordPress standard

Contatti

• Website: https://emanuelegori.uno
• Repository: https://git.emanuelegori.uno/emanuelegori/eg-fediverso-box
• Email: Usa il form di contatto sul sito
• Fediverso: @emanuelegori@emanuelegori.uno

---

Autore

Emanuele Gori

• Website: emanuelegori.uno
• Git: git.emanuelegori.uno
• Blog: Informatica, libertà digitale e open source
• Fediverso: @emanuelegori@emanuelegori.uno

---

Statistiche

• Versione: 3.0.1
• Data Release: Gennaio 2025
• Licenza: GPL-2.0-or-later
• Compatibilità: WordPress 5.0+ | PHP 7.2+
• Piattaforme Fediverso: Mastodon (testato), altre piattaforme ActivityPub (compatibilità teorica)
• Lingue: Italiano, Inglese

---

Creato da Emanuele Gori Libertà digitale e Fediverso, sempre!