CompositeGrid

This element works similarly to the Grid element, but offers much more flexibility and customization.

Declaration

This element is declared as an object with "element_type": "CompositeGrid" property.

The maximum number of digits in the combined response is specified in the columns_count property.

A set of characters to be drawn inside bubbles is specified in the values array.

{
	"element_type": "CompositeGrid",
	"columns_count": 3,
	"values": ["U", "S", "A"]
}

Required properties

Name Type Description
element_type string Must be "CompositeGrid" (case-insensitive).
columns_count integer The maximum number of symbols in the combined response. Each symbol is represented as a line or column of bubbles, depending on the element’s orientation property.
values array Characters to be drawn inside bubbles.

Optional properties

Name Type Default value Description
name string n/a Used as an element’s identifier in recognition results and is displayed as a label on the form.
extra_row array of arrays n/a Each array provided in this property adds a custom line / column of bubbles at the start of the grid. Characters drawn inside these bubbles may differ from those provided in values property.
A set of characters that will be displayed inside the bubbles of a particular line / column is defined as an array of strings. The length of the array cannot be less than the value of the columns_count property. To hide certain bubbles, provide an empty string ("") at their positions.
align string “left” Horizontal alignment of Grid element: "left", "center" or "right".
orientation string “horizontal” Element’s orientation:
  • "horizontal" - each digit is represented as a column of bubbles;
  • "vertical" - each digit is represented as a row of bubbles.
rotate integer 0 Rotate the element by the given degree. The following values are supported: 90, 180, 270.
header_type string “underline” The type of the box to be displayed in front of each column / row. This box can be used for hand-writing the answer in addition to marking bubbles.
  • "underline" - draw a horizontal line.
  • "square" - draw a box.
header_border_size integer 3 Border width of the box to be displayed in front of each column / row.
header_border_color string “black” Border color of the box to be displayed in front of each column / row. Can be picked from one of the supported values.
vertical_margin integer 0 Vertical spacing between the element’s lines, in pixels.
bubble_size string “normal” Size of bubbles: "extrasmall", "small", "normal", "large", or "extralarge".
bubble_type string “round” Bubble style: "round" or "square".
x integer n/a Set the absolute position of the Grid element relative to the left edge of the page.
Overrides the value of align property.
y integer n/a Set the absolute position of the Grid element relative to the top edge of the page.
column integer 1 The number of the column where the Grid element will be placed. Only applicable if Grid is placed in a multi-column Container element.
display_hint boolean true Show (true) or hide (false) the label above the element.

Allowed child elements

None.

Recognition behavior

Numbers from each marked bubble are merged into a single number.

If the respondent marks more than one bubble per row / column (depending on the orientation attribute), the affected CompositeGrid element will not be recognized and an error will be written to the recognition results.

Examples

Check out the code examples to see how CompositeGrid elements can be used.

Bank security word

{
	"element_type": "Template",
	"children": [
		{
			"element_type": "Page",
			"children": [
				{
					"element_type": "CompositeGrid",
					"name": "Security word",
					"columns_count": 8,
					"values": ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z"]
				}
			]
		}
	]
}

Bank security word

Recognition result

PASSWORD

Formula

{
	"element_type": "Template",
	"children": [
		{
			"element_type": "Page",
			"children": [
				{
					"element_type": "CompositeGrid",
					"name": "Formula",
					"columns_count": 5,
					"values": ["X", "Y"],
					"extra_row": [
						["1", "2", "3", "4", "5"],
						["", "+", "+", "+", ""],
						["", "=", "=", "=", ""]
					]
				}
			]
		}
	]
}

Formula

Recognition result

X+Y=5

Rotated

{
	"element_type": "Template",
	"children": [
		{
			"element_type": "Page",
			"children": [
				{
					"element_type": "CompositeGrid",
					"name": "Rotated",
					"columns_count": 5,
					"values": ["1", "2", "3", "4", "5"],
					"orientation": "vertical",
					"rotate": 90
				}
			]
		}
	]
}

Rotated

CustomAnswerSheet