Custom Form Fields

Rulebooks can be used to add custom fields to topic forms. Every time a topic is opened, the form renderer engine first checks for the existence of form field rules and executes them.

Note

This only works for topics that have its project field assigned. Otherwise, the custom field system would not know which rulebook to apply from many different projects.

If you need a custom field to be applied globally, the project to which your rulebook belongs must be a global project.

Form field rules

Form field rules are made of a sequence of ops, just like any other rule in Clarive. But instead of executing commands or sending files remotely, form field rules output field definitions called fieldlets.

There are special form field events that we can create rules for.

The following list of events may be different, depending on the profile(s) installed in Clarive SE. In Clarive EE the set of customizable form events may be completely different since new events can be defined at the administrators discretion.

Event	Description
any_form	adds a field to all forms
form_feature	adds a field to feature form types
form_bugfix	adds a field to bugfix forms
form_sprint	adds a field to sprint forms
form_release	adds a field to release forms
form_epic	adds a field to sprint forms
form_hotfix	adds a field to hotfix forms
form_story	adds a field to story forms
form_task	adds a field to task forms
form_task_template	adds a field to task template
form_[custom_category]	adds a field to custom category forms

For example, to add different fields to the bugfix topic form, use the following rulebook structure:

name: my custom fields

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

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

For conciseness, you can group field definitions with the def op.

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:

You can even parametrize the fields with variables to make it more adaptable.

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

Available Fieldlets

• field_text - simple text field

• field_date - simple date field

• field_time - simple time field

• field_textarea - a multiline text field

• field_richtext - rich HTML-based text editor

• field_combo - a drop-down combo box with a static list of options

• field_pills - selectable visual options

• field_grid - a multi-column table

• field_upload - an attachment field

Getting the form context

In every form event rule, the following variables are available. These variables are useful in making the fields conditional to things like security or topic situation.

Variable	Description
username	id of the user opening the topic
category	name of the topic category
topic_mid	mid of the topic (not available if it's a new topic)

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

Common Arguments

Every field_* type op has a set of common arguments that can be used to configure the form field.

Argument	Required?	Type	Default
id	required	string	-
label	required	string	-
colspan	optional	num (1-12)	12 (max width)
rowspan	optional	num ( >2 )	(according to field)
default	optional	any	-
required	optional	bool	false
edit	optional	bool	true
view	optional	bool	true
active	optional	bool	true
readonly	optional	bool	false

label (required)

Label is the text that show up next to the field.

id (required)

When the topic data is stored in the database, it's stored with a field id.

Field ids are important as you may want to use them later in other event or pipeline rules to extract configuration data from them.

Field ids have to be all lowercase, start with alpha characters (from a to z) and be followed by any character from alphanumeric characters and underscore.

Example ids:

• my_field (ok)

• _my_field (not ok)

• 2017field (not ok)

• someField (not ok)

Tip

Prefix all your fields with a recognizable identifier so that you can easily remember them while keeping the database organized. Also, use snake notation (underscore separators) for more clarity.

For instance, if your fields were related to work estimates they could be prefixed with the string estimate_, such as estimate_date, estimate_description etc.

colspan

Number of columns that the field will occupy in the edit mode, a number from 1 to 12.

rowspan

Number of rows that the field will occupy in the edit mode, minimum is 2.

The form grid layout manager will try to accomodate the fieldlet within the grid, which also takes into consideration the rows of other fields visible.

default

Default value for the field.

required

If a field is required (set to true or to 1, the topic can only be saved if the field has data.

edit

Boolean that determines if the field can be seen in the topic editor panel.

Set edit to false if the field should not be visible in the editor panel. Default is true.

view

Boolean that determines if the field can be seen in the view panel of the topic (main panel). Default is true.

readonly

Boolean that determines if the field can be modified in the edit mode. Default is false, meaning a field can always be modified.

Field ops

field_text

This field will create a simple, one line text field.

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

field_textarea

A text field that is multi-line. The text has no formatting. For a formatted text field, use the field_richtext op instead.

Use the rowspan parameter to configure the field height.

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

field_richtext

This opens a rich HTML-based text editor, which supports text and paragraph formatting, visual queues, such as lists and image pasting.

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

field_date

A date field which opens a calendar.

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

field_time

A time field.

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

field_pills

Pills are option buttons that are highlighted in color and shown as badges.

Pills are great for short selection lists (from 2 to 4) that are also very easy to see and click. Each option should have at least the parameter name: and optionally color:.

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

field_grid

Grids are a multi-column table that holds sub-fields. You can define from one to many columns, but try to limit columns to 4 or 5 max, otherwise it may not fit into users screen properly and may become difficult to read.

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

Each column accepts these common parameters:

Parameter	Description	Default
id	The column id used to store into the db	If no id set, name is converted to id
name	The column header text	(required)
type	Type of field for the column (list of types below)	textfield
width	The column width in pixels	100
default	The default value for the field	(none)
sortable	If the column is sortable or not	true
readonly	If the column is readonly	false

This is the set of column types to pick from:

Column Type	Description	Additional Options
textfield	single line text	none
textarea	multi line text	none
checkbox	A simple checkbox	none
combo	A simple checkbox	options: [ 'column1', 'column2' ]
date	A date picker	none
projects	Drop-down list of all projects in the system	none
users	Drop-down list of all users in the system	none
environments	Drop-down list of all environments in the system	none

To set a default value to a column field, just add default: to the list of options.

    # ...

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

field_combo

This is a drop-down combo with a fixed set of values passed as an array in the parameter options.

To set a default value, use the name of the option.

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

field_upload

This field enables users to upload one or more files. Files uploaded are attached to the topic and are stored in the database.

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

Additional Form Ops

There are also a few additional form ops that allow your rulebook to control existing fields, like removing predefined fields from view or make them readonly.

remove_fields

The remove_fields op will take the selected field out of the edit and view topic panels, so that the field will be invisible for the user.

The remove_fields op accepts an array as argument with the labels (or ids) of the individual fields to be removed.

any_form:
    - remove_fields:
          - Reviewer

readonly_fields

The readonly_fields op will make one or more fields readonly, meaning the user will be able to see it, but not change its value.

The readonly_fields op accepts an array as argument with the labels (or ids) of the individual fields to be changed into readonly mode.

any_form:
    - readonly_fields:
          - Reviewer
          - Assigned