Un content manager accede al pannello di amministrazione, trova una pagina tra altre 50, apre l'editor, corregge un titolo, salva, torna al sito e aggiorna la scheda. Sei clic per una modifica. Per Grav CMS esiste una soluzione semplice: il plugin Editable with ContentTools integra un editor WYSIWYG direttamente nella pagina del sito. Apri la pagina, clicchi su «modifica», correggi il testo e lo salvi in un file Markdown senza entrare nel pannello di amministrazione.

Il plugin non viene aggiornato dal 2022 (l'autore ha ufficialmente interrotto il supporto), ma funziona in modo stabile su Grav 1.7 e copre lo scenario base della modifica di semplici pagine Markdown senza logica dinamica. L'installazione richiede cinque minuti e, una volta completata, modificare i testi dal frontend diventa molto più semplice.

Di seguito trovi una guida completa dall'installazione ai permessi di accesso, con un'analisi dei limiti e un'alternativa (Fred).

💡 Panoramica rapida:

• Installa il plugin tramite GPM o archivio zip e copia la configurazione.
• Imposta git-sync per versionare le modifiche su un repository (opzionale).
• Contrassegna le aree modificabili con lo shortcode editable usando nomi univoci.
• Assegna i permessi site.editable agli utenti frontend.
• Unisci le sessioni admin e frontend tramite session.split: false.
• Tieni presente il limite: solo Markdown semplice, niente Twig o contenuti dinamici.

Installazione: via GPM o manuale

Il plugin si installa tramite Grav Package Manager, il metodo standard per qualsiasi add-on in Grav:

1
bin/gpm install editable-contenttools

Esegui il comando dalla cartella root del sito (dove si trova bin/). GPM scaricherà l'ultima versione e la estrarrà in /user/plugins/editable-contenttools.

In alternativa, puoi installarlo manualmente: scarica l'archivio zip da GitHub, estrailo in /user/plugins/ e rinomina la cartella in editable-contenttools (senza il suffisso -master). La struttura dovrebbe apparire così: /user/plugins/editable-contenttools/editable-contenttools.php.

Copia la configurazione in una posizione sicura

Dopo l'installazione, assicurati di copiare il file di configurazione nella directory utente:

1
cp user/plugins/editable-contenttools/editable-contenttools.yaml user/config/plugins/editable-contenttools.yaml

Questo passaggio è importante: se le impostazioni restano nella cartella del plugin, verranno azzerate quando aggiorni tramite GPM. Un approccio alternativo è installare tramite il pannello di amministrazione di Grav (Plugin → Aggiungi): in questo caso il sistema crea automaticamente la configurazione in user/config/plugins/ e non serve alcuna copia manuale.

Configurazione: tre opzioni di configurazione

Il file editable-contenttools.yaml contiene tre parametri:

1
enabled: true
2
git-sync: false
3
git-sync-mode: foreground

enabled attiva il plugin. Senza enabled: true l'editor non apparirà sul frontend, anche se i permessi sono concessi. Il valore predefinito è true.

git-sync attiva la sincronizzazione con un repository Git dopo ogni salvataggio. Funziona solo se il plugin Git Sync è installato. Se il tuo sito risiede in Git e vuoi registrare ogni modifica nella cronologia, imposta questo parametro su true. Altrimenti lascialo su false.

git-sync-mode determina se attendere il completamento della sincronizzazione prima di restituire il controllo all'utente. foreground significa che il pulsante «Salva» si sblocca solo dopo che commit e push sono terminati. background funziona in modo asincrono, ma alcuni server Linux potrebbero avere problemi con i processi in background. Per la maggior parte degli scenari foreground è sufficiente.

Contrassegnare le aree modificabili: lo shortcode [editable]

Il plugin non rende l'intera pagina automaticamente modificabile. Definisci quali blocchi possono essere modificati usando lo shortcode [editable]:

1
[editable]
2
## Section heading
3
 
4
Text that can be edited from the frontend.
5
[/editable]

Una pagina può contenere un numero qualsiasi di queste aree. Ogni area deve avere un nome univoco, altrimenti ContentTools non saprà dove salvare le modifiche.

Il parametro name: univocità obbligatoria

Di default il plugin assegna nomi automaticamente (region-0, region-1 e così via), ma è meglio specificare manualmente nomi significativi:

1
[editable name="hero-block"]
2
## Main heading
3
 
4
Text that can be edited.
5
[/editable]

Al primo salvataggio tramite frontend, il plugin aggiungerà automaticamente un parametro name allo shortcode se mancante. In pratica è più comodo specificare i nomi già in fase di markup, perché semplifica il debug (puoi vedere quale blocco stai modificando negli strumenti di sviluppo del browser).

Dopo aver inserito il markup e salvato la pagina, visita il sito come utente con il permesso site.editable, clicca l'icona a forma di matita a sinistra e modifica il testo come faresti in un normale editor di testo. Tieni premuto Shift per circa tre secondi per evidenziare tutte le aree modificabili.

Puoi provarlo sul sito demo del plugin (il salvataggio è disabilitato, Grav 1.7.46).

Diritti di accesso: frontend e backend

Per vedere l'icona a forma di matita, un utente ha bisogno dei permessi di modifica. Le regole sono diverse per gli utenti frontend (content manager) e per gli utenti backend (amministratori).

Utenti frontend

L'utente deve poter effettuare il login tramite il plugin Grav Login o Private Grav. Poi aggiungi quanto segue al file account (user/accounts/username.yaml):

1
access:
2
  site:
3
    login: 'true'
4
    editable: 'true'

Senza il permesso site.editable l'icona a forma di matita non comparirà, anche se l'utente ha effettuato il login e possiede altri diritti.

Utenti backend (amministratori)

Di default Grav tiene separate le sessioni admin e frontend. Per consentire a un amministratore di modificare le pagine direttamente sul sito (senza accedere al pannello di amministrazione), imposta quanto segue in system.yaml (o tramite il pannello di amministrazione Configurazione → Sistema):

1
session:
2
  split: false

Questo unifica le sessioni: il login al pannello di amministrazione garantirà automaticamente l'accesso all'editor frontend. L'amministratore avrà anche bisogno del permesso admin.super o admin.pages nel proprio file account.

Se l'icona non compare dopo il login, verifica le impostazioni di caching dell'admin:

1
admin:
2
  super: 'true'
3
  login: 'true'
4
  cache: 'false'

Il parametro cache: false disabilita la cache per l'admin e può risolvere il problema dell'icona invisibile.

Limitazioni: cosa il plugin non può fare

Il plugin funziona esclusivamente con Markdown semplice. Questa è una limitazione architetturale, non un bug: ContentTools modifica l'HTML nel browser e il plugin converte l'HTML di nuovo in Markdown. In questo processo qualsiasi markup dinamico verrà corrotto. Non modificare il contenuto tramite ContentTools se:

• è assemblato da template Twig (ad esempio, pagine modulari: i blocchi figli sono inseriti dal genitore dinamicamente e il plugin non può vedere il loro sorgente);
• è iniettato da altri plugin (Page Inject e plugin simili inseriscono contenuti da altre pagine, il che è un processo unidirezionale);
• cambia via JavaScript nel browser (slider, accordion e altri elementi interattivi saranno convertiti in HTML statico);
• contiene tag speciali Grav Markdown (le immagini con parametri ?lightbox e ?resize saranno danneggiate durante la conversione HTML → Markdown, perché i parametri di elaborazione andranno persi).

Le regole di sicurezza sono semplici:

• Tieni le immagini e gli shortcode complessi fuori dalle aree modificabili.
• Mantieni le aree piccole: il numero è illimitato e 10 blocchi piccoli sono meglio di un blocco grande con dei rischi.
• Fai delle prove su una copia dell'articolo o in un ambiente di staging prima di dare accesso ai redattori.
• Se noti differenze nella formattazione Markdown tra la versione con l'icona a forma di matita e la versione senza, sposta quel frammento fuori da [editable].

Alternativa: il plugin Fred

Se la funzionalità di Editable with ContentTools non basta, dai un'occhiata a Fred, un editor frontend più recente per Grav, anch'esso basato su ContentTools. Differenze principali:

• Caricamento immagini tramite finestra di dialogo (con rotazione ed elaborazione di base).
• Wrapping automatico del contenuto tramite l'evento onPageProcessed, che richiede meno markup manuale con shortcode.
• Sviluppo attivo: l'autore accetta segnalazioni su GitHub e continua ad aggiungere funzionalità.

Installazione clonando il repository in /user/plugins/fred:

1
cd user/plugins
2
git clone https://github.com/BugHunter2k/grav-plugin-fred.git fred

I permessi si impostano in modo simile: site.editor: true nel file account dell'utente (nota: site.editor, non site.editable).

Sia Editable with ContentTools che Fred risolvono lo stesso problema: danno ai content manager uno strumento per modifiche rapide senza entrare nel pannello di amministrazione. Il primo è adatto se ti serve uno strumento semplice e collaudato per pagine Markdown senza sorprese. Il secondo funziona se vuoi più automazione e sei pronto ad affrontare i possibili intoppi di uno sviluppo attivo.

Video: come funziona ContentTools

Una dimostrazione di due minuti della modifica di una pagina Grav nel browser: l'autore mostra come vengono evidenziate le aree modificabili, come si apportano le modifiche e come il contenuto viene salvato di nuovo in Markdown. Un buon modo per vedere il plugin in azione prima di installarlo.

⁉️🤔 Domande frequenti

Perché l'icona della matita non compare dopo l'installazione?

Verifica quattro cose. Primo, enabled: true nella configurazione del plugin (user/config/plugins/editable-contenttools.yaml). Secondo, l'utente deve avere il permesso site.editable nel proprio file account. Terzo, per gli utenti backend session.split deve essere false in system.yaml. Quarto, svuota la cache di Grav: bin/grav clear-cache. Di solito il problema è legato ai permessi o alle sessioni separate.

Posso modificare le pagine modulari?

No. Le pagine modulari sono assemblate a partire da pagine figlie tramite template Twig, un processo unidirezionale: il plugin non può "scomporre" il risultato nelle parti originali. Nel frontend vedi l'HTML finito, ma il sorgente (i file Markdown separati dei moduli figli) si trova in altre cartelle e il plugin non sa dove salvare le modifiche. Per le pagine modulari usa l'interfaccia standard di amministrazione di Grav.

Cosa succede se lascio un'immagine dentro [editable]?

I tag speciali Markdown di Grav per le immagini (con parametri ?lightbox, ?resize, ?cropResize) verranno danneggiati durante la conversione da HTML a Markdown. L'immagine in sé rimarrà al suo posto (il tag <img> viene convertito nel Markdown standard ![](url)), ma i parametri di elaborazione andranno persi. Conclusione: tieni sempre le immagini con parametri fuori dall'area modificabile. Se un'immagine è semplice (senza parametri), tecnicamente puoi lasciarla dentro, ma nella pratica è più sicuro spostare tutti i media fuori da [editable].

Il plugin è stato abbandonato dall'autore. È sicuro usarlo?

L'autore ha annunciato ufficialmente la fine del supporto nel 2022 e l'ultimo commit risale ad agosto 2024 (un aggiornamento di compatibilità per Grav 1.7). Il plugin è stabile su Grav 1.7 e non influisce su componenti critici per la sicurezza: lavora solo con contenuti Markdown e non ha accesso a operazioni lato server. Se prevedi di passare a Grav 2.0, valuta di dare un'occhiata a Fred o di attendere una soluzione ufficiale di editing frontend (nuovi approcci basati su TinyMCE e Prosemirror sono in discussione sul forum).

Qual è la differenza tra Editable with SimpleMDE e la versione con ContentTools?

Editable with SimpleMDE usa lo stesso approccio (editing frontend), ma invece di un editor visuale fornisce l'editor Markdown SimpleMDE con anteprima in tempo reale. È adatto a chi preferisce scrivere il markup a mano e vuole vedere il risultato a destra dell'editor anziché in modalità WYSIWYG. Entrambi i plugin sono dello stesso autore (bleutzinn) ed entrambi sono stati abbandonati dal 2022.

Vale la pena installare un editor frontend per Grav nel 2026

Se il tuo sito gira su Grav 1.7, è composto da semplici pagine Markdown e i content manager sono stanchi di entrare nel pannello di amministrazione per un paio di modifiche, installa Editable with ContentTools. Cinque minuti per l'installazione, configurazione minima e la modifica diventa un'operazione a un clic. Apri la pagina, clicca sulla matita, correggi il testo, salva. Niente ricerche tra le liste di pagine, niente cambio di scheda.

Per nuovi progetti o quando pianifichi il passaggio a Grav 2.0 (un rilascio è previsto nel 2026, anche se non c'è una data precisa), prendi in considerazione Fred: è più attivamente sviluppato e ha maggiori probabilità di ricevere la compatibilità con la seconda versione del CMS. In ogni caso, l'editing frontend fa risparmiare decine di clic e minuti di tempo su ogni modifica, cosa che si nota soprattutto nei siti con aggiornamenti frequenti dei contenuti. Provalo in un ambiente di test e decidi quanto questo approccio accelera il tuo flusso di lavoro.