From wiki.ginstr.com
Revision as of 16:52, 21 March 2017 by Dinko (talk | contribs) (XML Attributes Description)
Jump to: navigation, search

GnListView

Widget XML tag
<com.ginstr.widgets.GnListView>
Description
GnListView is used to show data in a table appearance, with header on the top and data in rows with cells below.

XML Attributes Description

Attribute Description
gn:data_columns_width{n} Defines the width of each column from left to right that appears in listview
Can be
  • hardcoded, i.e. 50,50,50
gn:data_columns_name Defines the names from left to right that will appear in header columns
Can be
  • hardcoded, i.e. resident_nfcTagUid,resident_firstName
  • @string
gn:data_columns_settings Defines the settings for each column from left to right that is displayed in listview.
If there is a single column to be shown in listview there is no separator between settings for columns.
If there are 2 or more columns whose settings should be configured “pipe” (|) is used to separate them
i.e. “settingsColumn1|settingsColumn2|…”.
Can be
  • format – converting long to human readable date and time, correct formats here
gn:data_columns_id Defines column identifiers
gn:data_columns_type Defines cell type for each row which will display data
gn:data_filters Defines filter parameter to sort data
gn:data_columns_sort Defines column by which data will be sorted in GnListView
gn:lstRefreshNoFilter Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
gn:lstExpandToFitChildren Stretches GnListView to load all children without scroll

Example

<com.ginstr.widgets.GnListView
  android:id="@+id/lstResidents"
  android:layout_width="match_parent"
  android:layout_height="match_parent"
  android:layout_gravity="center_horizontal"
  android:background="#e1e1e1"
  gn:data_columns_name="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
  gn:data_columns_id="resident_nfcTagUid,resident_firstName,resident_lastName,resident_roomNo,resident_buildingCode"
  gn:data_columns_type="text,text,text,text,text"
  gn:serverTableGenerator="ignore"
  gn:lstRefreshNoFilter="true"
  gn:s_listSelector="#00000000"
  gn:custom_xml="customList_listview.xml"
  gn:custom_header_xml="residentsList_header.xml"
  gn:custom_row_xml="residentsList_row.xml"
  gn:complex_cell_layout="true"/>




GnListView Filtering

Once data is loaded from the database it can be filtered by a filter mechanism. You can also filter the data loaded into the GnListView by using the following filter types:

  • VALUE
  • WIDGET
  • KEYWORD

Filters can also be chained by chain words:

  • AND
  • OR

If the filters are chained then each of filter statements must be true in order to show some record that is in GnListView data.

i.e.[@+id/widgetOne]|[=]|[columnOne],[AND]|[#today]|[=]|[timestamp],[AND]|[dog]|[=]|[columnAnimalType]

The upper statement filters the GnListView in the following way:

IF the widget that has id “@+id/widgetOne” has a value equal to the value in columnOne in listview rows AND if timestamp value in listview rows is within today AND if columnAnimalType value in listview rows is equal to “dog”, then the row from listview rows will be displayed in GnListView.

Based the example above, the filter chaining definition is:

[CHAIN WORD]|[FILTER],[CHAIN WORD]|[FILTER1]…

General filter [FILTER] definition is:

[VALUE]|[COMPARATOR]|[COLUMNID]

Filters behave differently depending on the content of the [VALUE] field.

[VALUE] field special characters

Special Character Description
:: Defines range in VALUE (turns filter into RANGE filter) (not yet implemented)
* Equivalent to like
# Keyword identifier (turns filter into KEYWORD filter)
@+id/ Widget id
\ Escape character

In order to use special characters as standard text you need to escape them as follows: \::, \*, \#, \@+id/ or \\

Comparators

Comparators define the relation between the two values that are being compared.

The following comparators can be used to compare:

Comparator Symbol Description Value Types Allowed
= Equals to values STRING, NUMBER
c= Case sensitive equals to values STRING, NUMBER
> Greater than value NUMBER

[VALUE] filter

Compares a value against value loaded into GnListView data rows.
The definition of value filter is as follows :
[VALUE]|[COMPARATOR]|[COLUMNID]
i.e. [two]|[=]|[columnOne]
The following filter will compare data row value if is equal to two, filter will return true and data row loaded into GnListView.

[WIDGET] filter

If [VALUE] field contains special character @+id/ filter will behave as Widget filter.
[WIDGET] filter compares listview datarow value with value of a certain widget.
[@+id/WIDGET_ID]|[COMPARATOR]|[COLUMNID]
i.e. [@+id/widgetOne]|[=]|[columnA]
This filter checks if a widget with id @+id/widgetOne has value equal to columnA of listview datarow. If true row will be shown.

[KEYWORD] filter

[KEYWORD] filter compares values from list with special values that cannot be obtained by other means.
[#KEYWORD]|[COMPARATOR]|[COLUMNID]
#today
Keyword #today checks if value from listview is within today's date. If it is then it returns true and row is displayed.
i.e. [#today]|[=]|[timestamp] is timestamp field within today's date
When using the timestamp the dateTime datatype must be used.

gn:data_columns_width

Defines the width of each column from left to right that appears in listview

(String) values = 0100 (percent) OR 100DP, 115DP

When percentage values are used, the sum of all values must be 100

i.e. 30,70, 20,20,20,20,20

When DP values (density pixels) are used, the sum of values is irrelevant.

gn:data_columns_name

Defines the names from left to right that will appear in header columns

(String) values = column1, column2 ... lastcolumn

gn:data_columns_settings

Defines the settings for each column from left to right that is displayed in listview.

If there is a single column to be shown in listview there is no separator between settings for columns.

If there are 2 or more columns whose settings should be configured “pipe” (|) is used to separate them

i.e. “settingsColumn1|settingsColumn2|…”.

Settings:

Dt dateTime
format – converting long to human readable date and time, correct formats here

gn:data_columns_id

Defines column identifiers, which are directly related with dbRequest fields.

If the data is loading from a dbRequest that has columns i.e. name, surname, to read that data to listview your columns should have same id’s surname, name. Note that the order here is not important.

gn:data_columns_type

Defines cell type for each row which will display data

(String) values = Dt text, Dt pictures, Dt pointer, Dt dateTime, Dt phoneNumber

Value Description
Dt text Shows text in cell
Dt pictures Shows pictures in cell
Dt pointer When pointer is used, additional widget attributes must be set
Dt dateTime shows date as long, if gn:data_columns_settings set, it is possible to show date as formatted text (see here for more information).
Dt phoneNumber Shows all phone numbers stored in column of type phoneNumber

Dt pointer additional widget attributes

gn:data_source_request=”query”
id of query which will be used to get pointed value
gn:data_source_table=”table”
name of table which will get queried
gn:data_source_field
column of referenced table which we would like to display supported referencing columns of data type Dt text
gn:data_source_keys (optional)
query keys in case referenced table values need to be reduced. This optimises memory on large table loads. Permitted query keys are listed here.

gn:data_filters

Once data is loaded into GnListView, it can be filtered by defining filter parameter.

Filters are separated by , (comma symbol) and they have special syntax. More about filters here.

gn:data_columns_sort

Defines column by which data will be sorted in GnListView

Currently, sorting only accepts ascending sort by columnID defined by value of this attribute. For example if dbRequest has columns: name,surname,timestamp, and name is set as a value for this attribute then all rows will be sorted ascending by name.

gn:lstRefreshNoFilter

Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)

This attribute is not relevant to designer and if developing a standard ginstr app then it can be omitted.

(Boolean) value = true

gn:lstExpandToFitChildren

Can be used only if listView is: com.ginstr.widgets.internal.ExpandableHeightListView in control/widget_en_listview.xml, if set to true, GnListView will stretch to load all children without scroll

(Boolean) value = true