From wiki.ginstr.com
Revision as of 14:52, 21 June 2016 by Mark (talk | contribs) (Created page with "<div style="float:right; clear:both; margin-left:0.5em;">__TOC__</div> =Building first ginstr apps= ==Minimal app folders and files of ginstr app== For each ginstr app follo...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Building first ginstr apps

Minimal app folders and files of ginstr app

For each ginstr app following folders must be present:

control 
contains xml files for further customization of widgets for example GnEditText, GnListView and more.
database 
contains configuration.xml, queries.xml and variables.xml. More about purposes of each file further in manual.
drawable-$ 
$ stands for hdpi, mdpi, xhdpi, xxhdpi and xxxhdpi containing same graphic resources but in different sizes. To ensure best possible UI, graphics are pre-made for several groups of screen densities, where usually bigger screen has bigger density and folder with largest graphics is used. Number of images in each graphical folder must be the same and same images in different folders should have same filenames.
layout 
activity.xml and start.xml are required for app to display login screen and making authentification. 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 is app using)
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 folder will be used for display text values of referenced strings.

Location of ginstr apps on device

On image below is provided overview of location ginstr launcher and ginstr app files on developing computer and Android device. Each ginstr app has root folder, in out example this is airConditionerMaintanence. When ginstr launcher is installed on device, it creates folder com.ginstr with 2 subfolders: $configSets and $defaultApp. To add new ginstr app to ginstr launcher on device, app files are copied with app root folder as showed on image below to com.ginstr folder. Path to com.ginstr may not be same on all devices. For example on image below this is case 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 own shortcut. It is good practice to work on XML files on computer (local) and then transferring again to device in same location. This ensures saving work on computer, because ginstr app files could end up only on device and never transfered to computer and work could be lost.

login screen of defaultApp

On image below red arrow is pointing from created shortcut 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 logs in ginstr web UI. Transferring ginstr app files can be achieved with plain folder explorer (in windows this is Windows Explorer). Connecting device with USB to computer, navigate to path com.ginstr and copy/paste inside ginstr app files. File manager apps could be used, for instance Total Commander. Other way could be wireless transfer data from computer to device, for this device must be connected to same local wifi network as computer. Using Android apps like FTP service, device is behaving like server and on computer FTP manager (for instance FileZilla) connects to device as on any other FTP server. For additional information consult product manuals how to use Android app FTPService on device and FileZilla.

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 customized styling that will replace default widget styling.

Database

Contains files that are relevant to building a database, creating database queries and tables, columns. More information about databases in available in the database section of this manual.

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:

1. Widget with drawable image

Density folder for drawable resources

Drawable resources are displayed differently on different devices. In example an entry level device has a lower resolution than a top of the line 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 top of the line device the resource will appear smaller or the resolution will create a pixilation 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 in the resource found the density is scaled to that of the device. In case no resource is found in the “hdpi” folder then 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 density

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

An example how a designer should scale a resource if the base graphics are created in “hdpi” density and how this to convert 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 scale factor for “ldpi” from “hdpi” base ratio needs to 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 in which category it belongs (ldpi, mdpi, hdpi …)

On this website, 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 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 more than 400 which means it belongs to “xxhdpi” category.

Layout

Contains GL 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 GL 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.
More information about widgets is available in widget description section.

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

File:layout example.png
2. Layout example

!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:

3. Widget for holding other layouts on activity.xml

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 containing one resource with id “text_for_button”, strings.xml:
4. Example of strings.xml

For referencing value resources in layouts an appropriate identifier needs to be set in front of resource id. Valid identifiers are: string, array, attr, color, id, style. To reference for example a string from Image 5 (below), the unique id of string has to be used in the layout identifier for string (identifier, string id).

5. Example of referencing string

More information about resource types Resource types.



4.2 Obligatory resources and folder structures In order for GL to work without issues some resources have to be present. 4.2.1 Obligatory folder structure In order that GL will allow creation of shortcut in $defaultApp when “Create shortcut” button is pressed following folders and files have to exist: • “layout” folder o “start.xml” file o “activity.xml” file • “values” folder o “strings.xml” file 4.2.2 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. name= write app id 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)

4.2.3 commons.xml In root folder of ginstr app has to exist “settings” folder with common.xml file. commons.xml defines common resources that are always the same regardless of language changes Obligatory commons.xml strings: • <string name="min_client_version">30150108</string> - always write latest version of GL you’re currently using , the version is 3yyymmdd and date can be found when GL $defaultApp is started by going to “preferences screen” and clicking “about” the date of launcher gives rest of information • <string name="app_version">2.01</string> - defines current ginstr app version, it’s necessary if you develop in incremental steps to know which ginstr app version is currently running via “about” screen and to track log of changes externally 4.2.4 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:



4.3 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 ginstr app developer and will not be using ginstr servers 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”

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. 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 graph-ic.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, this 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 4.4 Alternative resources Alternative resources allow to load 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 al-ternative 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.


6. example of resources and alternative resources 4.5 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 internal application of GL which gets unpacked directly form GL apk. If string resource is not found within the scope of the current ginstr app GL 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 GL will go to $defaultApp and look for the resource with same id in the strings.xml files from $defaultApp.