We are at Atlassian Summit - which will affect our response times. Meet us there (if you happen to be in San Jose)

Skip to end of metadata
Go to start of metadata

Create a new Table Grid

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

JIRA admins 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 plugin is using the standard java properties file format to
read and interpret the properties.

  • Each line stores a single property
  • Each property is stored as a pair or strings separated by a '='
    For instance

    gd.columns=Invoice, Product, Number, Comment
    

    or

    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 these 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

  • The grid details
    The grid details are used to specify the behavior of the grid, the columns and how the grid should be initialized
  • The grid initialization properties
    A grid can be initialized in various ways.
  • The column details
    The column details are used to specify the column behavior, create one column detail for each column in the grid.

Connecting to a database

There are two options to connect to one (or more databases)

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

Column types

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

PropertyUsage
col.xyz.type Specify what type of values can be stored in a column, defines the behaviour of the plugin.
col.xyz.type = checkbox  Show checkbox options when editing a cell.
col.xyz.type = date Formats the column as a date. When editing a cell, brings up a calendar popup.
col.xyz.type = datetime Enter a date time field
col.xyz.type = integer Use this when the column should store plain integer number fields such as 1234, -789, ...
col.xyz.type = list Create a dropdown list which is either initialized using a static list or using a query.
col.xyz.type = number Use this when the column should store number fields with a decimal (such as 1.5, -212.34 ...)
col.xyz.type = radio  To present a radio button group to the user
col.xyz.type = sequence Give each row in the grid a unique id.
col.xyz.type = string The column is used to enter a single line of text.
col.xyz.type = textarea This type allows the user to enter multiple lines of text
col.xyz.type = userlist This column type provides a dropdown listing JIRA users. This type has additional properties allowing to filter the users

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.

 


  • No labels