From wiki.ginstr.com
Jump to: navigation, search
m (Redirected page to Category:.ginstr app)
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
<div style="float:right; clear:both; margin-left:0.5em;">__TOC__</div>
+
#REDIRECT [[:Category:.ginstr_app]]
==Minimal app folders and files of ginstr app==
 
 
 
For each ginstr app following folders must be present:<br>
 
;control : contains XML files for further customisation of [[widgets]], for example <code>[[GnEditText]]</code>, <code>[[GnListView]]</code> 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-$ : <code>$</code> 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 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 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==
 
[[File:Ginstr_apps_files_on_computer_(left)_and_Android_device_(right).png|600px|thumb|1. ginstr apps files on computer (left) and Android device (right)]]
 
[http://wiki.ginstr.com/index.php/File:Ginstr_apps_files_on_computer_(left)_and_Android_device_(right).png 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 '''airConditionerMaintainence'''.
 
 
 
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 [http://wiki.ginstr.com/index.php/File:Ginstr_apps_files_on_computer_(left)_and_Android_device_(right).png Screenshot 1] to '''com.ginstr''' folder. Path to '''com.ginstr''' may not be same on all devices. For example [http://wiki.ginstr.com/index.php/File:Ginstr_apps_files_on_computer_(left)_and_Android_device_(right).png 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 [http://wiki.ginstr.com/index.php/File:Ginstr_app_shortcut_(left)_started_ginstr_app_(right).png 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 [http://www.ghisler.com/ 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 [https://sites.google.com/site/andreasliebigapps/ftpserver FTPService], device behaves like a server and on computer FTP manager (for instance [https://filezilla-project.org/ FileZilla]) connects to device as on any other FTP server. For additional information consult product manuals for [https://sites.google.com/site/andreasliebigapps/ftpserver/usage FTPService] and [https://wiki.filezilla-project.org/Documentation FileZilla].
 
 
 
[[File:Ginstr_app_shortcut_(left)_started_ginstr_app_(right).png|400px|thumb|none|2. Login screen of defaultApp]]
 
 
 
==Resources and ginstr app file structure in detail==
 
Resources can be divided into two main categories:
 
#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
 
#Other resources
 
#:(images, fonts, sounds…)
 
 
 
All ginstr app files are stored in the folder (ginstr launcher base folder):
 
 
 
<pre>BASE_PATH = external storage /Android/data/com.ginstr/</pre>
 
 
 
==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 <code>[[GnLogin]]</code> widget or <code>[[GnResetPassword]]</code>. 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.
 
===Database===
 
Contains files that are relevant to building a [[database]], creating database queries and tables, columns. More information about databases available [[database|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]] <code>@drawable/someImage</code>. Images are then found using the name under which they are saved in the drawable folder for example, widget with drawable:
 
 
 
<source lang="xml">
 
<ImageView
 
    android:layout_width="wrap_content"
 
    android:layout_height="wrap_content"
 
    android:src="@drawable/image" />
 
</source>
 
 
 
====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 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 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 <code>null</code> and nothing will be shown on the device.
 
 
 
====How to create resources for other densities====
 
Ratios between density categories are:
 
<pre>Idpi : mdpi : tvdpi : hdpi : xhdpi : 400dpi : xxhdpi : xxxhdpi
 
= 3  :  4  :  5.28 :  6  :    8  :  9.96 :    12  :    16</pre>
 
 
 
In order to scale the image the following formula should be used:
 
 
 
<pre>pixels * scaleFactor = newPixelValue</pre>
 
 
 
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 <code>scaleFactor</code> for '''“ldpi”''' from '''“hdpi”''', the base ratio needs to be divided by the target ratio:
 
 
 
::<pre>targetRatio /baseRatio = scaleFactor</pre>
 
::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 [http://www.gsmarena.com 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: <code>[http://developer.android.com/reference/android/widget/LinearLayout.html LinearLayout]</code>, <code>[http://developer.android.com/reference/android/widget/RelativeLayout.html RelativeLayout]</code>, <code>[http://developer.android.com/reference/android/widget/ScrollView.html ScrollView]</code>, and <code>[http://developer.android.com/reference/android/widget/FrameLayout.html FrameLayout]</code>.
 
 
 
Example of a layout file with one widget ('''some_layout.xml'''):
 
<source lang="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>
 
</source>
 
 
<span style="color: red">'''!IMPORTANT!'''</span> 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:
 
<source lang="xml">
 
<de.enaikoon.ag.layout.FragmentViewPager
 
    android:id="@+id/fragmentPager"
 
    android:layout_width="match_parent"
 
    android:layout_height="match_parent" />
 
</source>
 
 
 
===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 <code>text_for_button</code>:
 
 
<source lang="xml">
 
<?xml version="1.0" encoding="utf-8"?>
 
<resources>
 
    <string name="text_for_button">Click me!</string>
 
</resources>
 
</source>
 
 
 
For referencing value resources in layouts an appropriate identifier needs to be set in front of resource id. Valid identifiers are: <code>string</code>, <code>array</code>, <code>attr</code>, <code>color</code>, <code>id</code>, <code>style</code>.
 
 
 
To reference for example a string from [http://wiki.ginstr.com/index.php/File:Example_of_referencing_string.png Screenshot 3] (below), the unique id of string has to be used in the layout identifier for string (<code style="color: red">identifier</code>/<code style="color: blue">string id</code>).
 
 
 
[[File:Example_of_referencing_string.png|frame|none|3. Example of referencing string]]
 
 
 
More information about resource types see [http://developer.android.com/guide/topics/resources/more-resources.html 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:
 
* '''“layout” folder'''
 
** [[start.xml]] file
 
** [[activity.xml]] file
 
* '''“values” folder'''
 
** [[strings.xml]] file
 
 
 
===strings.xml===
 
Location of [[strings.xml]] should be in “values” folder in ginstr app root folder.
 
 
 
Obligatory [[strings.xml]] strings:
 
::;'''<code><string name="in_appName">name of the application</string></code>''' : defines name of ginstr app that will be shown in about screen
 
::;'''<code><string name="enterAppIdHere">shortcut app name</string></code>''' : defines name of the ginstr app which will be shown in shortcut on homescreen. <code>enterAppIdHere</code> should be replaced with AppId of ginstr app you’re currently developing
 
::;'''<code><string name="appName">name of the application</string></code>''' : defines name of the ginstr app which will be used in app
 
::;'''<code><string name="appNameShortcut">shortcut app name</string></code>''' : defines name of the ginstr app which will be shown in shortcut (at present not used but still obligatory when we switch from <code>enterAppIdHere</code>)
 
 
 
===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:
 
::;'''<code><string name="min_client_version">30150108</string></code>''' : always write latest version of ginstr launcher you’re currently using , the version is <code>3yyymmdd</code> and date can be found when ginstr launcher [[$defaultApp]] is started by going to “preferences screen” and clicking “about”.
 
::;'''<code><string name="app_version">2.01</string></code>''' : 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 <code><change …><item>…</item>…</change></code>
 
 
 
::How it should be tracked:
 
<source lang="xml">
 
<?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>
 
</source>
 
 
 
===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]]”
 
 
 
<source lang="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>
 
</source>
 
 
Parameters <code>themeName</code>, <code>shapeName</code>, <code>readElements</code>, <code>pagesElements</code> 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 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: <code>app_icon</code>, <code>background.jpg</code> and <code>background_i.png</code>
 
 
 
'''“_themes”''' folder contains all other graphic resources which are referenced in [[graphic.xml]] file with following strings:
 
 
 
::;<code>themeName</code> : collection of shape names
 
::;<code>shapeName</code> : 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,
 
::;<code>readElements</code> : image with circles, usually used for suggestive NFC scan symbol in app
 
::;<code>pagesElements</code> : navigation images with dots, these images are located in '''_pages_pressed''' - by <code>shapeName</code> we find directory for button grey images, common directory holds grey icons for each icon in '''shapeName > common directory'''
 
 
 
==Alternative resources==
 
[[File:Example_of_resources_and_alternative_resources.png|frame|4. 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:
 
# Check if all qualifiers match
 
# 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
 
# 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 <code>id=”commonString”</code>.
 
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]].
 
 
 
==Further Reading==
 
===[[building first ginstr apps]]===
 

Latest revision as of 13:29, 3 July 2016