← Tutti gli articoli

API e helper

window.JZ: helper per pilotare pulsanti, slider e Output Console dal codice

15 maggio 2026 · di JustZix Team

Per un momento, dimentica che JustZix inietta CSS e JS in ogni pagina. Concentrati sul fatto che ogni azione — pulsante, slider, select, toggle3, input, textarea — è un elemento DOM vivo che puoi pilotare da altro codice. Servono due namespace separati nel MAIN world: window.JZ (helper per le azioni) e window.JUSTZIX (logger). Ognuno ha il suo ciclo di vita, il suo scopo, e deliberatamente non si mescolano.

Perché due namespace e non uno

Il logger (sola scrittura, dispatch verso la Output Console) e l'indirizzabilità del DOM (leggere/manipolare elementi che vivono già nel DOM della pagina) sono due semantiche diverse. Impacchettarle insieme mescolerebbe le responsabilità. Un utente che legge il codice vede JUSTZIX.log(...) e sa: «quello è un logger». Vede document.querySelector('[data-jz-action-id="x"]') e sa: «quella è una query DOM». Inoltre — l'API DOM nativa + gli attributi data-* vincono sempre su un wrapper proprietario (funziona con l'inspect dei DevTools, con le librerie di terze parti, con il copia-incolla da internet).

Idempotente — l'installazione è gestita per versione (_jzVersion per JZ, flag di hook per JUSTZIX), così gli aggiornamenti dell'estensione non sovrascrivono i namespace a metà sessione.

Superficie completa dell'API

// ============================================================
// window.JZ — Helper per le azioni
// Opera su elementi data-jz-action-id nel DOM.
// Può essere occupato dagli script della pagina → fallback: query DOM nativa.
// ============================================================
JZ.action(labelOrId)     // Elemento per label O id. Case-insensitive per label.
JZ.actionById(id)        // Elemento per data-jz-action-id. Nessun fallback su label.
JZ.actions()             // Array di tutti gli elementi azione nel DOM.
JZ.labels()              // Array di label (maiuscole/minuscole originali).
JZ.click(labelOrId)      // Click programmatico. Per <select> sceglie la prima opzione.
                          // Ritorna true/false.
JZ.value(labelOrId)      // Valore corrente dell'azione (string o null).
JZ.setValue(labelOrId, value)  // Setter programmatico + dispatch di input + change.
JZ.bars()                // Array di tutte le .jz-actions-bar nel DOM.
JZ.barById(id)           // Barra per data-jz-bar-id.
JZ.floatingBtn()         // L'elemento del pulsante flottante di JustZix (quando attivo).

// ============================================================
// window.JUSTZIX — Logger (da v2.13.73, alias primario da v2.13.76)
// Fa dispatch verso la Output Console (kind='jz'); NON inoltra al console.* nativo.
// Nome di brand = rischio di collisione trascurabile. Funziona ovunque.
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// Alias alla stessa API:
window.__JUSTZIX__       // sempre impostato (retrocompatibilità con v2.13.72-75)
window.JZ                // anche, solo quando non occupato — una scorciatoia più corta

// Fallback quando window.JZ è occupato dalla pagina (es. Google Ads):
// → nessun equivalente di JUSTZIX.click(); usa il DOM nativo.
document.querySelector('[data-jz-action-id="..."]').click();

Caso d'uso 1 — un pulsante clicca un altro pulsante

Hai le azioni «Login → Dashboard → Statistiche». Tre pulsanti separati in una barra di azioni. Aggiungi un quarto «🚀 Quick» che esegue tutti e tre in sequenza:

// Azione BUTTON «Quick» — campo del codice:
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Statistiche');
JUSTZIX.log('Flusso Quick completato — 3 click in 1');

Bonus: questo script non sa nulla della pagina, conosce solo le sue azioni JustZix. Cambia i selettori dentro «Login» / «Dashboard» — «Quick» continua a funzionare, perché le chiama per label.

Caso d'uso 2 — uno slider pilota una variabile CSS

Azione SLIDER «Luminosità» (range 50-150, default 100). Nel suo campo «Code»:

// Lo slider esegue questo codice a ogni cambiamento.
// `value` è una extraVar iniettata dall'estensione (da v2.12.2).
document.documentElement.style.setProperty('--brightness', value + '%');

Ora in un'altra azione (BUTTON «Reset») puoi impostare programmaticamente il valore dello slider:

JZ.setValue('Luminosità', 100);  // Lo slider salta a 100, variabile CSS aggiornata, luminosità ripristinata.
JUSTZIX.log('Luminosità ripristinata al 100%');

Lo stesso vale per TOGGLE3 (interruttori a 3 stati come «Dev / Staging / Prod»): JZ.setValue('Ambiente', 'staging') attiva quello stato specifico ed esegue il suo codice.

Caso d'uso 3 — la Output Console come «blocco appunti»

La Output Console (da v2.13.66) è un pane che cattura tutto l'output di console.log dalla pagina. Pagine come Gmail intasano la console con centinaia di righe al secondo. I filtri sulle stringhe aiutano, ma un trucco migliore: scrivi solo i tuoi messaggi tramite JUSTZIX.log, poi imposta il pane in modalità [J] (Just JustZix).

// In un'azione «Verifica carrello»: logga solo i TUOI messaggi, niente rumore della pagina.
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`Il carrello ha ${items.length} articoli`);
items.forEach((it, i) => {
  const price = parseFloat(it.querySelector('.price')?.textContent || 0);
  JUSTZIX.log(`  [${i}] ${it.dataset.sku} — $${price}`);
});
const total = [...items].reduce((s, it) => s + parseFloat(it.querySelector('.price')?.textContent || 0), 0);
JUSTZIX.log(`Totale: $${total}`);

Il pane Output Console in modalità [J] mostra SOLO quelle 3 righe — completamente pulito, perfetto per una toolbar QA o un contesto rivolto al cliente.

E se la pagina ha già window.JZ?

Il logger funziona sempre — JUSTZIX.log() ha un nome di brand (rischio di collisione trascurabile) ed è il primario. In più window.__JUSTZIX__ è sempre impostato come alias di fallback. Un conflitto su window.JZ riguarda solo gli helper per le azioni — e anche allora hai una via d'uscita nativa.

Alcuni siti (es. Google Ads) hanno il proprio window.JZ. JustZix lo rileva: se window.JZ esiste già quando il logger si installa, l'estensione non sovrascrive l'API della pagina e lo segnala nel messaggio di benvenuto della Output Console. La scorciatoia breve JZ resta quindi riservata alla pagina — usa JUSTZIX per il logging e il DOM nativo per le azioni:

// Logger: sempre JUSTZIX (funziona anche quando JZ è occupato dalla pagina)
JUSTZIX.log('Carrello elaborato');

// Click su un'azione: quando window.JZ è occupato → usa il DOM nativo invece di JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// Oppure per data-jz-key (label in maiuscolo):
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

È un design deliberato: data-jz-action-* + querySelector è un pattern nativo — funziona con l'inspect dei DevTools, con le librerie di terze parti, con il copia-incolla da internet. JZ.click() è zucchero sintattico — un livello di indirezione opzionale che puoi saltare quando non è disponibile.

Trappole

• JZ.click() su INPUT/TEXTAREA li clicca soltanto, non cambia il loro valore. Per impostare il testo: JZ.setValue('Cerca', 'foo'). Gli altri tipi (button, select, toggle3, slider) hanno un default sensato per il click.
• JZ.value()/setValue() sono diventati più completi da v2.13.33. Le versioni più vecchie non avevano il valore dello slider nel dataset — se vedi null per uno slider, controlla la versione dell'estensione.
• La ricerca per label è case-insensitive, ma quella per ID è case-sensitive. Consigliato: attieniti alle label (le tue), non agli ID (auto-generati).
• JUSTZIX.log NON inoltra alla console dei DevTools. È voluto — vogliamo un canale separato per gli script JustZix. Se vuoi i DevTools — usa il normale console.log.
• La JS Console cattura solo il traffico in stile DevTools, non JUSTZIX.log automaticamente. «console.log('hi')» nella JS Console funziona come sempre; «JUSTZIX.log('hi')» nella JS Console NON apparirà nella Output Console a meno che tu non abbia un pane Output Console attivo in modalità [J] o [C+J].
• Nessun JUSTZIX.click() o simile. Logger e helper per le azioni sono namespace separati per scelta. Quando la pagina occupa window.JZ, attivi le azioni tramite il DOM nativo (querySelector + data-jz-action-*) — è il pattern, non un bug.

Cosa fare dopo

Questo chiude la mini-serie sulle finestre di JustZix nel frontend:

• CSS pane — editor CSS in tempo reale nella scheda
• JS Console — REPL con cronologia ↑↓
• JS pane — Run-on-demand
• window.JZ helpers (questo articolo) — l'API programmatica

Tutto insieme è una mini-IDE dentro ogni scheda del browser, con una mini-API per pilotare i tuoi pulsanti. Installa JustZix e provalo tu stesso — completamente gratuito, senza account, senza server.