Control: GRID

What you will learn in this chapter
GRID control
Attributes, Size and Scrolling, Background, Child controls of GRID
Reference: Actions, Data Sourcing, appearance

GRID control

Grid is a used to display data in a grid layout. The most common use of Grid is to display a set of images either from the local device or from the remote server.

You can create grid by either specifying the number of columns or the width of each column in pixels, device pixels or as a percentage of the screen width. Grid is a group control which has one or more child controls.

In XMADL, GRID control is defined as follows

<!-- Parent Control-->
<control type="GRID"...............>
  <action................./>
    <!-- Child Controls-->
    <control .........../>
    <control .........../>
    <control .........../>
    <control .........../>
</control>

Fig below shows images display in a grid layout on Android and on iOS

Attributes

Attribute Value Mandatory
type GRID Yes
x

Specifies x position (distance from the left edge of the parent control). Parent control could be screen as well. It can be expressed in percentage, or pixels (px) or device pixels (dp).

By default width in percentage is relative to its parent control. It can be made relative to screen using attribute dimensions_relative_to=”SCREEN” in screen_deck . Learn more about dimensions

Yes
y

Specifies y position (distance from the top edge of the parent control). Parent control could be screen as well. It can be expressed in percentage, or pixels (px) or device pixels (dp).

By default width in percentage is relative to its parent control. It can be made relative to screen using attribute dimensions_relative_to=”SCREEN” in screen_deck . Learn more about dimensions

Yes
width

Specifies the width of the control in percentage or pixels (px) or device pixels (dp).

By default width in percentage is relative to its parent control. It can be made relative to screen using attribute dimensions_relative_to=”SCREEN” in screen_deck . Learn more about dimensions

Yes
height

Specifies the height of the control in percentage or pixels (px) or device pixels (dp).

By default width in percentage is relative to its parent control. It can be made relative to screen using attribute dimensions_relative_to=”SCREEN” in screen_deck . Learn more about dimensions

Yes
appearance_name   Yes
data_type JSONARRAY, CURSOR (default) Yes
on_empty_show comma separated name(s) of the control that should become visible when the data set is empty. If and when the data set is available these controls will be hidden. No
local_data_source This is used to define SQL statement for reading data from the light weight local database (SQLite) that is part of the application. For example, to select the first_name from the user table, the local_data_source will be a SQL query “Select first_name from user”. No
remote_data_source This is URL (Web Address) of the remote server from where the data is fetched. The server response could be an Image, JavaScript Object Notation (JSON). More formats are will be supported in future. No
remote_request_type Defines http request type to be made to the server. Values GET, POST, PUT, DELETE No
remote_data_format This defines the format of data received back after executing the URL. Values are JSON, IMAGE. Default is JSON. No
remote_data_save_locally

This attribute directs AVM to save the remote data locally as well before passing it to the control. If the server response is JSON, AVM will attempt to save the data locally. See section Fetch local data in XMADL control element below.

Note: Local Data is always fetched after the remote data is fetched. So if remote data is first saved into the local database then the local data fetch will get the latest and greatest data.

No
column_width Column Width expressed in percentage, or pixels (px) or device pixels (dp). No
num_columns Number of columns. At least one of column_width or num_columns MUST be specified. No
vertical_spacing Vertical spacing between the grid cells. It is expressed in percentage (of height), or pixels (px) or device pixels (dp). Yes
horizontal_spacing Horizontal spacing between the grid cells. It is expressed in percentage (of width), or pixels (px) or device pixels (dp). Yes
on_empty_show Specify a control name. If the data source does not fetches any data for the GRID control, then this control is shown. Yes
    Yes

Note

If the data_type is CURSOR, then local_data_source must be defined. Learn more about Data Sourcing

Size and Scrolling

The size of the grid is determined by the attributes width and height. height attribute determines the maximum height of GRID on the device screen. When the height of all grid cells (vertically) combined together exceeds the height of the GRID control, scroll bar appears automatically.

Note

Make sure that on a screen containing Grid, the attribute “scroll” of <screen> element should equal NONE. By default it is scroll=”NONE”, so you need not specify the attribute scroll in screen element.

Background

Background of a GRID can be set by the attribute appearance_name. To set GRID with transparent background, make sure the appearance has alpha=”0”. To set a different background, make sure that the appearance has background_color and alpha greater than 0. You can set other properties such as border, radius also. Learn more about appearance

Child controls of GRID

A grid is essentially used to display information or images. The controls supported as child controls of a GRID control are:

  • TEXT
  • IMAGE

The appearance of child controls is based on the appearance_name attribute of that control.

Examples

  1. In this example, the grid displays images present in the local device in 4 columns. The images are stored on the local device and the list is stored in the table ‘images’. The width of the grid cells will vary if the width of the GRID control is given as a % of the screen and the width of the IMAGE control is given as a % of GRID control.
<control type="GRID" name="grid_view" x="4" y="5" width="90" height="40" permission="READONLY"
     appearance_name="lightblue_bkgrnd_border" num_columns="4"
     horizontal_spacing="0" vertical_spacing="0" data_type="CURSOR"
     local_data_source="select image as _id, image as my_image, title from images">
     <control type="IMAGE" name="my_image" x="0" y="0" width="100" height="75"
        field_name="my_image" appearance_name="black" zorder="1" data_type="VARCHAR"/>
     <control type="TEXT" name="title" x="10" y="66" width="80" height="15"
        field_name="title" appearance_name="black" zorder="1"/>
</control>
  1. In this example, the grid displays images present in the local device with column width fixed. The column width is 100dp. The images are stored in the local device and their list is stored in the table ‘images’. The number of columns in grid will vary with the screen’s width.
<control type="GRID" name="grid_with_fixed_column_width" x="5" y="46" width="90" height="40" permission="READONLY"
     appearance_name="lightblue_bkgrnd_border" column_width="100.0dp"
     horizontal_spacing="0" vertical_spacing="0" data_type="CURSOR"
     local_data_source="select image as _id, image as my_image, title from images">
     <control type="IMAGE" name="my_image_with_fixed_column_width" x="0" y="0" width="100" height="75"
        field_name="my_image" appearance_name="black" zorder="1" data_type="VARCHAR"/>
     <control type="TEXT" x="10" y="66" width="80" height="15"
        field_name="title" appearance_name="black" zorder="1"/>
</control>

Note

These examples can be found in the tutorial TODO (name of the tutorial)