Renderizado personalizado de celdas: insignias y avatares

Por qué column_callback() por sí solo no basta

column_callback($field, $fn) permite reemplazar el valor de una celda por lo que devuelva tu callback. Por defecto, ese valor de retorno se trata como texto plano y se escapa, igual que cualquier otro valor, así que una cadena simple como '<span>Active</span>' aparecería como corchetes angulares literales, no como un elemento con estilo.

Envuelve el retorno del callback con el helper estático Xcrud::html($html, $text = null) cuando necesites que la celda realmente renderice marcado en vez de texto:

public static function html(string $html, ?string $text = null): array

$text es lo que realmente se usa como valor de la columna en todos los lugares donde el HTML con estilo no tendría sentido: exportación a CSV/XLSX/PDF y búsqueda/ordenación de la cuadrícula, ya que estos no pueden renderizar un <span> con color.

Ejemplo: una insignia de estado

Un patrón habitual: colorear una columna status con un column_callback() que devuelve una pequeña píldora mediante 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 celda de la cuadrícula muestra la píldora coloreada; una exportación CSV/XLSX/PDF de la misma columna muestra en cambio la palabra en texto plano ("Active", "Pending", "Canceled"), y la búsqueda/ordenación de columna sigue funcionando contra ese mismo texto plano.

El mismo enfoque funciona para un avatar: devuelve una etiqueta <img> (o un <span> con iniciales dentro de un círculo) envuelta en Xcrud::html(), con un nombre o iniciales en texto plano como alternativa $text.

highlight() y highlight_row() - estilo condicional más simple

Cuando solo necesitas que una celda o fila cambie de color según una comparación -sin marcado personalizado-, highlight()/highlight_row() es más sencillo que 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

$xcrud->highlight('amount', 'gt', '100000', 'xcrud-hl-warn');
$xcrud->highlight_row('status', 'eq', 'canceled', 'xcrud-hl-muted');

highlight() aplica la clase solo a la celda que coincide; highlight_row() la aplica a la fila completa. Varias reglas pueden coincidir con la misma celda/fila: sus clases se acumulan en lugar de reemplazarse entre sí.