From wiki.ginstr.com
Revision as of 12:04, 28 March 2017 by Dinko (talk | contribs) (Alternative layout)
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{n} 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{n} 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{n} Defines column identifiers

If the data is loading from database 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.

Can be

  • hardcoded, i.e. resident_nfcTagUid,resident_firstName
  • @string
gn:data_columns_type Defines cell type for each row which will display data

Can be

  • text
  • pictures
  • pointer - must be used in combination with additional pointer attributes. More about attributes here
  • dateTime
  • phoneNumber
gn:data_filters{n} Defines filter parameter to sort data

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{n} Defines column by which data will be sorted

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.

Can be

  • true
  • false
gn:lstExpandToFitChildren Stretches GnListView to load all children without scroll

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.

Can be

  • true
  • false

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" />

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

Filters

Filter Description
[VALUE]
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]
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]
[KEYWORD] filter compares values from list with special values that cannot be obtained by other means.
[#KEYWORD]|[COMPARATOR]|[COLUMNID]
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.

pointer additional XML attributes

Attribute Description
gn:data_source_request id of query which will be used to get pointed value
Can be
  • hardcoded
gn:data_source_table name of table which will get queried
Can be
  • hardcoded
gn:data_source_field column of referenced table which we would like to display supported referencing columns of data type text
Can be
  • hardcoded
gn:data_source_keys
optional

query keys in case referenced table values need to be reduced. This optimises memory on large table loads.

Can be
  • hardcoded

Alternative layout

Special widget which has multiple XML files defining multiple parts of this composite widget:

widget_en_listview_row_container.xml

Widget Name Description
TextView @+id/etEmail this text field represents emails stored in the widget
Button @+id/etEmailManage this button opens dialog screen to manage email entries


widget_en_listview_row_container.xml
defines how listview container appearance will look like
widget_en_listview_header_container.xml
defines how header container appearance will look like
widget_en_listview_column_string.xml
defines how column cell of type string will look like
Internal widgets to keep id and type unchanged:
id Type
@+id/tvDisplayView TextView
widget_en_listview.xml
defines the appearance of the listview container
Internal widgets to keep id and type unchanged:
id Type
@+id/lstHeader FrameLayout
@+id/lstListView ListView

GnListView has a possibility to use custom defined layouts and rows:

gn:custom_xml="custom_listview.xml"
customised XML listview layout
gn:custom_header_xml
customised XML listview header layout
gn:custom_row_xml
customised XML row layout
gn:complex_cell_layout
to create complex list layouts based on one cell in row


If the default look and feel needs to be changed, create or copy identical files from $defaultApp to current app "control" folder.
To provide alternative layout, the files mentioned above can be set into control folder of the current application. Files must be named as shown above and widgets with Id’s have to stay of same type and keep same id.

widget_en_email.xml

Widget Name Description
TextView @+id/etEmail this text field represents emails stored in the widget
Button @+id/etEmailManage this button opens dialog screen to manage email entries

dialog_en_email.xml

Widget Name Description
GnEditText @+id/etEmailDialogName this input field is used to define email entry name attribute
GnEditText @+id/etEmailDialogAddress this input field is used to define email entry email attribute
ListView @+id/lstEmailDialogAddresses displays currently stored email entries in widget
Button @+id/btnEmailDialogAdd this button adds data that is set into GnEditTexts into widget and refreshes the listview
Button @+id/btnEmailDialogEdit this button, after clicking on list item and modifying entry data, will replace stored entry data with newly entered data
Button @+id/btnEmailDialogRemove after clicking on list item, clicking this button will remove the entry from the list
Button @+id/btnEmailDialogClose this button closes dialog and refreshes widget on screen with data

dialog_en_email_row.xml

Widget Name Description
LinearLayout @+id/etEmailRow this container represents a single list row
TextView @+id/etEmailName this text widget will display email entry name attribute
TextView @+id/etEmailRowAddress this text widget will display email entry email attribute