Hook & Filtri

Questo riferimento è destinato agli sviluppatori che vogliono estendere ReadNinja in modo programmatico. Tutti gli hook e i filtri sono stabili e disponibili nelle versioni Gratuita e Pro.

Filtri PHP

Filtro	Parametri	Descrizione
`rpb_is_pro`	`bool`	Restituisce `true` se la licenza Pro è attiva
`rpb_should_display`	`bool $display, int $post_id`	Controlla programmaticamente se la barra viene renderizzata
`rpb_bar_config`	`array $config`	Modifica l'array di config JS prima che venga emesso sulla pagina
`rpb_settings_tabs`	`array $tabs`	Aggiunge o rimuove schede dalla pagina impostazioni

`rpb_is_pro`

Permette ad altri plugin di verificare se Pro è attivo senza codificare nomi di classe o costanti.

add_action( 'init', function () {
    if ( apply_filters( 'rpb_is_pro', false ) ) {
        // Logica solo Pro qui
    }
} );

`rpb_should_display`

Viene eseguito appena prima che ReadNinja decida di renderizzare o meno la barra sulla richiesta corrente. Restituisci false per nasconderla, true per forzarla. Usalo per nascondere la barra sugli articoli molto brevi:

add_filter( 'rpb_should_display', function ( $display, $post_id ) {
    $content    = get_post_field( 'post_content', $post_id );
    $word_count = str_word_count( wp_strip_all_tags( $content ) );

    if ( $word_count < 300 ) {
        return false;
    }
    return $display;
}, 10, 2 );

`rpb_bar_config`

Ti fornisce l'array di config JS completo appena prima che venga trasmesso al frontend. Usalo per iniettare valori personalizzati, sostituire colori basati su meta dell'articolo, o aggiungere dati aggiuntivi per i tuoi script.

add_filter( 'rpb_bar_config', function ( $config ) {
    if ( is_singular( 'podcast' ) ) {
        $config['color']  = '#ff6b35';
        $config['height'] = 6;
    }
    return $config;
} );

`rpb_settings_tabs`

Aggiunge una scheda personalizzata alla pagina impostazioni. Combina con l'azione rpb_render_tab_{tab} per riempirne il contenuto.

add_filter( 'rpb_settings_tabs', function ( $tabs ) {
    $tabs['custom'] = __( 'Personalizzato', 'my-plugin' );
    return $tabs;
} );

Azioni PHP

Azione	Parametri	Descrizione
`rpb_after_bar_render`	`int $post_id`	Si attiva dopo l'emissione dell'HTML della barra
`rpb_render_tab_{tab}`	—	Inietta contenuto in qualsiasi scheda impostazioni

Esempio — aggiungere un <div> aggiuntivo subito dopo la barra di avanzamento sugli articoli singoli:

add_action( 'rpb_after_bar_render', function ( $post_id ) {
    echo '<div class="my-custom-ribbon" data-post="' . esc_attr( $post_id ) . '"></div>';
} );

Esempio — riempire il contenuto della scheda personalizzata registrata sopra:

add_action( 'rpb_render_tab_custom', function () {
    echo '<h2>La mia scheda personalizzata</h2>';
    echo '<p>Qualsiasi contenuto di impostazioni va qui.</p>';
} );

Eventi del browser

ReadNinja invia un singolo evento DOM che puoi ascoltare lato frontend.

Evento	Target	Dettaglio
`rpb:threshold-reached`	`document`	`{ percent: number }`

Questo evento si attiva una sola volta per caricamento pagina, esattamente quando il lettore supera la soglia configurata (funzionalità Pro — vedi Trigger di soglia).

document.addEventListener('rpb:threshold-reached', (e) => {
  console.log('Il lettore ha raggiunto', e.detail.percent, '%')
  // mostra una popup, invia un evento analytics, ecc.
})