Feature ETP-3486: Add color support documentation

docs/developer-guide/etendo-classic/how-to-guides/how-to-configure-color-system.md

@@ -0,0 +1,89 @@
+---
+tags:
+  - How to
+  - Color System
+  - UI
+  - Extensibility
+
+status: new
+---
+
+# How to Configure Color System Support in the UI
+
+## Overview
+
+The color system in Etendo allows assigning visual identifiers (color badges) to records within a grid or form in the Workspace UI, enhancing the user experience by highlighting key information. This feature uses Etendo's extensibility system and can be applied without modifying the core codebase of the graphical interface.
+
+A common use case is applying it to master tables such as **Product Category** (`M_Product_Category`) or **Business Partner Group** (`C_BP_Group`), as these are frequently referenced in main grids like Products or Customers.
+
+## How the Color System Works
+
+For a color to appear in the UI, the field in the main table must reference a master table via a Foreign Key (**TableDir** or **Table** reference). The Workspace UI and Etendo coordinate through an interaction between the metadata and the React frontend:
+
+1. **Metadata injection**: the backend checks whether the data dictionary has the column configured with the **Color** reference type. If so, it injects `colorFieldName` into the graphical metadata to indicate the property name.
+2. **Frontend request**: the data-fetching hooks (Datasource) in Next.js evaluate each defined column. If a column specifies `colorFieldName` metadata, the frontend adds the dependency as `_extraProperties` to the API request (e.g., `_extraProperties=M_Product_Category_ID$EM_SMF_Color`), which instructs the backend to perform the corresponding JOINs and return the color value in the JSON response.
+3. **Interface rendering**: when processing cells, the frontend checks for the linked color property and renders a **Tag** badge using the hex value, calculating a text color with adequate contrast.
+
+This architecture ensures efficiency without modifying the standard payload. Color values update in real time in the **Form View**, the **Main Grid View**, and during **Inline Editing**.
+
+## Step-by-Step: Configuring Color in Product Category
+
+The following procedure uses `M_Product_Category` as an example.
+
+### 1. Add the Color Column in the Data Dictionary
+
+1. Access the Etendo ERP Classic environment with the **System Administrator** role.
+2. Navigate to the **Tables and Columns** window.
+3. Search for the master table — in this case, `M_Product_Category` (Product Category).
+4. In the **Columns** tab, create a new column using the module prefix (e.g., `EM_CRM_Color` or `EM_SMF_Color`).
+5. Assign the **Color** reference type to the new column. This is the key step that allows the system to recognize the column's purpose.
+6. Set the length to 7 or 10 characters — sufficient to store a hex code such as `#FF0000`.
+
+!!! note
+    Using the **Color** reference type allows the backend to detect the column's purpose independently of its name, integrating it transparently into the metadata read by the frontend.
+
+### 2. Apply Database Changes and Show the Column
+
+1. Apply the changes by compiling the system:
+
+    ```bash title="Terminal"
+    ./gradlew smartbuild
+    ```
+
+2. Navigate to the **Window, Tab and Field** window in Etendo Classic.
+3. Search for the **Product Category** window.
+4. In the **Field** tab, add or reload the record for the new column so it appears in the classic ERP interface.
+
+### 3. Verify the Configuration
+
+1. Open the **Product Category** window in Etendo Classic.
+2. Select an existing record (e.g., the category *Standard*).
+3. Enter a hex color value in the new field (e.g., `#8E44AD`) and save.
+4. Open the Workspace UI and navigate to the **Products** window (`M_Product`).
+5. In the products grid, locate the **Product Category** column (`M_Product_Category_ID`).
+
+The frontend detects the color configuration, adds the `_extraProperties` request parameter, and renders the category value as a colored badge.
+
+!!! info
+    This behavior is module-agnostic and variable-agnostic. Any master table with a column configured with the **Color** reference type is automatically supported across grids and forms without additional development.
+
+## Scope and Restrictions
+
+### Affected Fields
+
+Color badge rendering applies only to **Foreign Key fields (TableDir / Table)** that reference a master table with a color column configured. Examples:
+
+- `M_Product_Category_ID` in the Products table.
+- `Priority_ID` in the Tasks table.
+- `C_Currency_ID` in the Invoices table.
+
+### Fields Not Affected
+
+This feature does not affect:
+
+- Plain text fields (Strings).
+- Numeric, date, or boolean fields.
+- Static list dropdowns (*List* reference type) defined in Reference domains.
+
+---
+This work is licensed under :material-creative-commons: :fontawesome-brands-creative-commons-by: :fontawesome-brands-creative-commons-sa: [ CC BY-SA 2.5 ES](https://creativecommons.org/licenses/by-sa/2.5/es/){target="_blank"} by [Futit Services S.L](https://etendo.software){target="_blank"}.

docs/es/developer-guide/etendo-classic/how-to-guides/how-to-configure-color-system.md

@@ -0,0 +1,89 @@
+---
+tags:
+  - How to
+  - Color System
+  - UI
+  - Extensibility
+
+status: new
+---
+
+# Cómo configurar el soporte del sistema de color en la UI
+
+## Visión general
+
+El sistema de color en Etendo permite asignar identificadores visuales (etiquetas de color) a registros dentro de una rejilla o formulario en la UI de Workspace, mejorando la experiencia de usuario al resaltar información clave. Esta funcionalidad utiliza el sistema de extensibilidad de Etendo y puede aplicarse sin modificar el código base de la interfaz gráfica.
+
+Un caso de uso común es aplicarlo a tablas maestras como **Categoría de producto** (`M_Product_Category`) o **Grupo de terceros** (`C_BP_Group`), ya que se referencian con frecuencia en rejillas principales como Productos o Clientes.
+
+## Cómo funciona el sistema de color
+
+Para que un color aparezca en la UI, el campo en la tabla principal debe referenciar una tabla maestra mediante una clave foránea (referencia **TableDir** o **Tabla**). La UI de Workspace y Etendo se coordinan mediante una interacción entre los metadatos y el frontend en React:
+
+1. **Inyección de metadatos**: el backend comprueba si el diccionario de datos tiene la columna configurada con el tipo de referencia **Color**. Si es así, inyecta `colorFieldName` en los metadatos gráficos para indicar el nombre de la propiedad.
+2. **Petición del frontend**: los hooks de obtención de datos (Datasource) en Next.js evalúan cada columna definida. Si una columna especifica metadatos `colorFieldName`, el frontend añade la dependencia como `_extraProperties` a la petición de la API (p. ej., `_extraProperties=M_Product_Category_ID$EM_SMF_Color`), lo que indica al backend que realice los JOIN correspondientes y devuelva el valor de color en la respuesta JSON.
+3. **Renderizado de la interfaz**: al procesar las celdas, el frontend comprueba la propiedad de color enlazada y renderiza una insignia **Tag** usando el valor hex, calculando un color de texto con contraste adecuado.
+
+Esta arquitectura garantiza eficiencia sin modificar el payload estándar. Los valores de color se actualizan en tiempo real en la **Vista de formulario**, la **Vista principal de rejilla** y durante la **edición en línea**.
+
+## Paso a paso: configurar Color en Categoría de producto
+
+El siguiente procedimiento usa `M_Product_Category` como ejemplo.
+
+### 1. Añadir la columna Color en el diccionario de datos
+
+1. Accede al entorno Etendo ERP Classic con el rol **Administrador del sistema**.
+2. Navega a la ventana **Tablas y columnas**.
+3. Busca la tabla maestra — en este caso, `M_Product_Category` (Categoría de producto).
+4. En la pestaña **Columnas**, crea una nueva columna usando el prefijo del módulo (p. ej., `EM_CRM_Color` o `EM_SMF_Color`).
+5. Asigna el tipo de referencia **Color** a la nueva columna. Este es el paso clave que permite al sistema reconocer el propósito de la columna.
+6. Establece la longitud en 7 o 10 caracteres — suficiente para almacenar un código hex como `#FF0000`.
+
+!!! note
+    Usar el tipo de referencia **Color** permite al backend detectar el propósito de la columna independientemente de su nombre, integrándola de forma transparente en los metadatos leídos por el frontend.
+
+### 2. Aplicar cambios en base de datos y mostrar la columna
+
+1. Aplica los cambios compilando el sistema:
+
+    ```bash title="Terminal"
+    ./gradlew smartbuild
+    ```
+
+2. Navega a la ventana **Ventana, pestaña y campo** en Etendo Classic.
+3. Busca la ventana **Categoría de producto**.
+4. En la pestaña **Campo**, añade o recarga el registro de la nueva columna para que aparezca en la interfaz del ERP Classic.
+
+### 3. Verificar la configuración
+
+1. Abre la ventana **Categoría de producto** en Etendo Classic.
+2. Selecciona un registro existente (p. ej., la categoría *Standard*).
+3. Introduce un valor de color hex en el nuevo campo (p. ej., `#8E44AD`) y guarda.
+4. Abre la UI de Workspace y navega a la ventana **Productos** (`M_Product`).
+5. En la rejilla de productos, localiza la columna **Categoría de producto** (`M_Product_Category_ID`).
+
+El frontend detecta la configuración de color, añade el parámetro de petición `_extraProperties` y renderiza el valor de la categoría como una insignia coloreada.
+
+!!! info
+    Este comportamiento es agnóstico al módulo y agnóstico a la variable. Cualquier tabla maestra con una columna configurada con el tipo de referencia **Color** se soporta automáticamente en rejillas y formularios sin desarrollo adicional.
+
+## Alcance y restricciones
+
+### Campos afectados
+
+El renderizado de insignias de color se aplica solo a **campos de clave foránea (TableDir / Tabla)** que referencian una tabla maestra con una columna de color configurada. Ejemplos:
+
+- `M_Product_Category_ID` en la tabla Productos.
+- `Priority_ID` en la tabla Tareas.
+- `C_Currency_ID` en la tabla Facturas.
+
+### Campos no afectados
+
+Esta funcionalidad no afecta a:
+
+- Campos de texto plano (Strings).
+- Campos numéricos, de fecha o booleanos.
+- Desplegables de lista estática (tipo de referencia *List*) definidos en dominios de referencia.
+
+---
+This work is licensed under :material-creative-commons: :fontawesome-brands-creative-commons-by: :fontawesome-brands-creative-commons-sa: [ CC BY-SA 2.5 ES](https://creativecommons.org/licenses/by-sa/2.5/es/){target="_blank"} by [Futit Services S.L](https://etendo.software){target="_blank"}.

docs/es/user-guide/new-ui/how-to-guides/how-to-configure-color-system.md

@@ -0,0 +1,83 @@
+---
+tags:
+  - How to
+  - Color System
+  - UI
+  - Extensibility
+---
+
+# Cómo Configurar el Soporte al Sistema de Colores en la UI
+
+## Visión General
+
+El sistema de colores en Etendo permite asignar identificadores visuales (pastillas de color) a registros dentro de una grilla o formulario en Workspace UI, mejorando la experiencia del usuario al destacar información clave. Esta funcionalidad aprovecha el sistema de extensibilidad de Etendo para aplicarse transparentemente sin necesidad de alterar el código base de la interfaz gráfica.
+
+Un excelente caso de uso (y uno de los más visuales) es aplicarlo a tablas maestras como la **Categoría de Producto (M_Product_Category)** o el **Grupo de Terceros (C_BP_Group)**, ya que estas son muy utilizadas dentro de grillas principales (como la grilla de Productos o la de Terceros/Clientes).
+
+## ¿Cómo funciona la relación con la otra tabla?
+
+Para que el color se refleje en la UI, el campo en cuestión en la tabla principal debe apuntar a una tabla maestra a través de una Foreign Key (Referencia **TableDir** o **Table**). 
+
+La implementación actual en Workspace UI y Etendo funciona de manera coordinada gracias a una simbiosis entre la metadata y el frontend de React:
+
+1. **Inyección de Metadata:** El backend deduce si una tabla hija necesita mostrar un color verificando si el diccionario de datos tiene configurada la columna con la Referencia asignada al tipo "Color". De ser así, inyecta `colorFieldName` indicando cómo se llama esta propiedad hacia la metadata gráfica.
+2. **Petición del lado del Front:** Los hooks de obtención de datos (Datasource) en NextJS revisan activamente cada columna definida. Si alguna especifica la metadata `colorFieldName`, el frontend añade al vuelo esa dependencia para solicitarla en la Request a la API (ej: `_extraProperties=M_Product_Category_ID$EM_SMF_Color`). Esto le fuerza al backend a hacer los JOIN correspondientes y volcar el valor final del color al formato JSON.
+3. **Renderizado en la Interfaz:** Al momento de procesar las celdas, el frontend comprueba si recibió esta propiedad vinculada al color y le asigna automáticamente el componente visual en forma de 'Tag' (pastilla envuelta), usando el valor hexa recuperado y calculando un texto con buen contraste de legibilidad.
+
+Esta arquitectura explícita garantiza eficiencia sin corromper el payload estándar. De igual manera, se actualiza en tiempo real tanto en la **Vista de Formulario (Form View)**, en la **Vista de Grilla Principal (Grid View)**, y a la hora de mutar la información por medio de la **Edición en Línea (Inline Editing)** (donde el cliente vuelve a efectuar una petición del registro pidiendo los `_extraProperties` de colores al guardar exitosamente).
+
+## Paso a Paso: Configurar el Color en la Categoría de Productos
+
+A continuación, se detalla el procedimiento exacto para probar e implementar esto utilizando la tabla `M_Product_Category` como ejemplo:
+
+### 1. Agregar la columna de Color en el Diccionario de Datos
+
+1. Ingresa a tu entorno de **Etendo ERP Classic** con el rol de **System Administrator** (Administrador del Sistema).
+2. Ve a la ventana **Tables and Columns** (Tablas y Columnas).
+3. Busca la tabla maestra de interés, en este caso `M_Product_Category` (Categoría de Producto).
+4. En la pestaña de *Columns*, crea una nueva columna utilizando tu prefijo de módulo (por ejemplo `EM_CRM_Color` o usar el prefijo de tu módulo de pruebas activo).
+5. Asigna a esta nueva columna el tipo de referencia **Color**. Esta es la instrucción clave y mejor práctica para que el sistema reconozca oficial y estructuradamente que este campo soportará colores.
+6. La longitud ideal es de 7 o 10 caracteres; suficientes para guardar en su interior un código hexadecimal (`#FF0000`).
+
+!!!note "Nota clave"
+      Al utilizar el Reference "Color", el backend detectará explícita y correctamente el propósito de tu columna sin depender del nombre exacto bajo el que la registres, integrándola transparentemente a la metadata que lee el frontend.
+
+### 2. Aplicar la tabla en la BD y mostrar la columna
+
+Luego de definir la columna en el diccionario de datos, debes materializarla en la base de datos:
+1. Aplica los cambios mediante el proceso clásico compilando en consola (ej. `gradlew smartbuild` o reconstruyendo de manera apropiada la base de datos).
+2. Ve a la ventana **Window, Tab and Field** (Ventana, Pestaña y Campo) dentro del entorno Etendo.
+3. Busca la ventana correspondiente, en este caso **Product Category**.
+4. Asegúrate recargar la pestaña o cerciorarte de agregar/crear el registro para la pestaña central de **Field** respecto a esa nueva columna, logrando así que el campo esté listo para ser usado y se visualice en la interfaz del ERP clásico.
+
+### 3. Prueba de Fuego (¡La Magia Visual!)
+
+1. Abre la ventana **Product Category** (Categoría de Producto) en Etendo Classic.
+2. Selecciona un registro existente, por ejemplo la categoría titulada "Standard" (o directamente sobre la que decidas usar).
+3. Escribe un valor hexadecimal identificativo y bien llamativo sobre el nuevo campo de color. Por ejemplo: `#8E44AD` (Un color púrpura oscuro), y guarda finalmente el registro.
+4. Ahora, ve a través del frontend de **NextJS de Workspace UI**.
+5. Abre la ventana principal respectiva para **Products** (Productos o `M_Product`).
+6. En aquella grilla resultante de productos, busca la columna "Categoría de Producto" (`M_Product_Category_ID`).
+7. **¡Sorpresa!** Si esta categoría suele verse como un simple texto azul detallando el contenido "Standard", ahora notarás un cambio muy atractivo. Al pedirse los datos, el frontend detectará que hay una configuración para pedir metadatos de ese color (`_extraProperties`), inyectará la petición extra, la base de datos lo procesará automáticamente por detrás y la UI terminará pintando el texto en una hermosa pastilla redondeada color púrpura.
+
+Lo genial de este diseño es que todo ha quedado **totalmente agnóstico de módulos y variables específicas**. Siempre que la tabla maestra cuente con una columna configurada con el Reference "Color", el componente subyacente de UI la aprovechará sin problemas. Uno puede aplicarlo a tablas de Monedas, Métodos de Pago, Vendedores o Almacenes... e instantáneamente brotarán coloreadas en la grilla y formulario sin que se requiera programar ni un solo componente auxiliar.
+
+## Restricciones y Análisis de Alcance
+
+### ¿A qué campos afecta y permite intervenir?
+
+La lógica dinámica de inyección de metadata y renderizado de pastillas de color **solo afecta a campos (Fields) definidos como tipo de Referencia Foránea (Foreign Keys / TableDir / Table)** hacia la tabla maestra que ya cuenta con la columna de color configurada. Algunos ejemplos concisos incluyen:
+
+* `M_Product_Category_ID` apuntando en la tabla de Productos.
+* `Priority_ID` reflejándose en la tabla de Tareas.
+* `C_Currency_ID` visualizándose en la tabla de Facturas.
+
+### ¿A qué campos NO afecta o resultan omitidos?
+
+Su dinámica de control actual **NO afectará o incidirá bajo los elementos a continuación especificables**:
+
+* Campos de texto estáticos y regulares (Cadenas o *Strings* convencionales).
+* Valores Numéricos, Fechas naturales o datos de tipo Booleanos.
+* Listas estáticas predefinidas en el sistema (Es decir, menús desplegables del propio tipo *List* codificados de forma fija o *hardcodeada* bajo los dominios de las Listas de Referencia en el diccionario).
+
+---