From wiki.ginstr.com
(Redirected from Category:.ginstr app)
Jump to: navigation, search

ginstr logo main.png app structure

Minimum requirement for app folders and files of a ginstr app

For each ginstr app, the following folders must be present:

control 
contains XML files for further customisation of widgets, for example GnEditText, GnListView and more.
database 
Contains the following XML files:
configuration.xml 
table schemes (not yet implemented)
queries.xml 
prepared query schemes with tables, columns and keys
variables.xml 
variable definitions used in app
drawable-$ 
$ stands for hdpi, xhdpi, xxhdpi and xxxhdpi containing same graphic resources but in different sizes. To ensure the best user interface possible, graphics are pre-made for several groups of screen densities, where usually bigger screen has bigger density and folder with largest graphics is used. The number of images in each graphical folder must be the same and file names should be uniform across folders.
layout 
activity.xml and start.xml are required for app to display login screen and perform authentication. Other XML files present in folder will then build other app pages (screens). Note that there may exist other XML files which are not used in app execution, but have specific purpose. This will be explained in app example.
settings 
contains changelog.xml (documenting app changes by developer), common.xml (documenting app version), graphic.xml (documenting which graphic resources app is using)
src
/web
contains webMvc.js file with logic definition for the web UI.
/client
values 
contains strings.xml and arrays.xml. This folder is in relationship with values-en, values-es and values-eg which have string resources important for app. Depending on language used in app, different folders may be used to display text values of referenced strings.

Location of ginstr apps on device

Screenshot 1. ginstr apps files on computer (left) and Android device (right)

Screenshot 1 (right) shows the location of ginstr launcher and ginstr app files on developing computer and Android device.

Each ginstr app has root folder, in our example this is airConditionerMaintenance.

When ginstr launcher is installed on device, it creates folder com.ginstr with 2 subfolders:

  • $configSets
  • $defaultApp

To add new ginstr app to ginstr launcher on device, app files are copied with app root folder as shown on Screenshot 1 to com.ginstr folder. Path to com.ginstr may not be same on all devices. For example, Screenshot 1 shows the path for Samsung S6 with Android 5.1.

After ginstr apps are transferred to device, starting ginstr launcher and pressing “create icons on the launch screen” creates shortcuts for each ginstr app currently present on device. ginstr app can then be started via its own shortcut. It is good practice to work on XML files on computer (local) before transferring to device in the same location to ensure a local copy is saved in the event of file transfer issues.

On Screenshot 2 (below), the red arrow is pointing from shortcut created on device on the left side of the image, and started ginstr app on the right side. Starting ginstr app login screen is displayed, requiring credentials to authenticate with entered username and password. Username is in email format and user should login with same credentials as used for ginstr web UI.

Transferring ginstr app files can be achieved with a folder explorer (e.g. Windows Explorer). When device is connected to computer with USB, navigate to path com.ginstr and paste ginstr app files within. File manager apps could be used, for instance Total Commander. Another way could be wireless transfer data from computer to device, provided the device is connected to same local WiFi network as computer. Using Android apps such as FTPService, device behaves like a server and on computer FTP manager (for instance FileZilla) connects to device as on any other FTP server. For additional information consult product manuals for FTPService and FileZilla.

Screenshot 2. Login screen of defaultApp

Resources and ginstr app file structure in detail

Resources can be divided into two main categories:

  1. XML files
    a. Layout XML files 
    build user interface, connect everything together (actions, resources, database fields)
    b. Resource XML files 
    contain translations and arrays with translations
    c. Database XML files 
    describe queries, variables and other data operation elements
  2. Other resources
    (images, fonts, sounds…)

All ginstr app files are stored in the folder (ginstr launcher base folder):

BASE_PATH = external storage /Android/data/com.ginstr/

Folders

App resource folders are:

  • assets
  • control
  • database
  • debug
  • drawable
  • layout
  • values

Assets (optional)

Contain non-text resources such as font files or other files used internally by ginstr launcher, those files are not language or configuration dependant.

Control

Contains XML layouts that represent internal controls such as GnLogin widget or GnResetPassword. If the designer wants to change the appearance of default widgets then alternative files can be provided with individual customised styling that will replace default widget styling.

More information about controls available here.

Database

Contains files that are relevant to building a database, creating database queries and tables, columns.

More information about databases available here.

Debug (optional)

Will automatically appear if not present when logging is enabled. Where ginstr launcher stores generated log dumps that will be used by developers to find problems and eliminate them.

Drawable

Stores all app images. Images in layouts are referenced by their file name within widgets @drawable/someImage. Images are then found using the name under which they are saved in the drawable folder for example, widget with drawable:

<ImageView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:src="@drawable/image" />

Density folder for drawable resources

Drawable resources are displayed differently on different devices. For example, an entry level device has a lower resolution than a flagship device. If the designer creates a resource for an entry level device it will appear fine on this device, but when the same app is loaded onto a flagship device, the resource will appear smaller or the resolution will create a pixelation of the image depending on the difference of density (density between those devices - dots per inch difference).

The default folder for ginstr launcher is “drawable-hdpi”. All drawable resources (images) should be in this folder. This folder is also called basefolder.

Density on Android devices is divided into categories:

  • ldpi
  • mdpi
  • tvdpi
  • hdpi
  • xhdpi
  • 400dpi
  • xxhdpi
  • xxxhdpi

When creating resources for different device densities, the above identifiers can be used. When a resource is loaded into the density folder, the device density that coordinates to the image should be checked. If no resource is found then basefolder is checked and the resource density is scaled to that of the device. In case no resource is found in the “hdpi” folder, all other drawable folders are checked for the resource. The first resource which is found is scaled to the device density. If the designer does not provide the resource in any drawable folder then the drawable resource will be null and nothing will be shown on the device.

How to create resources for other densities

Ratios between density categories are:

Idpi : mdpi : tvdpi : hdpi : xhdpi : 400dpi : xxhdpi : xxxhdpi
= 3  :   4  :  5.28 :   6  :    8  :   9.96 :    12  :    16

In order to scale the image, the following formula should be used:

pixels * scaleFactor = newPixelValue

For example, to scale a resource created in “hdpi” density to other densities (i.e. an image of 100x100 pixels):

Since the image is in “hdpi”, “hdpi” is the base for the scaleFactors of other densities. Based on the ratios between density categories, the scaleFactors need to be calculated.

To get a scaleFactor for “ldpi” from “hdpi”, the base ratio must be divided by the target ratio:

targetRatio /baseRatio = scaleFactor
Using these formulas the results for “ldpi”:
3 / 6 = 0.5 scaleFactor for converting “hdpi” image to “ldpi”
4 / 6 = 0.66 scaleFactor for converting “hdpi” image to “mdpi” etc…
Once all scale factors are calculated, the following formula can be used to scale the image:
100 * 0.5 x 100 * 0.5 = 50 x 50 pixels image for “ldpi”
100 * 0.66 x 100 * 0.66 = 66 x 66 pixels image “mdpi” etc…

Determine the density of a device and relevant category

On gsmarena.com, a device can be searched and in the technical specifications the “size” can be found. After the size there is the pixel density, written like (-400 PPI pixel density).

This number describes the density of the screen on the device.

Here are the categories into which each density falls:

  • ~120 – ldpi
  • ~160 – mdpi
  • ~213 – tvdpi
  • ~240 – hdpi
  • ~320 – xhdpi
  • ~400 – 400dpi
  • ~480 – xxhdpi
  • ~640 – xxxhdpi

For example the Sony Xperia Z2 has a density of ~424 PPI and as this density is greater than 400 which means it belongs to “xxhdpi” category.

Layout

Contains ginstr launcher layouts which generate a ginstr app. Layout files are XML files. Each layout consists of one or more widgets nested within the layout. One layout XML file is equivalent to one screen on the device. Upon starting ginstr launcher all layouts are loaded from a layout folder.

Layout and root layout can only have one widget as the top most element (root node). All other widgets have to be children of this widget.

Widgets that can be top elements are: LinearLayout, RelativeLayout, ScrollView, and FrameLayout.

Example of a layout file with one widget (some_layout.xml):

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
        xmlns:android="http://schemas.android.com/apk/res/android"
        android:id="@+id/rootlayout"
        android:layout_width="fill_parent"
        android:layout_width="fill_parent">
</RelativeLayout>

!IMPORTANT! A layout folder has to contain an activity.xml and a start.xml.

activity.xml is the container layout for all other root layouts and start.xml is the first root layout to be loaded on app launch.

activity.xml layout has to contain the widget:

<com.ginstr.layout.FragmentViewPager
    android:id="@+id/fragmentPager"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Values

XML files that contain simple values, such as strings, integers, arrays, colors, ids, styles. Each file contains multiple resources which are uniquely identified by an attribute name.

Valid files with values folder are: strings.xml, arrays.xml, attrs.xml, color.xml, ids.xml, styles.xml

Example of a resource file (strings.xml) containing one resource with id text_for_button:
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="text_for_button">Click me!</string>
</resources>

For referencing value resources in layouts, an appropriate identifier must be set in front of resource id.

Valid identifiers are: string, array, attr, color, id, style.

In the example below, the layout identifier string must be set in front of the unique id of string (text_for_button)

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/rootLayout"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent" >

    <TextView
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="@string/text_for_button" />
</RelativeLayout>

More information about resource types see Resource Types.

Obligatory resources and folder structures

In order for ginstr launcher to work without issues certain resources have to be present.

Obligatory folder structure

In order that ginstr launcher will allow creation of shortcut in $defaultApp when “Create shortcut” button is pressed, the following folders and files must exist:

strings.xml

Location of strings.xml should be in “values” folder in ginstr app root folder.

Obligatory strings.xml strings:

<string name="in_appName">name of the application</string> 
defines name of ginstr app that will be shown in about screen
<string name="enterAppIdHere">shortcut app name</string> 
defines name of the ginstr app which will be shown in shortcut on homescreen. enterAppIdHere should be replaced with AppId of ginstr app you’re currently developing
<string name="appName">name of the application</string> 
defines name of the ginstr app which will be used in app
<string name="appNameShortcut">shortcut app name</string> 
defines name of the ginstr app which will be shown in shortcut (at present not used but still obligatory when we switch from enterAppIdHere)

common.xml

In root folder of ginstr app has to exist “settings” folder with common.xml file.

common.xml defines common resources that are always the same regardless of language changes.

Obligatory common.xml strings:

<string name="min_client_version">30150108</string> 
always write latest version of ginstr launcher you’re currently using , the version is 3yyymmdd and date can be found when ginstr launcher $defaultApp is started by going to Preferences Screen and clicking “about”.
<string name="app_version">2.01</string> 
defines current ginstr app version. If you develop in incremental steps, it is necessary to know which ginstr app version is currently running via “about” screen and to track log of changes externally.

changelog.xml

Changes log is kept. Each time after developer executes certain changes within the application a brief description of what was done should be added to changelog.xml

Keeping track of changes simplifies debugging and seeing which new things are supported in each new version. Latest changes block has to be added on the top of the file <change …><item>…</item>…</change>

How it should be tracked:
<?xml version="1.0" encoding="utf-8"?>
<changes>
        <change developer="your name" timestamp="00.00.20xx">
                <item>initial release</item>
        </change>
        <change developer="???" timestamp="00.00.20xx">
                <item>???</item>
                <item>???</item>
        </change>
</changes>

graphic.xml

graphic.xml is used to instruct server side software to check graphical resources validity and organization of ginstr app. If you are not a ginstr app developer and will not be using ginstr servers, then this file is not necessary. File should be set in folder “settings” in root of ginstr app being developed, and should be named “graphic.xml

<?xml version="1.0" encoding="utf-8"?>
<graphic>
        <string name="themeName">white</string>
        <string name="shapeName">rounded_corners</string>
        <string name="readElements">none</string>
        <string name="pagesElements">none</string>
</graphic>

Parameters themeName, shapeName, readElements, pagesElements should all be defined in ticket on ginstr redmine system for currently developed app, if this is not the case please contact person who assigned you work.

The following information is purely informative how ginstr app graphic resources are added to the application and to clarify graphic.xml definitions.

On server side in SVN for graphic https://svn.enaikoon.de/ginstr/appsGraphic also exists a folder “appSpecifics”. Once app is deployed to SVN images from there are pulled to the app: app_icon, background.jpg and background_i.png

“_themes” folder contains all other graphic resources which are referenced in graphic.xml file with following strings:

themeName 
collection of shape names
shapeName 
specific shape for app where button shapes , input fields and horizontal lines are described. Each shape name must have common directory which contains icon images. Icon_save, settings,
readElements 
image with circles, usually used for suggestive NFC scan symbol in app
pagesElements 
navigation images with dots, these images are located in _pages_pressed - by shapeName we find directory for button grey images, common directory holds grey icons for each icon in shapeName > common directory

Alternative resources

3. Example of resources and alternative resources

Alternative resources allows loading of different app resources based on the app set preferences (locale, business domain, etc.) or the device configuration (orientation of the device, some hardware settings etc.). Each of those preferences is a qualifier.

A qualifier determines if a certain resource folder is qualified to be selected as an alternative resource. In order to qualify as an alternative resource that can be loaded the folder has to pass all set qualifiers checks. If no folder is qualified then the default resources are used.

Qualifier checks for each folder when looking for a resource:

  1. Check if all qualifiers match
  2. If more folders match
    a. Take folder with the most matching qualifiers
    b. If the number of qualifiers is equivalent the folder with the higher qualifier is selected
  3. If no folders match, the default folder with no qualifiers is selected

Example: A user has selected “English” as the language selection in an app and using the business domain “logistics”. Those are two qualifiers. When the app loads it will mark three values folders as valid: “values”, “values-en”, “values-en-Logistics”. Since qualifiers for language and domain match with “values-en-Logistics” folder it will use the last folder as an alternative resource folder. In case this resource is not available in the folder a default resource from “values” folder will be used.

Alternative resources between ginstr applications

In addition to alternative resources available within the ginstr app, it is possible to point to a resource which is contained in $defaultApp.

$defaultApp is an internal application of ginstr launcher which gets unpacked directly from ginstr launcher apk. If string resource is not found within the scope of the current ginstr app ginstr launcher will look it up in $defaultApp ginstr app folders only condition is that resource identifier matches the identifier in $defaultApp.

i.e. current ginstr app could have in strings.xml string with id=”commonString”.

If that string is not found in any strings.xml file in current ginstr app ginstr launcher will go to $defaultApp and look for the resource with same id in the strings.xml files from $defaultApp.

File and directory hierarchy

All commonly used XML files are described here for reference.

control
├─ widget_en_login.xml
├─ widget_en_listview.xml
├─ widget_en_listview_column_string.xml
├─ widget_en_listview_header_container.xml
├─ widget_en_listview_row_container.xml
├─ widget_en_custom_qrcode.xml
├─ widget_en_mediaaction.xml
├─ widget_en_listview_column_pointer.xml
├─ widget_en_listview_column_ibeacon.xml
├─ questionnaireDropDownText.xml
├─ questionnaireNumber.xml
└─ ...
database
├─ configuration.xml
├─ queries.xml
└─ variables.xml
drawable-hdpi
├─ app_icon.png
├─ appIcon.png
└─ ...
drawable-mdpi
├─ app_icon.png
├─ appIcon.png
└─ ...
drawable-xhdpi
├─ app_icon.png
├─ appIcon.png
└─ ...
drawable-xxhdpi
├─ app_icon.png
├─ appIcon.png
└─ ...
drawable-xxxhdpi
├─ app_icon.png
├─ appIcon.png
└─ ...
layout
├─ activity.xml
├─ start.xml
└─ ...
settings
├─ changelog.xml
├─ common.xml
└─ graphic.xml
values
├─ arrays.xml
├─ data.xml
├─ strings.xml
└─ styles.xml
values-XX
├─ arrays.xml
├─ data.xml
├─ strings.xml
└─ styles.xml

Further Reading

Building first ginstr apps

Subcategories

This category has only the following subcategory.