Campos de Formulario Personalizados

Los Rulebooks pueden usarse para agregar campos personalizados a los formularios de topics. Cada vez que se abre un topic, el motor de renderizado de formularios primero verifica la existencia de reglas de campos de formulario y las ejecuta.

Note

Esto solo funciona para topics que tienen asignado su campo de proyecto. De lo contrario, el sistema de campos personalizados no sabría qué rulebook aplicar de muchos proyectos diferentes.

Si necesita que un campo personalizado se aplique globalmente, el proyecto al que pertenece su rulebook debe ser un proyecto global.

Reglas de campos de formulario¶

Las reglas de campos de formulario están compuestas de una secuencia de ops, al igual que cualquier otra regla en Clarive. Pero en lugar de ejecutar comandos o enviar archivos remotamente, las reglas de campos de formulario generan definiciones de campos llamadas fieldlets.

Hay eventos especiales de campos de formulario para los que podemos crear reglas.

La siguiente lista de eventos puede ser diferente, dependiendo de los perfiles instalados en Clarive SE. En Clarive EE, el conjunto de eventos de formulario personalizables puede ser completamente diferente, ya que se pueden definir nuevos eventos a discreción de los administradores.

Evento	Descripción
any_form	agrega un campo a todos los formularios
form_feature	agrega un campo a tipos de formulario de feature
form_bugfix	agrega un campo a formularios de bugfix
form_sprint	agrega un campo a formularios de sprint
form_release	agrega un campo a formularios de release
form_epic	agrega un campo a formularios de sprint
form_hotfix	agrega un campo a formularios de hotfix
form_story	agrega un campo a formularios de story
form_task	agrega un campo a formularios de task
form_task_template	agrega un campo a plantillas de task
form_[custom_category]	agrega un campo a formularios de categoría personalizada

Por ejemplo, para agregar diferentes campos al formulario de topic bugfix, use la siguiente estructura de rulebook:

name: my custom fields

form_bugfix:
   - field_text:
        label: "Estimated duration"
        id: estimated_duration

form_sprint:
   - field_text:
        label: "Estimated duration"
        id: estimated_duration

Para mayor concisión, puede agrupar definiciones de campos con el op def.

name: grouped custom fields

def:
   time_management:
       - field_text:
             label: "Estimated duration"
             id: estimated_duration
       - field_date:
             label: "Estimated end-date"
             id: enddate

form_bugfix:
    - time_management:

form_sprint:
    - time_management:

Incluso puede parametrizar los campos con variables para hacerlos más adaptables.

name: grouped custom fields

def:
   time_management (show_date):
       - field_text:
             label: "Estimated duration"
             id: estimated_duration
       - if: {{ show_date }}
         then:
           - field_date:
                 label: "Estimated end-date"
                 id: enddate

form_bugfix:
    - time_management:
          show_date: false

form_sprint:
    - time_management:
          show_date: true

Fieldlets Disponibles¶

field_text - campo de texto simple
field_date - campo de fecha simple
field_time - campo de hora simple
field_textarea - campo de texto multilínea
field_richtext - editor de texto enriquecido basado en HTML
field_combo - cuadro combinado desplegable con una lista estática de opciones
field_pills - opciones visuales seleccionables
field_grid - tabla de múltiples columnas
field_upload - campo de adjunto

Obtener el contexto del formulario¶

En cada regla de evento de formulario, las siguientes variables están disponibles. Estas variables son útiles para hacer que los campos sean condicionales a cosas como seguridad o situación del topic.

Variable	Descripción
username	id del usuario que abre el topic
category	nombre de la categoría del topic
topic_mid	mid del topic (no disponible si es un topic nuevo)

any_form:
    - if: "{{ ctx.status('name') == 'In Progress' }}"
      then:
         - field_text:
              label: Assigned Tester
              id: tester

Argumentos Comunes¶

Cada tipo de op field_* tiene un conjunto de argumentos comunes que pueden usarse para configurar el campo de formulario.

Argumento	¿Requerido?	Tipo	Predeterminado
`id`	requerido	string	-
`label`	requerido	string	-
`colspan`	opcional	num (1-12)	12 (ancho máximo)
`rowspan`	opcional	num ( >2 )	(según el campo)
`default`	opcional	any	-
`required`	opcional	bool	false
`edit`	opcional	bool	true
`view`	opcional	bool	true
`active`	opcional	bool	true
`readonly`	opcional	bool	false

label (requerido)¶

Label es el texto que aparece junto al campo.

id (requerido)¶

Cuando los datos del topic se almacenan en la base de datos, se almacenan con un id de campo.

Los ids de campo son importantes ya que puede querer usarlos más tarde en otras reglas de evento o pipeline para extraer datos de configuración de ellos.

Los ids de campo deben estar en minúsculas, comenzar con caracteres alfa (de a a z) y ser seguidos por cualquier carácter de caracteres alfanuméricos y guión bajo.

Ejemplos de ids:

my_field (ok)
_my_field (no ok)
2017field (no ok)
someField (no ok)

Tip

Prefije todos sus campos con un identificador reconocible para que pueda recordarlos fácilmente mientras mantiene la base de datos organizada. Además, use notación snake (separadores de guión bajo) para mayor claridad.

Por ejemplo, si sus campos estuvieran relacionados con estimaciones de trabajo, podrían tener el prefijo estimate_, como estimate_date, estimate_description, etc.

colspan¶

Número de columnas que ocupará el campo en el modo de edición, un número del 1 al 12.

rowspan¶

Número de filas que ocupará el campo en el modo de edición, el mínimo es 2.

El administrador de diseño de cuadrícula de formularios intentará acomodar el fieldlet dentro de la cuadrícula, que también tiene en cuenta las filas de otros campos visibles.

default¶

Valor predeterminado para el campo.

required¶

Si un campo es requerido (establecido en true o en 1, el topic solo puede guardarse si el campo tiene datos.

edit¶

Booleano que determina si el campo puede verse en el panel del editor de topics.

Establezca edit en false si el campo no debe ser visible en el panel del editor. El valor predeterminado es true.

view¶

Booleano que determina si el campo puede verse en el panel de vista del topic (panel principal). El valor predeterminado es true.

readonly¶

Booleano que determina si el campo puede ser modificado en el modo de edición. El valor predeterminado es false, lo que significa que un campo siempre puede modificarse.

Ops de campo¶

field_text¶

Este campo creará un campo de texto simple de una línea.

any_form:
    - field_text:
        id: next_version
        label: Next Version String

field_textarea¶

Un campo de texto de múltiples líneas. El texto no tiene formato. Para un campo de texto con formato, use el op field_richtext en su lugar.

Use el parámetro rowspan para configurar la altura del campo.

any_form:
    - field_textarea:
          id: test_description
          label: Test Case Description
          rowspan: 8

field_richtext¶

Esto abre un editor de texto enriquecido basado en HTML, que admite formato de texto y párrafo, señales visuales, como listas y pegado de imágenes.

any_form:
    - field_richtext:
          id: test_description
          label: Test Case Description
          rowspan: 8

field_date¶

Un campo de fecha que abre un calendario.

any_form:
    - field_date:
          id: target_date
          label: Target Date

field_time¶

Un campo de hora.

any_form:
    - field_time:
          id: target_date
          label: Select Delivery Time

field_pills¶

Las pills son botones de opción que se resaltan en color y se muestran como insignias.

Las pills son excelentes para listas de selección cortas (de 2 a 4) que también son muy fáciles de ver y hacer clic. Cada opción debe tener al menos el parámetro name: y opcionalmente color:.

any_form:
    - field_pills:
          id: issue_type
          label: Issue Type
          options:
           - name: High
             color: e0a0a0
           - name: Low
             color: a0a0e0

field_grid¶

Las grids son tablas de múltiples columnas que contienen subcampos. Puede definir desde una a muchas columnas, pero intente limitar las columnas a 4 o 5 como máximo, de lo contrario, es posible que no quepa correctamente en la pantalla de los usuarios y pueda volverse difícil de leer.

any_form:
    - field_grid:
         label: Testing Issues Detected
         id: testing_issues
         columns:
             - name: "By Whom"
               type: users
             - name: "Which Project"
               type: projects
             - name: Verified?
               type: checkbox
               default: true
               width: 20
             - name: Verified?
               type: checkbox
             - name: "Problem Type"
               type: combo
               default: "Translations"
               options:
                   - Code
                   - Documentation
                   - Translations

Cada columna acepta estos parámetros comunes:

Parámetro	Descripción	Predeterminado
`id`	El id de columna usado para almacenar en la bd	Si no hay id, el nombre se convierte en id
`name`	El texto del encabezado de columna	(requerido)
`type`	Tipo de campo para la columna (lista de tipos abajo)	textfield
`width`	El ancho de columna en píxeles	100
`default`	El valor predeterminado para el campo	(ninguno)
`sortable`	Si la columna es ordenable o no	true
`readonly`	Si la columna es de solo lectura	false

Este es el conjunto de tipos de columna para elegir:

Tipo de Columna	Descripción	Opciones Adicionales
`textfield`	texto de una línea	none
`textarea`	texto de múltiples líneas	none
`checkbox`	Una simple casilla de verificación	none
`combo`	Una simple casilla de verificación	`options: [ 'column1', 'column2' ]`
`date`	Un selector de fecha	none
`projects`	Lista desplegable de todos los proyectos del sistema	none
`users`	Lista desplegable de todos los usuarios del sistema	none
`environments`	Lista desplegable de todos los entornos del sistema	none

Para establecer un valor predeterminado en un campo de columna, simplemente agregue default: a la lista de opciones.

    # ...

    - field_grid:
         label: Testing Issues Detected
         id: testing_issues
         columns:
             - name: "Issue Type"
               type: combo
               default: "External"
               options:
                  - "Internal"
                  - "Documentation"
                  - "External"

field_combo¶

Este es un combo desplegable con un conjunto fijo de valores pasados como un array en el parámetro options.

Para establecer un valor predeterminado, use el nombre de la opción.

any_form:
    - field_combo:
        label: Select Speed
        default: Faster
        options:
            - Faster
            - Slower

field_upload¶

Este campo permite a los usuarios cargar uno o más archivos. Los archivos cargados se adjuntan al topic y se almacenan en la base de datos.

any_form:
    - field_upload:
        label: Upload Evidence Files
        id: evidence_files

Ops de Formulario Adicionales¶

También hay algunos ops de formulario adicionales que permiten que su rulebook controle campos existentes, como eliminar campos predefinidos de la vista o hacerlos de solo lectura.

remove_fields¶

El op remove_fields sacará el campo seleccionado de los paneles de edición y vista del topic, para que el campo sea invisible para el usuario.

El op remove_fields acepta un array como argumento con las etiquetas (o ids) de los campos individuales a eliminar.

any_form:
    - remove_fields:
          - Reviewer

readonly_fields¶

El op readonly_fields hará que uno o más campos sean de solo lectura, lo que significa que el usuario podrá verlo, pero no cambiar su valor.

El op readonly_fields acepta un array como argumento con las etiquetas (o ids) de los campos individuales a cambiar al modo de solo lectura.

any_form:
    - readonly_fields:
          - Reviewer
          - Assigned