🔧 Release v1.0.14 – refactoring debug layer, sidebar toggle fixes, localized AJX_CLP_DB

Author: fgirolami29

.gitignore

@@ -49,3 +49,5 @@ wp-config.php
 .DS_Store
 /.vscode
 /mu-plugins/codecorn/ajax-blog-search/assets/css/_STASH
+README_*
+TODO_*

README.md

@@ -1,93 +1,99 @@
 # MU CC Ajax Blog Search
 
-**MU plugin** per WordPress che trasforma il widget di ricerca del blog in una **ricerca AJAX live** , senza cambiare il markup del tema .
+**MU plugin** per WordPress che trasforma il classico _widget di ricerca del blog_ in una **ricerca AJAX live**, senza modificare il markup del tema.
 
-Pensato per essere drop in in `wp-content / mu-plugins` , con codice organizzato sotto `codecorn / ajax-blog-search` e un piccolo bootstrap che registra hook e asset .
+Pensato per essere “drop-in” dentro `wp-content/mu-plugins`, con codice strutturato in `codecorn/ajax-blog-search` e un bootstrap minimale che registra hook e asset.
 
 ---
 
-## Caratteristiche
+## 🚀 Caratteristiche principali
 
-- Ricerca **AJAX** sui post del blog direttamente dal widget `widget_search`
-- Nessuna modifica al template del tema : il form rimane quello standard
-- Risultati mostrati **sotto al campo di ricerca** , con titolo , data ed excerpt
-- Fallback automatico :
-  - se JS non è disponibile → il form continua a funzionare in modo classico
-- Struttura pulita :
-  - bootstrap MU in `mu-cc-ajax-blog-search.php`
-  - core in `codecorn / ajax-blog-search / src / Plugin.php`
-  - JS e CSS sotto `assets /`
-- Namespace dedicato `CodeCorn \ AjaxBlogSearch`
+- 🔍 Ricerca **AJAX** sui post del blog direttamente dal widget `widget_search`
+- 🧩 Nessuna modifica al template del tema → il form rimane quello standard
+- 💬 Risultati mostrati sotto il campo di ricerca, con titolo, data ed excerpt
+- ⚙️ Fallback automatico: se JS è disattivo, il form continua a funzionare in modo classico
+- 🧱 Struttura pulita e organizzata:
+
+  - bootstrap MU → `mu-cc-ajax-blog-search.php`
+  - core PHP → `codecorn/ajax-blog-search/src/Plugin.php`
+  - asset → `assets/js` e `assets/css`
+
+- 🧭 Namespace dedicato `CodeCorn\AjaxBlogSearch`
 
 ---
 
-## Requisiti
+## 🧰 Requisiti
 
-- WordPress 5 . x o superiore
-- PHP 7 . 4 o superiore consigliato
-- jQuery attivo sul frontend ( WordPress lo carica di default sui temi classici )
+- WordPress 5.x o superiore
+- PHP 7.4 o superiore (consigliato)
+- jQuery frontend attivo (WordPress lo include di default nei temi classici)
 
 ---
 
-## Struttura del plugin
-
-All interno di `wp-content / mu-plugins` :
+## 📁 Struttura del plugin
 
-```text
-mu-plugins /
+```
+mu-plugins/
   mu-cc-ajax-blog-search.php        # bootstrap MU
-  codecorn /
-    ajax-blog-search /
+  codecorn/
+    ajax-blog-search/
       index.php                     # stub di sicurezza
-      src /
-        Plugin.php                  # core del plugin , namespace CodeCorn \ AjaxBlogSearch
-      assets /
-        js /
+      src/
+        Plugin.php                  # core del plugin (namespace CodeCorn\AjaxBlogSearch)
+      assets/
+        js/
           ajax-blog-search.js       # logica AJAX lato client
-        css /
-          ajax-blog-search.css      # stile minimo risultati ( opzionale )
+        css/
+          ajax-blog-search.css      # stile minimo risultati
 ```
 
 ---
 
-## Installazione
+## ⚙️ Installazione
 
-1 . Clona la repo dentro `wp-content / mu-plugins` :
+1. **Clona la repo** in `wp-content/mu-plugins`:
 
-```bash
-cd wp-content / mu-plugins
-git clone https : / / github . com / CodeCornTech / mu-cc-ajax-blog-search . git
-```
+   ```bash
+   cd wp-content/mu-plugins
+   git clone https://github.com/CodeCornTech/mu-cc-ajax-blog-search.git
+   ```
 
-Assicurati che il file `mu-cc-ajax-blog-search.php` si trovi **direttamente** dentro `mu-plugins /` , e la cartella `codecorn / ajax-blog-search /` sia accanto .
+   Assicurati che:
 
-2 . Verifica che WordPress stia caricando il MU plugin :
+   - `mu-cc-ajax-blog-search.php` sia **direttamente** dentro `mu-plugins/`
+   - la cartella `codecorn/ajax-blog-search/` sia accanto.
 
-- vai in **Bacheca → Plugin → Plugin uso obbligato ( Must Use )**
-- dovresti vedere `MU CC Ajax Blog Search` nella lista
+2. Vai in **Bacheca → Plugin → Plugin uso obbligato (Must Use)**
+   e verifica che **MU CC Ajax Blog Search** sia visibile.
 
-3 . Verifica che il tema usi un **widget di ricerca** standard , ad esempio il classico widget `Cerca` nella sidebar del blog :
+3. Il tema deve usare un **widget di ricerca** standard (`widget_search`).
+   Se nel markup trovi:
 
-- se il markup contiene `<aside class="widget widget_search">` e un `<form class="search-form">` , il plugin può agganciarsi automaticamente
+   ```html
+   <aside class="widget widget_search">
+     <form class="search-form" ...></form>
+   </aside>
+   ```
 
-Non serve alcuna configurazione nel backend .
+   allora il plugin si aggancia automaticamente.
+   Nessuna configurazione aggiuntiva necessaria.
 
 ---
 
-## Come funziona
+## ⚙️ Come funziona
 
 ### Lato PHP
 
-La classe principale `CodeCorn \ AjaxBlogSearch \ Plugin` :
+La classe principale `CodeCorn\AjaxBlogSearch\Plugin`:
 
-- registra lo script JS e , se presente , il CSS
-- espone un endpoint AJAX :
+- registra JS + CSS quando serve
+- espone un endpoint AJAX:
 
   - `action = cc_ajax_blog_search`
-  - disponibile sia per utenti loggati che non loggati
+  - disponibile per utenti loggati e ospiti
 
-- esegue una query `WP_Query` sui post del blog usando il parametro `s` passato dal client
-- restituisce un JSON del tipo :
+- esegue una `WP_Query` con il termine `s` passato dal client
+- restituisce un JSON strutturato così:
 
 ```json
 {
@@ -96,130 +102,158 @@ La classe principale `CodeCorn \ AjaxBlogSearch \ Plugin` :
     "results": [
       {
         "title": "Esempio articolo",
-        "url": "https : / / sito . it / esempio articolo /",
+        "url": "https://sito.it/esempio-articolo/",
         "date": "10 Novembre 2025",
-        "excerpt": "Estratto accorciato del contenuto …"
+        "excerpt": "Estratto accorciato del contenuto …",
+        "thumb": "https://sito.it/wp-content/uploads/2025/11/thumb.jpg"
       }
     ]
   }
 }
 ```
 
-### Lato JS
+---
 
-Lo script `assets / js / ajax-blog-search.js` :
+### Lato JS
 
-- cerca tutti i form `.widget_search form . search-form`
-- per ciascuno :
+Lo script `assets/js/ajax-blog-search.js`:
 
-  - crea un container `<div class = "cc-ajax-search-results">` subito dopo il form
-  - intercetta `submit` del form e i `keyup` nel campo di ricerca
-  - effettua una richiesta AJAX a `admin - ajax . php` con :
+- trova tutti i form `.widget_search form.search-form`
+- crea un box risultati `<div class="cc-ajax-search-results">` subito dopo il form
+- intercetta:
 
-    - `action = cc_ajax_blog_search`
-    - `nonce` per sicurezza
-    - parametro `s` con il valore digitato
+  - `submit` → effettua AJAX
+  - `keyup` → ricerca live con debounce
 
-  - renderizza i risultati sotto il form
+- richiama `admin-ajax.php?action=cc_ajax_blog_search` passando `s` e `nonce`
+- renderizza dinamicamente titolo, data, excerpt e thumb (opzionale)
 
-Se il campo di ricerca è vuoto , la box risultati viene svuotata .
+Se il campo è vuoto, la box risultati viene svuotata.
 
 ---
 
-## Personalizzazione
-
-### Limitare a un numero diverso di risultati
+## 🧩 Filtri e personalizzazioni
 
-Di default vengono restituiti i **5** post più rilevanti .
-Nel file `src / Plugin.php` , nell array di query :
+### 🔹 Miniatura (thumbnail)
 
 ```php
-'posts_per_page' => 5 ,
+add_filter('cc_ajax_blog_search_show_thumbnail', '__return_true');
+
+// opzionale: dimensione immagine
+add_filter('cc_ajax_blog_search_thumbnail_size', function () {
+    return 'medium'; // oppure una image-size custom
+});
 ```
 
-puoi aumentare o ridurre il valore .
+---
 
-### Limitare la ricerca a una categoria
+### 🔹 Sidebar mobile collapsabile / floating
 
-Puoi aggiungere `cat` o `category__in` agli argomenti della query :
+Permette di trasformare i widget della sidebar in un pannello mobile a comparsa (overlay o barra top).
+Disattivato di default.
 
 ```php
-$args = array(
-    'post_type'      => 'post' ,
-    's'              => $term ,
-    'posts_per_page' => 5 ,
-    'cat'            => 59 , // id categoria "News"
-);
+// attiva la feature
+add_filter('cc_ajax_blog_search_sidebar_toggle_enabled', '__return_true');
+
+// modalità: 'floating' (default) oppure 'top'
+add_filter('cc_ajax_blog_search_sidebar_toggle_mode', function () {
+    return 'floating'; // oppure 'top'
+});
+
+// breakpoint mobile (px)
+add_filter('cc_ajax_blog_search_sidebar_toggle_breakpoint', function () {
+    return 992;
+});
+
+// label del pulsante toggle
+add_filter('cc_ajax_blog_search_sidebar_toggle_label', function () {
+    return 'Filtri & ricerca';
+});
 ```
 
-Oppure , in una futura versione , leggere il valore da un filtro o costante .
+Quando disattivato o non definito, il CSS non modifica il comportamento della sidebar.
 
-👉 Per attivare i thumb ti basta , da tema / altro mu-plugin:
+---
 
-```php
-add_filter( 'cc_ajax_blog_search_show_thumbnail', '__return_true' );
+### 🔹 Debug Layer
 
-// opzionale : size custom
-add_filter( 'cc_ajax_blog_search_thumbnail_size', function () {
-    return 'medium'; // o una image size custom
-});
+Il sistema di debug è gestito interamente da PHP ed esposto al JS tramite `wp_localize_script`.
+
+Puoi attivarlo in 3 modi:
+
+#### 1. via `wp-config.php`
+
+```php
+define('CC_AJAX_BLOG_SEARCH_DEBUG', true);
 ```
 
-Toggled o floating sidebar Esempio di attivazione dal tema / altro mu-plugin:
+#### 2. via filtro (vince sul define)
 
 ```php
-add_filter( 'cc_ajax_blog_search_sidebar_toggle_enabled', '__return_true' );
-// floating (default) oppure 'top'
-add_filter( 'cc_ajax_blog_search_sidebar_toggle_mode', function () {
-    return 'floating'; // oppure 'top'
-});
+add_filter('cc_ajax_blog_search_debug', '__return_true');
 ```
-### Traduzioni testi frontend
 
-I testi mostrati dal JS vengono passati tramite `wp_localize_script` :
+#### 3. via console JS (solo runtime)
+
+```js
+window.AJX_CLP_DB = true;
+```
+
+Quando attivo, tutti i log `console.log` debug del plugin vengono stampati con prefisso `[AJX-SIDEBAR]`.
+
+---
+
+### 🔹 Traduzioni frontend
+
+I testi mostrati dal JS sono passati via `wp_localize_script`:
 
 - `no_results_text`
 - `error_text`
 
-Puoi sovrascriverli tramite filtro in un altro MU plugin o nel tema :
+Puoi sovrascriverli in un altro MU plugin o nel tema:
 
 ```php
-add_filter( 'cc_ajax_blog_search_i18n' , function ( $strings ) {
-    $strings['no_results_text'] = 'Nessun risultato per la tua ricerca .';
+add_filter('cc_ajax_blog_search_i18n', function ($strings) {
+    $strings['no_results_text'] = 'Nessun risultato per la tua ricerca.';
+    $strings['error_text']      = 'Errore temporaneo, riprova più tardi.';
     return $strings;
 });
 ```
 
-( hook da aggiungere in una versione successiva se ti va di internazionalizzare pesante )
-
 ---
 
-## Debug
-
-Se vuoi controllare che l AJAX funzioni :
-
-1 . Apri la pagina blog con sidebar
-2 . Premi `F12` → tab **Network**
-3 . Scrivi nel campo di ricerca almeno 3 caratteri
-4 . Dovresti vedere chiamate a :
+## 🧪 Debug manuale
 
-- `admin - ajax . php ? action = cc_ajax_blog_search & s = ...`
+1. Apri la pagina del blog
+2. Premi `F12 → Network`
+3. Digita almeno 3 caratteri nel campo ricerca
+4. Dovresti vedere chiamate a:
 
-Se la risposta è `200` con un JSON valido , il lato PHP è ok .
+```
+/wp-admin/admin-ajax.php?action=cc_ajax_blog_search&s=...
+```
 
-Se non vedi il container risultati , verifica il CSS del tema o eventuali conflitti JS .
+Se la risposta è `200 OK` e contiene JSON valido → il backend è ok.
+Se non compare il box risultati → verifica CSS del tema o conflitti JS.
 
 ---
 
-## Roadmap
+## 🧭 Roadmap
 
-- Filtro per post type custom
-- Opzione per usare un template markup personalizzato via hook PHP
-- Supporto per multiple istanze con comportamenti diversi
-- Tiny helper per limitare in automatico la ricerca alla categoria del blog corrente
+- [ ] Filtro per post type custom
+- [ ] Hook per template markup personalizzato
+- [ ] Supporto multi-istanza con config separate
+- [ ] Internazionalizzazione completa (`cc_ajax_blog_search_i18n`)
+- [ ] Auto-scope alla categoria corrente del blog
 
 ---
 
-## Licenza
+## ⚖️ Licenza
+
+**MIT License** — usa, forka, migliora e manda una PR ✨
 
-MIT . Usa , forka , migliora e mandaci una pull request ✨
+© CodeCorn Technology SRLS — _Federico Girolami_
+_“Digital Solution Architecture with Style.”_
+
+---