Table Grid configuration basics

Create a new Table Grid

A table grid is configured as a custom field for an issue.

You can create a custom field of the type 'Table Grid Editor' using the Admin > Add Custom field

Choose the Table Grid Editor as field type

Give the field a name and a description and define its context, just like you do when creating other custom fields.

Make sure that you limit the context of the custom field to the projects that are effectively using the custom field.

Configure the grid field

The configuration of a grid is done through the standard custom field configuration of JIRA.
All configuration details for a specific table grid need to be entered in the default field value of a custom field.

By default, a new table grid field is filled with a sample configuration. You can override or change this configuration to match it to your needs.
Next chapters will explain in detail how to configure a table grid.

Format of the configuration

The grid is using the standard java properties file format to read and interpret the grid properties.

Each line stores a single property
Each property is stored as a pair or strings separated by a = as on examples below
gd.columns = Invoice, Product, Number, Comment

col.Product.list.query = select name,prodcode from productlist
The first part is the key, the second part is the value
the key can be multilevel
For instance col.product.list.query has 4 levels
Keys are not case sensitive in general except for column names and datasource names.
- gd.columns is identical to GD.Columns
- col.FirstName is different from col.firstname
- gd.ds = CRM is different from gd.ds = crm
Values are case sensitive depending on what they represent, check the individual property specification pages for more details.
If the first character on a line is the number sign (#), all the remaining text on that line is interpreted as a comment
The order of properties is not important.
For clarity and maintenance, it is best to group similar properties together.

Structure of the grid configuration

A table grid configuration has 4 main sections

Grid details
Use these properties to specify the grid behavior and define columns.
Grid initialization properties
You can initialize a grid statically or dynamically and set up the database where the grid data should be stored.
Column details
Define columns type and behavior using these properties. Details should be specified for each column separately.
Grid Display Parameters
You can set up the grid display options using these properties.

Connecting to a database

There are two options to connect the grid to a database. You can connect to one or more databases.

Using a Datasource Specification
Embedded into the grid configuration using the database connection properties

Column types

The grid supports multiple types, where each type has a specific behavior

Configuration validation

When saving the grid configuration, the plugin will apply a number of validations such as

Are all the columns properly defined ?
Are the properties correctly set ?
Can it connect to the database ?

A warning message is provided in case something is wrong with the configuration itself

Configuration example

Below you can see an example of the grid configuration with explanation.

# General grid properties section
#----------------------------------------
# gd.columns is used to define the columns which make up the grid
# gd.tablename and gd.ds are used to specify 
# where the data of the grid should be stored
# It is possible to store the grid data in an external database
#
gd.columns=isummary,iassignee,istatus,iquantity,iprice,itotal,idue
gd.tablename=actions
gd.ds=jira



#Summary column configuration
#----------------------------------------
# Various column properties are used to specify the behaviour
# of the column (such as width, type, etc.)
#
col.isummary=Summary
col.isummary.name=summary
col.isummary.type=string
col.isummary.required=true
col.isummary.maxLength=128
col.isummary.width=400



#Assignee column configuration
#----------------------------------------
# The assignee column is a list column initialized with 
# all the users listed in JIRA
# (This list could also be restricted to users who have certain role(s) 
# in the current project or are members of a certain group(s)
# by specifying col.iassignee.allow.groups 
# and col.iassignee.allow.roles properties respectively)
#
col.iassignee=Assignee
col.iassignee.type=userlist
col.iassignee.required=true
col.iassignee.autocomplete=true
col.iassignee.width=100



#Status column configuration
#----------------------------------------
# The status column is a list column with statically defined values.
# Alternatively it could be a checkbox or a radio button.
#
col.istatus=Status
col.istatus.type=list
col.istatus.list.size=2
col.istatus.name1=Open
col.istatus.value1=O
col.istatus.name2=Done
col.istatus.value2=D
col.istatus.width=60
col.istatus.defaultValue=O



#Quantity column configuration
#----------------------------------------
# The quantity column is a list column with statically defined values.
#
col.iquantity=Quantity
col.iquantity.type=list
col.iquantity.list.size=5
col.iquantity.name1=1
col.iquantity.value1=1
col.iquantity.name2=2
col.iquantity.value2=2
col.iquantity.name3=3
col.iquantity.value3=3
col.iquantity.name4=4
col.iquantity.value4=4
col.iquantity.name5=5
col.iquantity.value5=5



#Price column configuration
#----------------------------------------
# The price column is a list column with statically defined values.
#
col.iprice=Price
col.iprice.type=list
col.iprice.list.size=5
col.iprice.name1=10
col.iprice.value1=10
col.iprice.name2=20
col.iprice.value2=20
col.iprice.name3=30
col.iprice.value3=30
col.iprice.name4=40
col.iprice.value4=40
col.iprice.name5=50
col.iprice.value5=50



#Formula column configuration
#----------------------------------------
# The total column is a formula column that displays formula results.
#
col.itotal=Total
col.itotal.type=number
col.itotal.formula={iquantity}*{iprice}


#Set current date in the date column
#----------------------------------------
# The due date column is of type 'date'
# The defaultDate is automatically set to a current date.
#
col.idue=Due date
col.idue.type=date
col.idue.defaultDate = +0d

Run time interpretation

The configuration is interpreted each time a grid is rendered, so you can make a modification to a configuration and view its impact on the grid, by refreshing an issue page.

Table Grid Editor (legacy) Documentation