<

Tema child

Ultima modifica: 29 Giugno 2026

Il wordpress Gpci framework per funzionare correttamente richiede obbligatoriamente l'utilizzo di un tema child (gpci-child) che viene già fornito pronto all'uso e può essere configurato a piacere. E' composto dalla classica struttura dei temi child di wordpress ma contiene molti files e cartelle aggiuntive che vengono inclusi dal tema padre per aggiungere funzioni e configurazioni precise. Quasi tutti i files e le cartelle aggiuntive sono opzionali (anche se consigliate), quindi verranno incluse dal tema padre soltanto se esistenti.

Cartelle

La maggior parte delle cartelle speciali del tema child serve ad aggiungere elementi in modo organizzato: basterà aggiungere files di una o più estensioni il cui contenuto sarà automaticamente valutato dal tema padre. Solitamente le funzioni che aggiungono il contenuto dalle cartelle sono ricorsive, quindi possono essere create sottocartelle a piacere per una migliore organizzazione nel caso che ci siano molti files. Nella lista seguente se la cartella è ricorsiva ho aggiunto una proprietà in grassetto ricorsiva per contrassegnarlo.

Risorse private

  • Posizione: /private/
  • obbligatorio

Questa cartella serve a contenere files e cartelle privati, come blocchi gutenberg aggiuntivi, chiavi di crittografia, logs, configurazioni php, ecc... E' preinserito nella cartella un file .htaccess per bloccare l'accesso ai files dal web.

Cartella temp

  • Posizione: /private/temp/
  • obbligatorio

In questa cartella verranno inseriti i files temporanei utilizzati dal tema padre. E' possibile utilizzare liberamente questa cartella stando attenti a non utilizzare gli stessi nomi dei files già presenti. Durante l'attivazione del tema child questa cartella verrà svuotata.

Cartella logs

  • Posizione: /private/logs/
  • obbligatorio

In questa cartella verranno inseriti i logs creati dalla funzione WriteLog. Durante l'attivazione del tema child questa cartella verrà svuotata.

Php

  • Posizione: /private/php/
  • opzionale

Questa cartella contiene le risorse private php.

Blocchi gutenberg aggiuntivi

  • Posizione: /private/blocks/
  • ricorsiva
  • opzionale

Tutti i files javascript caricati in questa cartella saranno registrati come blocchi gutenberg personalizzati, se per ogni file esiste un file php con lo stesso nome (oppure lo stesso nome senza i trattini medi) sarà registrato come render callback (blocco dinamico) di quel blocco.

Risorse collegate

Contenuti e funzioni php aggiuntivi

  • Posizione: /private/php/auto_includes
  • ricorsiva
  • opzionale

Tutti i files php caricati in questa cartella aggiunti automaticamente inclusi dal tema padre. E' possibile ad esempio creare files contenenti hooks php wordpress oppure funzioni che gestiscono processi cron che verranno automaticamente inclusi. Esempi:

//hook aggiuntivo
<?php
add_filter( $hook_name='render_block', $callback=function( $block_content, $block, $instance ){
  //codice relativo hook render_block
return $block_content;
}, $priority=31, $accepted_args=3 );

//funzione aggiuntiva
function invio_email(){
  //wp_mail();
}

Librerie javascript aggiuntive

  • Posizione: /js/module-additions/
  • ricorsiva
  • opzionale

Tutti i files javascript caricati in questa cartella saranno registrati come librerie javascript aggiuntive da poter selezionare tramite il modulo aggiunte di codice.

Icons

  • Posizione: /private/icons/
  • ricorsiva
  • opzionale

Tutti i files html caricati in questa cartella aggiungeranno icone alle icone globali, ogni file può contenere icone multiple. Le icone dovranno essere formattate nella seguente struttura di esempio:

<symbol viewbox="0 0 448 512" id="angle-down"><path d="M201.4 374.6c12.5 12.5 32.8 12.5 45.3 0l160-160c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L224 306.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l160 160z"/></symbol>

<symbol viewbox="0 0 512 512" id="circle-info"><path d="M256 512A256 256 0 1 0 256 0a256 256 0 1 0 0 512zM216 336h24V272H216c-13.3 0-24-10.7-24-24s10.7-24 24-24h48c13.3 0 24 10.7 24 24v88h8c13.3 0 24 10.7 24 24s-10.7 24-24 24H216c-13.3 0-24-10.7-24-24s10.7-24 24-24zm40-208a32 32 0 1 1 0 64 32 32 0 1 1 0-64z"></path></symbol>

Ricordarsi di assegnare un id ad ogni icona all'interno del tag symbol. L'id dovrà essere univoco nella pagina singola, meglio ancora nel sito.

Shortcodes aggiuntivi

  • Posizione: /private/php/shortcodes/
  • ricorsiva
  • opzionale

Tutti i files php caricati in questa cartella saranno registrati automaticamente come shortcodes personalizzati. E' possibile organizzare in files e sottocartelle a piacere per organizzare meglio, l'unica regola da seguire è che il nome del file equivale al tag dello shortcode. Le variabili da specificare all'interno invece sono:

  • atts - array - opzionale - contiene i valori predefiniti degli attributi
  • content - stringa - opzionale - eventuale contenuto passato se lo shortcode è di tipo enclosing

Esempi

Shortcode di tipo enclosing, nome file: esempio.php:

$atts =	[
  'link' => $atts['link'] ?? 'https://www.gigitopcinformatica.it',
  'testo' => $atts['testo'] ?? 'default2'
];

$link = $atts['link'];
$testo = $atts['testo'];

$StringaFinale = "<a href='$link'>$testo</a>";

return $StringaFinale;

Si usa con:

[esempio link="https://www.gigitopcinformatica.it/docs/gpci-framework/" testo="Documentazione Gpci framework"]

Risultato:

Documentazione Gpci framework

Shortcode di tipo enclosing, nome file: esempio2.php:

$atts = [
  'testo_sostitutivo' => $atts['testo_sostitutivo'] ?? 'false'
];

$testo_sostitutivo = $atts['testo_sostitutivo'];

$StringaFinale = "<p>Mi chiamo <b>$content</b>!</p>";
$StringaFinale = str_replace( $search='Mario', $replace='Luigi', $subject=$StringaFinale );

return $StringaFinale;

Si usa con:

[esempio2]Mario[/esempio2]

Risultato:

Mi chiamo Luigi!

Templates a pulsanti (templates btn)

  • Posizione: /private/js/templates-btn/
  • ricorsiva
  • opzionale

Il sistema dei templates a pulsanti serve a permettere agli amministratori di aggiungere pulsanti in varie zone del backend che, con un solo click, modificano campi personalizzati, testi e impostazioni con del contenuto predefinito. L'azione del pulsante è differente dalla zona in cui è generato (ad esempio nel gruppo di controllo attributi aggiunge o rimuove un attributo, invece nella sezione media/grandezze media del customizer imposta le grandezze media del sito) e il contenuto dei pulsanti si definisce semplicemente con un oggetto json per ogni zona. Il contenuto dei pulsanti può essere anche dinamico, per questo possono essere definite anche delle variabili php il cui contenuto dinamico sarà passato automaticamente a javascript.

File di variabili

  • Posizione: /private/js/templates-btn/templates-btn-vars.json

In questo file è possibile definire delle variabili da passare ai template btn definendone il nome e la stringa php che ne ritornerà il contenuto. Attenzione perchè la stringa php sarà valutata con eval durante il caricamento della pagina all'interno di un blocco try and catch e se ci sono errori ritornerà con una stringa di errore al posto del contenuto.

Vediamo intanto un esempio completo del file:

{
  "separator and site name":"'- '.get_bloginfo()",
  "excerpt":"get_the_excerpt( gpci\\QueryStringsArrayPost )"
}

Il file contiene sempre solo un oggetto con delle proprietà organizzate per nome e valore. In questo esempio abbiamo due variabili con il rispettivo contenuto:

  1. nome variabile: separator and site name. Sarà usata più tardi in questo modo: var:separator and site name
    Il contenuto del pulsante diventerà: - nome sito
  2. nome variabile: excerpt. Sarà usata più tardi in questo modo: var:excerpt
    Il contenuto del pulsante diventerà il riassunto del post corrente nel backend (calcolato però durante il caricamento dell'editor). Verificare in questo caso anche la costante gpci\QueryStringsArrayPost

Cartella auto-includes

  • Posizione: /private/js/templates-btn/auto-includes

In questa cartella è possibile creare sottocartelle e files json a piacere che conterranno gli oggetti javascript da passare alle zone dei pulsanti. Comunque consiglierei per semplicità, a parte casi particolari, di creare un file per ogni zona e chiamarlo come la zona stessa, proprio come nel tema child default. Intanto vediamo i parametri comuni degli oggetti:

icons
  • tipo: array di stringhe

Ogni stringa è il nome di una wordpress dashicon oppure un'icona in formato svg. Se si utilizzano icone svg intere utilizzare internamente single quotes oppure \" (vedi esempi). Ogni icona sarà generata subito prima del testo del pulsante. Ricordarsi che anche se si utilizza soltanto un'icona sarà sempre un array. Può essere lasciato vuoto se non si vuole inserire icone. Esempi:

Qui utilizziamo due dashicons:

{ "icons":[ "hidden", "smartphone" ] }

Ora utilizziamo una dashicon e un'icona svg intera:

{ "icons":[ "hidden", "<svg viewBox='0 0 512 512'><path d='M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z'/></svg>" ] }

equivalente di:

{ "icons":[ "hidden", "<svg viewBox=\"0 0 512 512\"><path d=\"M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352a144 144 0 1 0 0-288 144 144 0 1 0 0 288z\"/></svg>" ] }
ButtonText
  • tipo: stringa

Testo del pulsante. Se non si vuole generare un testo lasciare vuoto.

TooltipText
  • tipo: stringa

Testo del tooltip (comparirà quando ci si passa sopra con i mouse). Non utilizzare la proprietà se non si vuole generare il tooltip (ma andrebbe sempre specificato come guida).

content
  • tipo: stringa/array/oggetto/altro (dipende dalla zona)

Contenuto che verrà inserito nella zona del pulsante. Vedere la zona corrispondente e i files default nel tema child.

condition
  • tipo: condizione javascript

Condizione javascript che ritornerà true o false. Se true il contenuto sarà generato, La condizione per ora sarà valutata tramite eval; se la zona è di un blocco gutenberg sarà valutata all'interno della funzione edit del blocco. La variabile che interessa probabilmente sarà props da cui si risale a tutto ciò che può interessare (come il nome del blocco). Esempi:

Il pulsante verrà generato se l'utente corrente è un amministratore:

"condition" : "CurrentUserRoles.includes( 'administrator' )"

Il pulsante verrà generato se il blocco correntemente selezionato è un'immagine:

"condition" : "props.name == 'core/image'"

Ora definiamo la lista di tutte le zone disponibili (sia comuni che per moduli):

  • AdvancedClasses - questa zona di pulsanti è generata nei blocchi gutenberg in InspectorControls/avanzate/classi (sotto) e alterna il contenuto nella stringa delle classi
  • AdvancedJs - questa zona di pulsanti è generata nei blocchi gutenberg in InspectorControls/avanzate/js (sopra) e inserisce il testo nella textarea js
  • Attributes - questa zona di pulsanti è generata nei blocchi gutenberg in InspectorControls/attributi (sopra ai campi ripetibili) e alterna la definizione dell'attributo singolo
  • RenderingConditions - questa zona di pulsanti è generata in InspectorControls/condizioni di rendering (sopra ai campi ripetibili) e alterna la definizione della condizione singola
    module-media-mediasizes - questa zona di pulsanti è generata (se attivato il modulo media) nel customizer e serve a impostare le grandezze media sel sito con un click
  • BlockControlAddContent - questa zona di pulsanti è generata in BlockControls/Aggiungi elemento. Questa zona è doppia e oltre a poter inserire il contenuto è presente anche un pulsante per copiarlo in memoria (in quanto in alcune zone non funziona perfettamente e può fare comodo)
Modulo media
Modulo meta
  • module-meta-seo-title - questa zona di pulsanti è generata (se attivato il modulo meta) nei post in Motori di ricerca/Title e ci aggiunge il contenuto
  • module-meta-seo-description - questa zona di pulsanti è generata (se attivato il modulo meta) nei post in Motori di ricerca/Meta name=description e ci aggiunge il contenuto
  • module-meta-seo-metarobots - questa zona di pulsanti è generata (se attivato il modulo meta) nei post in Motori di ricerca/Meta name=robots e ci alterna il contenuto

Esempi

Per ora non inserisco esempi relativi ai template a pulsanti in questa pagina in quanto ci sono files già pronti piuttosto chiari nella cartella del tema child default.

Scripts aggiuntivi gutenberg

  • Posizione: /private/js/block_editor_assets/
  • ricorsiva
  • opzionale

I files javascript caricati in questa cartella saranno accodati al block editor dopo quelli del tema padre. Questo serve ad aggiungere facilmente hooks javascript, scripts e retro compatibilità a siti su in cui sarebbe troppo dispendioso convertire attributi dei blocchi o modifiche sostanziali. Esempio di retro compatibilità con la prima versione del controllo foreach:

Caricare il file old-foreach.js nella cartella contenente:

Vedi codice

Valori default

  • Posizione: /private/defaults/
  • opzionale

I files caricati in questa cartella saranno utilizzati come valori default durante il ripristino valori predefiniti nel customizer. Se il file non è trovato qui sarà utilizzato il file all'interno del tema genitore.

Files

functions.php

  • Posizione: /functions.php
  • opzionale

All'interno di questo file è possibile inserire funzioni php personalizzate che verranno eseguite prima di quelle del tema genitore. Per utilizzare le funzioni o modificare le variabili definite nel tema padre questo non è quasi mai il file corretto; per quel tipo di operazioni utilizzare il file functions-after-parent.php.

functions-after-parent.php

  • Posizione: /functions-after-parent.php
  • opzionale

All'interno di questo file è possibile inserire funzioni php personalizzate che verranno eseguite dopo quelle del tema genitore. Questo file è incluso alla fine del file functions.php del tema genitore, quindi da qui è possibile utilizzare le funzioni definite nel tema padre (come SetSmtpServer).

options.php (deprecato, utilizzare gpci_config.php)

  • posizione: /private/php/options.php
  • opzionale

Questo file viene incluso dal tema padre quasi subito e serve a specificare le opzioni forzate o predefinite delle pagine impostazioni. Può essere utile anche per modificare alcune opzioni di wordpress così da avere i files di funzione un po' più ordinati (ad esempio in questo file ho abilitato i riassunti per le pagine e disabilitato i pattern remoti). Il file è già popolato di default con varie potenziali opzioni (molte commentate) per dare un'idea di come andrebbe usato. Questo file è comunque opzionale e liberamente configurabile e prima dell'inclusione ne sarà verificata l'esistenza.

gpci_config.php

  • posizione: /private/php/gpci_config.php
  • opzionale

Questo file sostituisce options.php e serve a impostare le globali di configurazione del framework.

style.css

  • posizione: /style.css
  • obbligatorio

File richiesto da wordpress. In questo framework è utilizzato in modo completamente personalizzato e contiene tutti gli stili globali derivanti da gutenberg e dal customizer. Non va modificato manualmente ma attraverso il customizer.

style-print.css

  • posizione: /style-print.css
  • opzionale: modulo di stampa

File generato dal modulo di stampa, come lo style.css non va modificato manualmente ma attraverso il customizer.

customizer-base.css

  • posizione: /private/css/customizer-base.css
  • obbligatorio

Utilizzato per comporre il file style.css ed accodarlo in gutenberg dopo gli stili globali.

customizer-custom.css

  • posizione: /private/css/customizer-custom.css
  • obbligatorio

Utilizzato per comporre il file style.css ed accodato in gutenberg dopo gli stili globali e dopo il file customizer-base.css.

headers-style.css

  • posizione: /private/css/headers-style.css
  • obbligatorio

Utilizzato per comporre il file style.css introducendone le headers. Qui vanno inseriti i dati come:

  • author
  • author URI
  • theme URI
  • tags
  • versioni richieste

Al momento non modificare gli altri.

js-head.js

  • posizione: /js/js-head.js
  • obbligatorio

Contiene le variabili e gli scripts predefiniti e il codice personalizzato globale inserito nella zona corrispondente del customizer. Il verrà accodato automaticamente da wordpress nella head del sito.

js-footer.js

  • posizione: /js/js-footer.js
  • opzionale

Contiene il codice personalizzato globale inserito nella zona corrispondente del customizer. Il verrà accodato automaticamente da wordpress nel footer del sito, ma soltanto se esiste del codice.