From wiki.ginstr.com
Jump to: navigation, search
Line 4: Line 4:
 
Actions define what happens after an event has occurred. They are bound to certain events, clicks, swipes, long clicks, after load, before load …
 
Actions define what happens after an event has occurred. They are bound to certain events, clicks, swipes, long clicks, after load, before load …
  
Combined together, actions and events form an interaction with the app on a global level. Some actions can be used by only one widget while some others by all widgets.
+
Combined together, actions and events form an interaction with the app on a global level. Some actions can be used by only one widget while some others by all [[widgets]].
  
 
In the [[Action Library]] all actions are described in detail.
 
In the [[Action Library]] all actions are described in detail.
  
Actions can be clearing data from widgets, saving data to database, switching to another screen, loading data to widget, etc…
+
Actions can be clearing data from [[widgets]], saving data to database, switching to another screen, loading data to widget, etc…
All actions that are set to widget are bound to an event. If an action is not bound to an event it can’t be used. An example of an action is to add a picture in the following image 8 or in an action set or conditional action. All actions begin with prefix: <code>“gn:act_”</code>.
+
 
+
All actions that are set to widget are bound to an event. If an action is not bound to an event it can’t be used. An example of an action is to add a picture in the following image 1 or in an action set or conditional action.
 
[[File:example_of_bound_action_to_widget.png|thumb|400px|center|1. example of bound action to widget]]
 
[[File:example_of_bound_action_to_widget.png|thumb|400px|center|1. example of bound action to widget]]
 +
 +
All actions begin with prefix: <code>“gn:act_”</code>.
  
 
===Action formats===
 
===Action formats===
 
There are two formats how to define actions:
 
There are two formats how to define actions:
::;1. As widget attribute : action signature is as defined in widget library.  
+
::;1. As widget attribute : action signature is as defined in [[Widget Library]].  
 
::i.e. <code>gn:act_actionName=”actionValue”</code>
 
::i.e. <code>gn:act_actionName=”actionValue”</code>
 
::;2. As action within another action : action that is nested within another action as a value of its value
 
::;2. As action within another action : action that is nested within another action as a value of its value
Line 21: Line 23:
  
 
===Action types===
 
===Action types===
::;1. Event actions : are always bound to an event. In the widget library there are defined events. An action is executed when an event is triggered. Event actions can also be used in conditional actions and action sets. Picture 8 displays example of event action.
+
::;1. Event actions : are always bound to an event. In the [[Widget Library]] there are defined events. An action is executed when an event is triggered. Event actions can also be used in conditional actions and action sets. Picture 1 displays example of event action.
 
::;2. No event actions : can only be used within an action set or another conditional action that accepts actions. By trying to use them like in picture 2 (below). Nothing will happen since they are not bound to any event. Those actions do not have an event description in [[Widget Library]].
 
::;2. No event actions : can only be used within an action set or another conditional action that accepts actions. By trying to use them like in picture 2 (below). Nothing will happen since they are not bound to any event. Those actions do not have an event description in [[Widget Library]].
 
   
 
   
Line 32: Line 34:
 
==Actions usage best practices==
 
==Actions usage best practices==
 
In order to more efficiently use actions following best practices are suggested to all developers:
 
In order to more efficiently use actions following best practices are suggested to all developers:
#group business logic in single location in xml file. Use helper views to store business logic code or separate it by functionality and use triggers to call it. The reason for this is if you have reusable components of your business logic it will be easy to call them later via trigger somewhere else, also it will be more easy to understand the logic on one place than scattered around whole document.  
+
#group business logic in single location in XML file. Use helper views to store business logic code or separate it by functionality and use triggers to call it. The reason for this is if you have reusable components of your business logic it will be easy to call them later via trigger somewhere else, also it will be more easy to understand the logic on one place than scattered around whole document.  
  
:::::i.e.
+
:::i.e.
 
[[File:actions_usage_best_practice.png|thumb|800px|center|4. example of grouping business logic]]
 
[[File:actions_usage_best_practice.png|thumb|800px|center|4. example of grouping business logic]]
:::::In the picture above <code>FrameLayout</code> with <code>“@+id/invalidateRecord”</code> is used to hold a “block” of business logic which is then called when necessary to invalidate record, by action <code>“gn:act_trigger]|[@+invalidateRecord,gn:act_set]</code>
+
:::In the picture above <code>FrameLayout</code> with <code>“@+id/invalidateRecord”</code> is used to hold a “block” of business logic which is then called when necessary to invalidate record, by action <code>“gn:act_trigger]|[@+invalidateRecord,gn:act_set]</code>
  
 
==Pointer Actions==
 
==Pointer Actions==
 
Pointer value in ginstr launcher is a value that uniquely represents a row which holds some other row in database.  Any value in that row of data except value which represents id of the row can be called pointer value.
 
Pointer value in ginstr launcher is a value that uniquely represents a row which holds some other row in database.  Any value in that row of data except value which represents id of the row can be called pointer value.
  
::i.e. we have a in table “one” columns “a”,”b”,”c”
+
::i.e. we have columns <code>“a”</code>,<code>”b”</code>,<code>”c”</code> in table <code>“one”</code>
::We have row in table “two” which contains column “xy” which holds some row “id”.
+
::We have a row in table <code>“two”</code> which contains column <code>“xy”</code> which holds some row <code>“id”</code>.
::If we know in column data “source table” and “source column” we will get value of the pointer value in our case if “source table“= “one” and “source_column”=”b”, we will get value of column “b” read based on pointer id in table “two”.
+
::If we know in column data <code>“source table”</code> and <code>“source column”</code> we will get value of the pointer value. In our case if <code>“source table“=“one”</code> and <code>“source_column”=”b”</code>, we will get value of column <code>“b”</code> read based on pointer id in table <code>“two”</code>.
  
If pointer id or value needs to be stored into a widget following attributes are necessary on target:
+
If pointer id or value needs to be stored into a widget, the following attributes are necessary on target:
 
*<code>GnEditText</code>
 
*<code>GnEditText</code>
 
**<code>gn:data_type="pointer"</code> – if we just want to load pointed row id
 
**<code>gn:data_type="pointer"</code> – if we just want to load pointed row id
 
**<code>gn:getPointerValue=”true”</code> – if we want to load value from pointed row in that case some additional attributes are necessary
 
**<code>gn:getPointerValue=”true”</code> – if we want to load value from pointed row in that case some additional attributes are necessary
 
***<code>gn:data_source_request="queryName"</code> – has to have name of query which prepares data for querying and key in that query has to be <code>“_id”</code>
 
***<code>gn:data_source_request="queryName"</code> – has to have name of query which prepares data for querying and key in that query has to be <code>“_id”</code>
::::i.e. '''queries.xml''' “query” example:
+
::::i.e. [[queries.xml]] “query” example:
 
::::[[File:GnEditText_query_example.png|left|frame]]
 
::::[[File:GnEditText_query_example.png|left|frame]]
  
Line 62: Line 64:
 
Actions that work with pointers are:
 
Actions that work with pointers are:
 
===[[gn:act_rawQueryToWidget(s)]]===
 
===[[gn:act_rawQueryToWidget(s)]]===
When using query from database it is possible to store data from pointer columns to widgets
+
When using query from database it is possible to store data from pointer columns to [[widgets]]
 
===[[gn:act_loadPointer]]===
 
===[[gn:act_loadPointer]]===
 
Load pointer is used after pointer <code>“id”</code> (not pointer value) is loaded by <code>“rawQueryToWidget(s)”</code> to a widget [[GnEditText]] and then properties of the [[GnEditText]] are used to load pointer <code>“value”</code> into the widget and replace <code>“id”</code>.
 
Load pointer is used after pointer <code>“id”</code> (not pointer value) is loaded by <code>“rawQueryToWidget(s)”</code> to a widget [[GnEditText]] and then properties of the [[GnEditText]] are used to load pointer <code>“value”</code> into the widget and replace <code>“id”</code>.

Revision as of 14:13, 23 June 2016

Actions

Actions define what happens after an event has occurred. They are bound to certain events, clicks, swipes, long clicks, after load, before load …

Combined together, actions and events form an interaction with the app on a global level. Some actions can be used by only one widget while some others by all widgets.

In the Action Library all actions are described in detail.

Actions can be clearing data from widgets, saving data to database, switching to another screen, loading data to widget, etc…

All actions that are set to widget are bound to an event. If an action is not bound to an event it can’t be used. An example of an action is to add a picture in the following image 1 or in an action set or conditional action.

File:example of bound action to widget.png
1. example of bound action to widget

All actions begin with prefix: “gn:act_”.

Action formats

There are two formats how to define actions:

1. As widget attribute 
action signature is as defined in Widget Library.
i.e. gn:act_actionName=”actionValue”
2. As action within another action 
action that is nested within another action as a value of its value
Action that is defined as gn:act_actionName=”actionValue” for a widget has to be modified to use within another action like: gn:act_parentAction=”[gn:act_actionName]|[actionValue]”

Action types

1. Event actions 
are always bound to an event. In the Widget Library there are defined events. An action is executed when an event is triggered. Event actions can also be used in conditional actions and action sets. Picture 1 displays example of event action.
2. No event actions 
can only be used within an action set or another conditional action that accepts actions. By trying to use them like in picture 2 (below). Nothing will happen since they are not bound to any event. Those actions do not have an event description in Widget Library.
File:example of no event action used within an event action.png
2. example of no event action used within an event action
3. Conditional actions 
special case action that executes actions. It’s used as no event action and can be used within other actions or action sets. Depending on an outcome of a certain action it executes other actions. Conditional actions work like an if statement. More about conditional actions in Action Library.
File:example of conditional action within action set.png
3. example of conditional action within action set

Actions usage best practices

In order to more efficiently use actions following best practices are suggested to all developers:

  1. group business logic in single location in XML file. Use helper views to store business logic code or separate it by functionality and use triggers to call it. The reason for this is if you have reusable components of your business logic it will be easy to call them later via trigger somewhere else, also it will be more easy to understand the logic on one place than scattered around whole document.
i.e.
File:actions usage best practice.png
4. example of grouping business logic
In the picture above FrameLayout with “@+id/invalidateRecord” is used to hold a “block” of business logic which is then called when necessary to invalidate record, by action “gn:act_trigger]|[@+invalidateRecord,gn:act_set]

Pointer Actions

Pointer value in ginstr launcher is a value that uniquely represents a row which holds some other row in database. Any value in that row of data except value which represents id of the row can be called pointer value.

i.e. we have columns “a”,”b”,”c” in table “one”
We have a row in table “two” which contains column “xy” which holds some row “id”.
If we know in column data “source table” and “source column” we will get value of the pointer value. In our case if “source table“=“one” and “source_column”=”b”, we will get value of column “b” read based on pointer id in table “two”.

If pointer id or value needs to be stored into a widget, the following attributes are necessary on target:

  • GnEditText
    • gn:data_type="pointer" – if we just want to load pointed row id
    • gn:getPointerValue=”true” – if we want to load value from pointed row in that case some additional attributes are necessary
      • gn:data_source_request="queryName" – has to have name of query which prepares data for querying and key in that query has to be “_id”
i.e. queries.xml “query” example:
GnEditText query example.png
      • gn:data_source_table="pointedValueTableName" - name of table which holds pointed row
      • gn:data_source_field="pointedValueColumnName" - column which we want to get data from in pointed row , it is necessary that column is of Dt “text” , text datatype
  • GnDropDown
    • gn:data_source_field=”pointedValueColumnName” (only necessary when dropdown is used to write or update data to database, not when data is set to dropdown by rawQueryToWidget(s)
    • gn:s_sourceType="database"


Actions that work with pointers are:

gn:act_rawQueryToWidget(s)

When using query from database it is possible to store data from pointer columns to widgets

gn:act_loadPointer

Load pointer is used after pointer “id” (not pointer value) is loaded by “rawQueryToWidget(s)” to a widget GnEditText and then properties of the GnEditText are used to load pointer “value” into the widget and replace “id”.

Further Reading