/

Rendering Personalizzato delle Celle: Badge e Avatar

Rendering di HTML fidato - badge di stato colorati, miniature avatar - all'interno di una cella della griglia con Xcrud::html(), oltre a uno stile condizionale più semplice di celle/righe con highlight().

Perché column_callback() da solo non basta

column_callback($field, $fn) permette di sostituire il valore di una cella con qualunque cosa restituisca il callback. Per impostazione predefinita, il valore restituito viene trattato come testo semplice ed escapato, esattamente come qualsiasi altro valore - quindi una stringa semplice come '<span>Active</span>' comparirebbe come parentesi angolari letterali, non come elemento stilizzato.

Racchiudi il valore restituito dal callback nell'helper statico Xcrud::html($html, $text = null) quando vuoi che la cella renderizzi davvero del markup:

public static function html(string $html, ?string $text = null): array
ParametroTipoPredefinitoDescrizione
$htmlstringobbligatorioIl markup fidato da renderizzare nella cella (renderizzato via innerHTML lato client)
$text?stringnullFallback in testo semplice; se omesso, corrisponde a $html con i tag rimossi

$text è ciò che viene effettivamente utilizzato come valore della colonna ovunque l'HTML stilizzato non avrebbe senso - esportazione CSV/XLSX/PDF e ricerca/ordinamento della griglia - poiché questi non possono renderizzare uno <span> colorato.

Esempio: un badge di stato

Un pattern comune: assegnare un colore a una colonna status con un column_callback() che restituisce una piccola pillola tramite Xcrud::html():

$xcrud->column_callback('status', function ($value, $row) {
    $colors = [
        'active'   => '#16a34a',
        'pending'  => '#d97706',
        'canceled' => '#dc2626',
    ];
    $color = $colors[$value] ?? '#6b7280';

    $html = '<span style="background:' . $color . ';color:#fff;'
          . 'padding:2px 10px;border-radius:999px;font-size:12px;">'
          . htmlspecialchars(ucfirst($value)) . '</span>';

    return Xcrud::html($html, ucfirst($value));
});

La cella della griglia mostra la pillola colorata; un'esportazione CSV/XLSX/PDF della stessa colonna mostra invece la semplice parola ("Active", "Pending", "Canceled"), e la ricerca/ordinamento per colonna continuano a funzionare su quello stesso testo semplice.

Lo stesso approccio funziona per un avatar - restituisci un tag <img> (oppure uno <span> con iniziali in un cerchio) racchiuso in Xcrud::html(), con un nome semplice o le iniziali come fallback $text.

highlight() e highlight_row() - uno stile condizionale più semplice

Quando ti serve solo che una cella o una riga cambi colore in base a un confronto - senza bisogno di markup personalizzato - highlight()/highlight_row() è più semplice di un callback completo:

public function highlight(string $field, string $operator, string $value, string $class): self
public function highlight_row(string $field, string $operator, string $value, string $class): self
ParametroTipoPredefinitoDescrizione
$fieldstringobbligatorioColonna su cui valutare la condizione
$operatorstringobbligatorioStesso vocabolario di where(): simboli oppure eq/neq/gt/gte/lt/lte/contains/starts/ends
$valuestringobbligatorioValore con cui confrontare il campo
$classstringobbligatorioClasse CSS applicata quando la condizione corrisponde
$xcrud->highlight('amount', 'gt', '100000', 'xcrud-hl-warn');
$xcrud->highlight_row('status', 'eq', 'canceled', 'xcrud-hl-muted');

highlight() applica la classe solo alla cella corrispondente; highlight_row() la applica all'intera riga. Più regole possono corrispondere alla stessa cella/riga - le loro classi si sommano invece di sostituirsi a vicenda.