From wiki.ginstr.com
Jump to: navigation, search
m
m
Line 47: Line 47:
 
|}
 
|}
  
==GnListView Filtering==
+
==<code>GnListView</code> 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 <code>[[GnListView]]</code> by using the following filter types:
 
Once data is loaded from the database it can be filtered by a filter mechanism. You can also filter the data loaded into the <code>[[GnListView]]</code> by using the following filter types:
 
*<code>VALUE</code>
 
*<code>VALUE</code>
Line 140: Line 140:
 
;<code>[#KEYWORD]|[COMPARATOR]|[COLUMNID]</code>
 
;<code>[#KEYWORD]|[COMPARATOR]|[COLUMNID]</code>
  
=====#today=====
+
=====<code>#today</code>=====
 
Keyword <code>#today</code> checks if value from listview is within today's date. If it is then it returns <code>true</code> and row is displayed.
 
Keyword <code>#today</code> checks if value from listview is within today's date. If it is then it returns <code>true</code> and row is displayed.
  
Line 146: Line 146:
 
When using the timestamp the <code>date_time</code> datatype has to be used.
 
When using the timestamp the <code>date_time</code> datatype has to be used.
  
==gn:data_columns_width==
+
==<code>gn:data_columns_width</code>==
 
Defines the width of each column from left to right that appears in listview
 
Defines the width of each column from left to right that appears in listview
  
Line 156: Line 156:
 
When DP values (density pixels) are used, the sum of values is irrelevant.
 
When DP values (density pixels) are used, the sum of values is irrelevant.
  
==gn:data_columns_name==
+
==<code>gn:data_columns_name</code>==
 
Defines the names from left to right that will appear in header columns
 
Defines the names from left to right that will appear in header columns
  
 
''(String)'' values = <code>column1</code>, <code>column2</code> ... <code>lastcolumn</code>
 
''(String)'' values = <code>column1</code>, <code>column2</code> ... <code>lastcolumn</code>
  
==gn:data_columns_settings==
+
==<code>gn:data_columns_settings</code>==
 
Defines the settings for each column from left to right that is displayed in listview.
 
Defines the settings for each column from left to right that is displayed in listview.
  
Line 172: Line 172:
 
;<code>Dt “dateTime”</code>:<code>format</code> – converting long to human readable date and time, correct formats [http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html here]
 
;<code>Dt “dateTime”</code>:<code>format</code> – converting long to human readable date and time, correct formats [http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html here]
  
==gn:data_columns_id==
+
==<code>gn:data_columns_id</code>==
 
Defines column identifiers, which are directly related with <code>dbRequest</code> fields.
 
Defines column identifiers, which are directly related with <code>dbRequest</code> fields.
  
 
If the data is loading from a <code>dbRequest</code> that has columns i.e. <code>name, surname</code>, to read that data to listview your columns should have same id’s <code>surname, name</code>. Note that the order here is not important.
 
If the data is loading from a <code>dbRequest</code> that has columns i.e. <code>name, surname</code>, to read that data to listview your columns should have same id’s <code>surname, name</code>. Note that the order here is not important.
  
==gn:data_columns_type==
+
==<code>gn:data_columns_type</code>==
 
Defines cell type for each row which will display data
 
Defines cell type for each row which will display data
  
Line 203: Line 203:
 
|}
 
|}
  
===Dt "pointer" additional widget attributes===
+
===<code>Dt "pointer"</code> additional widget attributes===
  
 
;<code>gn:data_source_request=”query”</code>: id of query which will be used to get pointed value
 
;<code>gn:data_source_request=”query”</code>: id of query which will be used to get pointed value
Line 210: Line 210:
 
;<code>gn:data_source_keys</code> (optional): query keys in case referenced table values need to be reduced. This optimises memory on large table loads. Permitted query keys are listed [[gn:act_rawQueryToWidget#Query_keys_from_target|here]].
 
;<code>gn:data_source_keys</code> (optional): query keys in case referenced table values need to be reduced. This optimises memory on large table loads. Permitted query keys are listed [[gn:act_rawQueryToWidget#Query_keys_from_target|here]].
  
==gn:data_filters==
+
==<code>gn:data_filters</code>==
 
Once data is loaded into <code>[[GnListView]]</code>, it can be filtered by defining filter parameter.
 
Once data is loaded into <code>[[GnListView]]</code>, it can be filtered by defining filter parameter.
  
 
Filters are separated by <code>,</code> (comma symbol) and they have special syntax. More about filters [[#GnListView_Filtering|here]].  
 
Filters are separated by <code>,</code> (comma symbol) and they have special syntax. More about filters [[#GnListView_Filtering|here]].  
  
==gn:data_columns_sort==
+
==<code>gn:data_columns_sort</code>==
 
Defines column by which data will be sorted in <code>[[GnListView]]</code>
 
Defines column by which data will be sorted in <code>[[GnListView]]</code>
  
 
Currently, sorting only accepts ascending sort by <code>columnID</code> defined by value of this attribute. For example if <code>dbRequest</code> has columns: <code>name,surname,timestamp</code>, and <code>name</code> is set as a value for this attribute then all rows will be sorted ascending by name.
 
Currently, sorting only accepts ascending sort by <code>columnID</code> defined by value of this attribute. For example if <code>dbRequest</code> has columns: <code>name,surname,timestamp</code>, and <code>name</code> is set as a value for this attribute then all rows will be sorted ascending by name.
  
==gn:lstRefreshNoFilter==
+
==<code>gn:lstRefreshNoFilter</code>==
 
Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
 
Defines that on refresh data will not be filtered (used only in special cases when business logic implementation is used)
  
Line 227: Line 227:
 
''(Boolean)'' value = <code>true</code>
 
''(Boolean)'' value = <code>true</code>
  
==gn:lstExpandToFitChildren==
+
==<code>gn:lstExpandToFitChildren</code>==
 
Can be used only if listView is: <code>com.ginstr.widgets.internal.ExpandableHeightListView</code> in '''control/widget_en_listview.xml''', if set to <code>true</code>, <code>[[GnListView]]</code> will stretch to load all children without scroll
 
Can be used only if listView is: <code>com.ginstr.widgets.internal.ExpandableHeightListView</code> in '''control/widget_en_listview.xml''', if set to <code>true</code>, <code>[[GnListView]]</code> will stretch to load all children without scroll
  
 
''(Boolean)'' value = <code>true</code>
 
''(Boolean)'' value = <code>true</code>

Revision as of 10:55, 4 July 2016

GnListView

GnListView
Inherited classes
View
Android class type
LinearLayout
Child elements
FrameLayout, ListView
Widget XML tag
<com.ginstr.widgets.GnListView>


GnListView is used to show data in a table appearance, with header on the top and data in rows with cells below.

Data for listview can be queried via regular actions i.e. gn:act_query and the fields it returns depend on queries.xml.

XML Attributes Description

Attribute Description
gn:data_columns_width Defines the width of each column from left to right that appears in listview
gn:data_columns_name Defines the names from left to right that will appear in header columns
gn:data_columns_settings Defines the settings for each column from left to right that is displayed in listview
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

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 has to 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 on upper example, the filter chaining definition is

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

General filter [FILTER] definition is

[VALUE]|[COMPARATOR]|[COLUMNID]

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

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 date_time datatype has to 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 "phoneNumbers"

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.
Dt "phoneNumbers" 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