- 1 Quick introduction to widgets
Quick introduction to widgets
Widgets are building blocks of GL. ginstr custom widgets are explained in detail in this document. ginstr widgets have some internal functionality like taking a photo, calling a number. ginstr widgets are based on Android widgets, their behaviour is similar, for information about Android widgets refer to Android Documentation.
Widget XML structure
Each page (screen) must have root layout(widget) which behaves as main container of displayed(child) widgets such as TextView, Datepicker, ImageView, com.ginstr.widgets.GnEditText and others. Widget attributes will depend on design and business logic requirements of the ginstr app where following attributes must be defined for every widget:
- opening bracket “<” and widget name
- closing bracket “/>” or “</widgetName>”
, where pipe (|) translates as option to choose one of attribute values shownBelow is example XML code for root layout. Note that lines 2-4 are obligatory only for each root layout and do not require any changes. Line 5 is used as identifier for widget and in a case of root layout it is required and must be unique across the whole given XML file (screen).
1.<LinearLayout 2. xmlns:android="http://schemas.android.com/apk/res/android" 3. xmlns:tools="http://schemas.android.com/tools" 4. xmlns:gn="http://schemas.ginstr.com/ginstr" 5. android:id="@+id/start" 6. android:layout_width="match_parent" 7. android:layout_height="match_parent" > 8. <!-- displayed child widgets --> 9.</LinearLayout>
Line 8 is location that contains widgets which will form screen content. All widgets in single screen XML file are in parent-child relationship. For better overview of XML code it is desired that each child is indented to the right by tabulation or number of spaces in relation to parent, which is in most IDE-s 4 spaces. This will ensure easier future improvements. There are different types of widgets where one can only display some content (text, image), while others can also be used to input values by user. We will describe several widgets of each group.
Display only widgets
<TextView android:layout_width="match_parent" android:layout_height="wrap_content" android:textSize="25sp" android:text="@string/txtPage1Headline" />
Typical usage is showing text from string resource (strings.xml) on screen for purpose of page headline, subheadline and labeling other widgets. Attribute “textSize” should be defined. Attribute “text” has value @string/txtPage1Headline” which is reference to strings.xml containing textual value to be displayed as label. This value is stored in strings.xml as below: <string name=”txtPage1Headline”>Page 1</string> It is important to always use string references for label (TextView), because of existence of several strings.xml files, each for different language, which then makes easier internationalization of each app. On image below TextView is used for page headline „coffe machines maintenance“ and as label „identify coffee machine*“ for reading code widget.
Example of TextView usage in app
<ImageView android:layout_width="match_parent" android:layout_height="wrap_content" android:src="@drawable/background_i"/>
Widget is used to display graphic resource (image located in one of drawable directories) which is defined with: android:src=”@drawable/background_i”, where “background_i” is name of image (without file extension type .png, .jpeg, etc) which will be displayed in widget. Main purpose is to enrich UI for better user experience. Other purposes may be attaching click event, which executes specific action. More about click events and execution actions will be described later in manual. Example of imageView widget is displayed on screenshot from app below.
Example of TextView usage in app Note that imageView is used for icon and bottom image in red borders.
Input value widgets
Following widgets are expecting from user to input some value, textual, numeric and other. Main purpose is to collect from user data, which can also be graphical for instance taking picture, digital signature or scanning NFC (barcode). Some widgets can behave differently based on defined attributes. For instance most versatile widget is com.ginstr.widgets.GnEditText which can used as input box for collecting alphanumeric values, but also be configured for scanning NFC tag or barcode and more.
Input textual value (input box)
<com.ginstr.widgets.GnEditText android:id="@+id/firstName" android:layout_width="match_parent" android:layout_height="wrap_content" android:background="@drawable/entering_field_transparent_2.9" android:textSize="20sp" gn:s_sourceType="input" gn:s_hint="@string/txtFirstNameHint"/>
Input boxes using com.ginstr.widgets.GnEditTextImage above represents how input boxes look in application with attached background and hint text inside. Note that labels are above each of input box. nput box when is used to collect alphanumeric data from user, which is entered via keyboard on device. Representation can be enriched with displaying hint text inside of input box when nothing is entered using attribute gn:s_hint=”@string=txtFirstNameHint”. Hint text value is located in strings.xml, same as for TextView label described earlier. Further design enrichment includes showing input box on graphic background using attribute android:background=”@drawable_entering_field_transparent_2.9”. Image for input background is located in of drawable directories. Widget has also defined android:id needed for referencing it in further app execution which may include saving data from this widget to database, saving data to variable, comparing widget data to another widget and other decision making business logic. With attribute gn:s_sourceType=”input”, widget is configured to allow input of alphanumeric values. With different types of configuration of this attribute, widget can be used for different types of data entry such as numeric, current time, serial number of device and other. It is important to note that this attribute must always be defined for this widget.
Read NFC tag
<com.ginstr.widgets.GnEditText android:id="@+id/readNfcTag" android:layout_width="match_parent" android:layout_height="wrap_content" android:background="@drawable/entering_field_transparent_2.9" android:textSize="20sp" gn:s_hint="@string/txtReadNfcTagHint" gn:act_validate="[name:RequiredValidator],[message=@string/txtReadNfcTag Required]" android:textColor="#000000" android:textColorHint="#BABABA" gn:s_sourceType="nfc" gn:act_setOnNfc="[gn:act_trigger]|[@+id/actionSetWidget,gn:act_set]" />
Widget XML code above is same widget type as plain “input box” but configured to read NFC tags. This is achieved with defining gn:s_sourceType=”nfc”. When NFC tag is read with device, read code will be displayed inside input box and action gn:act_setOnNfc will execute all actions defined within the attribute value. Usually this would point to some action set which holds commands for reading data from database with NFC tag as key and decision making based on data existence. Validation attribute gn:act_validate is present here, behaving as attribute to be checked when validation check is triggered. This attribute will be checked with action [gn:act_validateScreen]| in app execution. In given example validator requires that value must be present in widget @+id/readNfcTag, if not toast message will be displayed to user, where text value shown to user is referenced with @string/txtReadNfcTagRequired. Validation attributes are used to ensure that data must be present in widget or having defined minimal, maximal length or other configured format of the content. With validators, user is forced to input data, which app business logic requires. More about validators is explained in next chapters of manual. Regarding naming convention of string resources in strings.xml, it is good to notice that labels for widget are related for better description of page or specific input box, for example label “txtFirstName”. Hint text for input will then be “txtFirstNameHint” and if validator is used “txtFirstNameRequired” will be string name resource. This will later ensure logical structuring of string resources and keep uniqueness through all strings. It is not permited to use some string resource more than once. Names of widget id’s will be closely related to database column names and in best case they should be the same. Case scenarios for naming conventions will be closely examined on example apps provided later in manual. With some described types of widgets we see that some of them are only for display text or images while others can have multiple purposes like entering data, reading data from other sources, displaying data from database, etc. Same is valid for events and actions. Some event can be defined on widget, which then executes action (or several actions, called action set). For example event “gn:act_beforeLoad” attached to widget will execute action right before page is displayed on device, for instance loading some data fom database. Other events could be executed when user clicks on widget “gn:act_setClick”,for loading next page (screen). This is usually case for buttons or some other user interaction.
Uploading ginstr apps to ginstr web
To upload ginstr app to ginstr web, we make zip file of root folder which contains all of our ginstr app folders (usually called app zip) and upload it to server https://22.214.171.124/SSOServer in application management section. If you don’t have persmission for ginstr app zip upload, request from ginstr apps developer for uploading this app zip. After upload, table with columns will be created on backend side. This can be examined opening ginstr web UI and searching app name and opening table in new portlet.
app table in ginstr web UI
If app is on the list but does not have any tables, they should be enabled for current ginstr account. In ginstr UI lobby hover with mouse over account name will open menu. Selecting my account opens page for managing app for current ginstr account.
entering to ginstr account Click on “my account” and then on “hide/show content”. This will open list with apps. Click on app name openes in right tab table list with CRUD rights for each table. Clicking on table names will create tables if they are not yet created. For development purpose enable full CRUD rights for each table.
managing CRUD rights of ginstr apps tables
After this step is done ginstr app tables should be visible in portlet of ginstr web, if this is not the case please contact ginstr app developer.
Updating ginstr apps that are already present on ginstr web
Updating ginstr app procedure is identical to uploading new ginstr app. However there are some restrictions to modifications of ginstr app table structures to existing apps. If some of restrictions is blocking to update new ginstr app it's required to uninstall the app from ginstr web and add it as new app. Ask ginstr app developer or admin to do that. Restrictions in modifications of ginstr app new uploaded ginstr app zip are:
- company name and appId (zip file name) must be identical to original upload
- table names should be unique in ginstr app zip
- changing od datatype of existing column is not allowed
- table must have columns
- columns can't be deleted if they have refrences
- it's not possible to set "unique" or "required" setting on columns of table that already has entries
- new "required" column can not be added to table if "default value" is not set on in the column settings
- new "unique" column with "default value" setting can not be added to table which has more than one row of existing data