🤖 12.1. Widgets para tus vistas XML
Widgets de Zolteka que tu plugin puede usar en sus vistas XML: porcentaje en color, miniatura de producto, texto con negritas, editor de líneas de producto y selector de color opcional. Los de etiquetas están en 12.2. Etiquetas de colores.
Requisitos: Zolteka 2.30 o superior, FacturaScripts 2026.65 o superior y PHP 8.1 o superior. Cada apartado indica desde qué versión de Zolteka existe lo que describe; esta subpágina recoge hasta la 2.30.
📍 Esta es una subpágina de 12. Zolteka para desarrolladores. Antes de empezar, lee su apartado Antes de empezar: comprobar que Zolteka está activo y registrar en Init::init().

Qué son estos widgets. No vienen en el núcleo de FacturaScripts: los añade Zolteka. Todos se escriben en un XMLView con <widget type="..."> dentro de una <column> y no se usan desde PHP. Necesitan Zolteka activo: si no lo está, el tipo no existe y el núcleo pinta un campo de texto normal. Cada widget indica en «Dónde se usa» si va en un listado, en un formulario o en una ficha.
Las propiedades comunes a todos los widgets (fieldname, required, readonly, onclick, opciones de color) funcionan igual que en el núcleo: consulta la página general de widgets de FacturaScripts. Aquí solo se listan las propiedades propias de cada widget.
📍 En esta página:
12.1.1. zPctBadge
Muestra un porcentaje como etiqueta de color. Es el que ves en los listados de facturas de cliente y de proveedor. A diferencia del widget nativo percentage, pinta el valor con un color según umbrales.
Dónde se usa: solo en listados.
<column name="pct-cobrado" display="right" order="500">
<widget type="zPctBadge" fieldname="pct_cobrado"/>
</column>
Propiedades
- fieldname: campo con el porcentaje. Obligatorio. Si está vacío se muestra un guion (-).
- decimal: decimales, de 0 a 6. Por defecto, 1.
- tonefield: campo del modelo con el color ya calculado. Por defecto,
{fieldname}_tone. Si trae valor, manda sobre los umbrales. - tonesuccess, tonewarning, tonedanger, toneinfo, toneprimary, tonesecondary: umbral a partir del cual se usa ese color. Gana el umbral más alto alcanzado. Opcionales.
- titlekey: clave de traducción del texto de ayuda al pasar el ratón. Opcional.
Colores admitidos: success, warning, danger, info, primary y secondary. Si no hay color ni se alcanza ningún umbral, sale warning.
Ejemplo con umbrales: rojo por debajo del 50 %, amarillo desde el 50 % y verde al llegar al 100 %, sin decimales.
<column name="pct-cobrado" display="right" order="500">
<widget type="zPctBadge" fieldname="pct_cobrado" decimal="0"
tonedanger="0" tonewarning="50" tonesuccess="100" readonly="true"/>
</column>
Visualización en listados

Notas: el modelo debe tener la propiedad indicada en fieldname, ya sea una columna o un valor calculado.
12.1.2. zImageProd
Muestra en un listado la miniatura de la primera imagen del producto, incluidas las de sus variantes si quieres.
Dónde se usa: solo en listados.
<!-- Extension/XMLView/ListProducto.xml de tu plugin -->
<view>
<columns>
<column name="image" order="90">
<widget type="zImageProd" fieldname="referencia"/>
</column>
</columns>
</view>
Propiedades
- fieldname: campo del producto, normalmente
referencia. Obligatorio. - thumbwidth: ancho de la miniatura en píxeles. Por defecto, 75.
- thumbheight: alto de la miniatura en píxeles. Por defecto, 75.
- variants:
trueincluye las imágenes de las variantes yfalselas excluye. Por defecto, true.
Ejemplo con opciones: miniatura más pequeña y solo imágenes del producto principal.
<widget type="zImageProd" fieldname="referencia" thumbwidth="50" thumbheight="50" variants="false"/>
Visualización en listados

Notas
- Con
Productosale la primera imagen del producto (convariants="false", solo la general). Con un modelo singetImages(), como el join de variantes, el widget busca porreferencia: la imagen de la variante y, si no tiene, la general del producto. - Las imágenes se cargan por lote para la página del listado, sin una consulta por fila.
- En las exportaciones CSV y XLSX la celda sale vacía.
- Desde la 2.24 Zolteka usa este widget en las pestañas Productos y Variantes de
ListProductoy, si se activa la casilla «Mostrar la imagen del producto en las líneas de los listados de documentos» (Ajustes generales → Listados, apagada por defecto), en las pestañas «Líneas» de los listados de documentos. Ese ajuste solo afecta a esos listados. - Para tu propio listado, la columna la añade tu plugin con una extensión de la vista, como en el ejemplo. Si el plugin ImageWidgetProd está activo, añade su propia columna de imagen y saldrán dos.
12.1.3. zHtml
Muestra en una celda de listado un texto con negritas, cursivas y saltos de línea. No tiene propiedades propias.
Dónde se usa: solo en listados.
<column name="resumen" order="200">
<widget type="zHtml" fieldname="resumen"/>
</column>
Visualización en listados
Todavía no hay captura: ningún plugin publicado usa aún este widget.
Notas
- Solo admite las etiquetas
strong,em,b,iybr, sin atributos. Cualquier otra se muestra como texto. - Si el campo está vacío se muestra un guion (-).
- No es un editor ni sirve para HTML libre. Se llama
zHtmlpara no chocar con widgetshtmlde otros plugins.
12.1.4. zLineasProducto
Editor de líneas de producto dentro de una ficha: referencia, descripción, cantidad, precio, si es facturable y, si quieres, una segunda línea de detalle. Las líneas se guardan con el mismo botón «Guardar» de la ficha.
Dónde se usa: en fichas (EditController o EditListView). En un listado la celda sale vacía.
<!-- XMLView/EditMiParte.xml -->
<group name="lineas" numcolumns="12">
<column name="mi-plugin-lineas" numcolumns="12" order="100">
<widget type="zLineasProducto"/>
</column>
</group>
Propiedades
- autoadd:
trueañade una fila vacía nueva al elegir un producto; confalseaparece el botón «Añadir línea». Por defecto, false. - prices:
falseoculta la columna de precio. Por defecto, true. - billable:
falseoculta la casilla «Facturable». Por defecto, true. - maxlines: número máximo de líneas, bloqueadas incluidas. Por defecto, 0 (sin límite). Usa el mismo valor al guardar.
- emptyquantity:
truedeja vacía la cantidad de las filas nuevas en vez de poner 1. Por defecto, false. - quantityfield: propiedad de la línea de la que se lee la cantidad. Por defecto, cantidad.
- quantitytitle: clave de traducción del rótulo de la cantidad. Por defecto, quantity.
- pricetitle: clave de traducción del rótulo de la columna de precio. Por defecto, zolteka-precio-unitario («Precio unitario»).
- lines: tipo de línea, para fichas con más de un tipo. Opcional.
- detail: plantilla Twig, sin extensión, de la segunda línea de cada fila. Opcional.
- autocompleteaction: acción que responde a la búsqueda de productos. Por defecto, autocomplete-producto-lineas.
- autocompletefilter: filtro que se envía con la búsqueda de productos. Opcional.
Las propiedades true/false también admiten 1/0, yes/no y on/off. El título del bloque sale del title de la columna; si no hay, se muestra «Productos y servicios».
Ejemplo con opciones: máximo de 20 líneas y sin la casilla «Facturable».
<widget type="zLineasProducto" maxlines="20" billable="false"/>
Ocultar los precios por usuario o permiso (desde la 2.02). El método ocultarPrecios() del widget (WidgetZLineasProducto) pone prices a false en tiempo de ejecución, igual que prices="false" en el XML: la columna desaparece y el valor sigue viajando oculto. Se llama sobre la instancia del widget antes de pintarla, cuando el controlador ya sabe qué usuario o permiso aplica.
Visualización en fichas

Notas
- El widget no guarda nada por sí solo. Tu controlador tiene que guardar las líneas con
ZLineasProductoSyncy responder a la búsqueda de productos (puede usarZLineasProductoBuscador). - El modelo de la ficha necesita el método
getLineasProducto(): array. Son opcionalesgetLineasProductoBloqueadas()ygetLineasProductoCodcliente(). - En un listado la celda sale vacía.
- Al elegir un producto, el autocomplete pone el precio unitario sin IVA, el mismo que usaría FacturaScripts en un presupuesto de ese cliente con esa referencia. Si no hay cliente o el Core no encuentra el producto, se usa el precio neto de la variante.
Ejemplo de controlador: un EditController cuyo modelo MiParte tiene líneas MiParteLinea con el campo idparte. Guarda las líneas con el mismo «Guardar» de la ficha y responde a la búsqueda de productos.
use FacturaScripts\Plugins\Zolteka\Lib\ZLineasProductoBuscador;
use FacturaScripts\Plugins\Zolteka\Lib\ZLineasProductoSync;
use FacturaScripts\Plugins\MiPlugin\Model\MiParteLinea;
protected function editAction(): bool
{
if (false === parent::editAction()) {
return false;
}
// guarda las líneas en el mismo «Guardar» de la ficha
ZLineasProductoSync::syncFromHttp(
$this->permissions->allowUpdate,
$this->request,
MiParteLinea::class,
'idparte',
(int) $this->getModel()->id(),
maxLineas: 20 // el mismo valor que maxlines="20" del XML
);
return true;
}
protected function execPreviousAction($action)
{
// autocompletado de productos del widget (action por defecto)
if ($action === 'autocomplete-producto-lineas') {
$this->setTemplate(false);
ZLineasProductoBuscador::autocompleteJson($this->request, $this->response);
return false;
}
return parent::execPreviousAction($action);
}
En una ficha nueva las líneas se guardan cuando ya existe el registro, por eso el ejemplo usa editAction(). Si tu plugin también debe funcionar sin Zolteka, comprueba antes class_exists(ZLineasProductoSync::class).
Las etiquetas de colores y de documentos (zetiqueta, zetiquetacolor, zetiquetas, zetiquetasficha) están en 12.2. Etiquetas de colores.
12.1.5. zColorOpcional
(Desde la 2.24.) Selector de color genérico que admite el valor vacío. No tiene relación con las etiquetas: sirve para cualquier campo de color opcional.
<widget type="zColorOpcional" fieldname="color"/>
Dónde se usa: en formularios y fichas (EditView).
El widget color del núcleo arranca con el selector obligatorio y rellena #FFFFFF en un campo vacío al abrir la ficha, así que un color opcional acabaría guardándose en blanco al editar otro campo cualquiera. zColorOpcional deja el campo vacío hasta que el usuario elige, y admite cualquier color. Lo usa la ficha del estado de evento del calendario. Para colores obligatorios sigue valiendo color; para elegir entre la paleta de tema de una etiqueta, zetiquetacolor.
Las Condiciones de uso de la página de entrada valen para esta subpágina, incluido el aviso de que los ejemplos de código son orientativos y se ofrecen sin garantía.