Launcher error codes

strings.xml naming convention

This document serves as a set of rules how to form string resources id's for widgets that are used in ginstr apps.

Definitions

${pageName}

defined by android:id attribute of the root screen element, NOT by fileName of file which contains widgets

${widgetName}

defined by ginstr app developer or in case of app-composer auto generated

It is strictly forbidden to use one resource in two different places of an app. In this case 2 different resources must be implemented.

Resources folder

Resources folders are found at each ginstr app on path:

default folder

appId/values/strings.xml

or for English

appId/values-en/strings.xml

or where LANG is language parameter

appId/values-LANG/strings.xml

String resource fallback mechanism and overriding rules

If resource is not found in ginstr app ginstr launcher has fallback mechanism to load resources from $defaultApp.

All resources that are in $defaultApp are globally available to all ginstr apps. If certain resource does not exist in any "strings.xml" of a ginstr app but is referenced in "layouts" of ginstr app and exists in $defaultApp then it will be loaded from $defaultApp. If you override a resource id that exists in $defaultApp in ginstr app $defaultApp resource will be ignored but this also means if you would change a generic message that is used across multiple ginstr apps for this app where is overridden it would not apply but additional modification of that overridden resource would be required.

There can be 3 situations when using resources in ginstr app:

1. resource id is loaded from $defaultApp and is used as is
2. resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app
3. resource id "template" is not loaded and does not exist in $defaultApp

$defaultApp resource id's prefix

All string resource id's in $defaultApp should start with $ symbol:

i.e.

<string name="$txtAppManagerInstall">install</string>
<string name="$txtAppManagerUninstall">uninstall</string>
<string name="$txtAppRecreateShortcuts">create icons&lt;BR/&gt;on the launch screen</string>

Labels: for ginstr app input fields

Label represents text above the input field of a widget. Resource id "template" is not loaded and does not exist in $defaultApp Labels should have the resource id formed as:

@string/${pageName}_${widgetName}

which would look like this on widget:

<com.ginstr.widgets.GnTextView
    android:id="..." 
    android:layout_width="match_parent" 
    android:layout_height="wrap_content" 
    android:text="@string/${pageName}_${widgetName}" 
    gn:style="..."/>

and in strings:

<string name="${pageName}_${widgetName}">example label</string>

example if pageName="pageOne" and widgetName="customerName":

<com.ginstr.widgets.GnTextView
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    android:text="@string/pageOne_customerName" 
    gn:style="..."/>

and example in strings:

<string name="pageOne_customerName">example label</string>

Hints: for ginstr app input fields

Hint represents text which is shown in input field when it's empty as a suggestion to user. Resource id "template" is not loaded and does not exist in $defaultApp

Hints should have resource id formed as:

@string/${pageName}_${widgetName}Hint

which would look like this on widget:

<com.ginstr.widgets.GnEditText
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:s_hint="@string/${pageName}_${widgetName}Hint" 
    gn:data_type="..." 
    gn:style="..."/>

and in strings:

<string name="${pageName}_${widgetName}Hint">example label hint</string>

example if pageName="pageOne" and widgetName="customerName":

<com.ginstr.widgets.GnEditText
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:s_hint="@string/pageOne_customerNameHint" 
    gn:data_type="..." 
    gn:style="..."/>

and example in strings:

<string name="pageOne_customerNameHint">example label hint</string>

Validators for ginstr app widgets

Validators are mechanisms that check if user entry is valid and prevent user from typing something that should not be typed in certain input field, i.e. typing text into a kilos field when number is expected. There can be multiple validators on a widget. Validation messages can also be loaded from $defaultApp. There are multiple validators and multiple strings that each validator contains.

$defaultApp contains predefined validation messages which are used for various purposes, in that case resourceId prefix is:

PREFIX + SUFFIX

{PredefinedNameOfValidation} + ValidatorNameKeyValue

Prefix

is defined by ginstr app developer with purpose of validation, i.e. "checkIfAllFieldsFilled"

Suffix

in the validator resourceId defines which validator and which message within validator is targeted:

Validator types "ValidatorName":

• TextValidator
• ComparatorValidator
• RequiredValidator

Validator messages for override "KeyValue" (see all of them here) :

MinLength
MaxLength
REGEX
PhoneErrMsg
EmailErrMsg
MinLengthErrMsg
.... 

The above information should be used in forming rules for different cases.

Forming rules for different cases:

Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)

@string/$PredefinedNameOfValidationValidatorNameKeyValue

which would look like this on widget:

    <com.ginstr.widgets.GnEditText
        android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:RequiredValidator],[message=@string/$PredefinedNameOfValidationValidatorNameKeyValue]" 
    gn:s_sourceType="input"/>

and in strings at $defaultApp:

<string name="$PredefinedNameOfValidationValidatorNameKeyValue">this is a default predefined message for validation</string>

example if predefinedNameOfValidation="checkIfAllFieldsFilled" and validatorName="RequiredValidator" and KeyValue="message":

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:RequiredValidator],[message=@string/$checkIfAllFieldsFilledRequiredValidatorMessage]" 
    gn:s_sourceType="input"/>

and example in strings at $defaultApp:

<string name="checkIfAllFieldsFilledRequiredValidatorMessage">please fill all fields which have a '*'</string>

Resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app

In this case resource should be copied from $defaultApp and variable content should be "replaced" and when done saved into ginstr app strings.xml Rule for forming resource ID in such case:

@string/${pageName}_${widgetName}ValidatorNameKeyValue

Content in $defaultApp:

<string name="$PredefinedNameOfValidationValidatorNameKeyValue">some value using params, %1$s , %2$s</string>

i.e.

<string name="checkIfFieldIsFilledRequiredRequiredValidatorMessage">entering the %1$s is required</string>

should be generated in ginstr app as:

on widget:

    <com.ginstr.widgets.GnEditText  
        android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:RequiredValidator],[message=@string/${pageName}_${widgetName}ValidatorNameKeyValue]" 
    gn:s_sourceType="input"/>

and in strings at ginstr app:

<string name="${pageName}_${widgetName}ValidatorNameKeyValue">entering the ${widgetName} is required</string>

example if pageName="pageOne" and widgetName="customerName" and validatorName="RequiredValidator" and KeyValue="message":

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:RequiredValidator],[message=@string/$pageOne_customerNameRequiredValidatorMessage]" 
    gn:s_sourceType="input"/>

and example in strings:

<string name="pageOne_customerNameRequiredValidatorMessage">entering the customerName is required</string>

Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only

Rule for forming resource ID in such case:

@string/${pageName}_${widgetName}ValidatorNameKeyValue

should be generated in ginstr app as:

on widget:

    <com.ginstr.widgets.GnEditText
        android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:RequiredValidator],[message=@string/${pageName}_${widgetName}ValidatorNameKeyValue]" 
    gn:s_sourceType="input"/>

and in strings at ginstr app:

<string name="${pageName}_${widgetName}ValidatorNameKeyValue">entering this value is required</string>

Example of decimal numerical validator for english (EN)

Maximum allowed number length is 15 which can be stored into ginstr back-end. For that reason there are 2 validator rules used.

Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)

resourceId prefix for number decimal is : widgetId + ValidatorName + KeyValue i.e. NumberDecimal + TextValidator + MaxLength (see NumberDecimal for further information)

$defaultApp contains:

<string name="$NumberDecimalTextValidatorMaxLength">maximum allowed number length is 15</string>
<string name="$NumberDecimalTextValidatorREGEX">only decimal numbers are allowed</string>
<string name="$NumberDecimalTextValidatorPattern">^[-+]?[0-9]*(\.)?[0-9]+\b$</string>

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:TextValidator],[maxLength=15],[maxLengthErrMsg=@string/$NumberDecimalTextValidatorMaxLength]" 
        gn:act_validate2="[name:TextValidator],[inputType=REGEX],[REGEXErrMsg=@string/$NumberDecimalTextValidatorREGEX],[pattern=@string/NumberDecimalTextValidatorPattern]" 
    gn:s_sourceType="input"/>

Resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app

$defaultApp contains:

<string name="$NumberDecimalTextValidatorMaxLength">maximum allowed %1$s length is %2$s</string>
<string name="$NumberDecimalTextValidatorREGEX">only decimal numbers are allowed for %1$s</string>
<string name="$NumberDecimalTextValidatorPattern">^[-+]?[0-9]*(\.)?[0-9]+\b$</string>

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:TextValidator],[maxLength=15],[maxLengthErrMsg=@string/$NumberDecimalTextValidatorMaxLength]" 
        gn:act_validate2="[name:TextValidator],[inputType=REGEX],[REGEXErrMsg=@string/$NumberDecimalTextValidatorREGEX],[pattern=@string/NumberDecimalTextValidatorPattern]" 
    gn:s_sourceType="input"/>

app specific generated:

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:TextValidator],[maxLength=15],[maxLengthErrMsg=@string/${pageName}_${widgetName}NumberDecimalTextValidatorMaxLength]" 
        gn:act_validate2="[name:TextValidator],[inputType=REGEX],[REGEXErrMsg=@string/${pageName}_${widgetName}NumberDecimalTextValidatorREGEX],[pattern=@string/NumberDecimalTextValidatorPattern]" 
    gn:s_sourceType="input"/>

in strings.xml:

<string name="${pageName}_${widgetName}NumberDecimalTextValidatorMaxLength">maximum allowed ${widgetName} length is ${maxLength}</string>
<string name="${pageName}_${widgetName}NumberDecimalTextValidatorREGEX">only decimal numbers are allowed for ${widgetName}</string>

Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only

<com.ginstr.widgets.GnEditText
    android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        gn:act_validate="[name:TextValidator],[maxLength=15],[maxLengthErrMsg=@string/${pageName}${widgetName}NumberDecimalTextValidatorMaxLength]" 
        gn:act_validate2="[name:TextValidator],[inputType=REGEX],[REGEXErrMsg=@string/${pageName}_${widgetName}NumberDecimalTextValidatorREGEX],[pattern=@string/$NumberDecimalTextValidatorPattern]" 
    gn:s_sourceType="input"/>

in strings.xml:

<string name="${pageName}_${widgetName}NumberDecimalTextValidatorMaxLength">maximum allowed ${widgetName} length is ${maxLength}</string>
<string name="${pageName}_${widgetName}NumberDecimalTextValidatorREGEX">only decimal numbers are allowed for ${widgetName}</string>

Buttons: execute some logic

Buttons should have the resource id formed as: @string/${pageName}_${widgetName}

which would look like this on widget:

<Button
  android:id="..." 
  android:layout_width="..." 
  android:layout_height="..." 
  android:background="..." 
  gn:setBackgroundPressed="..." 
  gn:style="..." 
  android:text="@string/${pageName}_${widgetName}"/>

in strings.xml:

<string name="${pageName}_${widgetName}">button function</string>

Example if pageName="pageOne" and widgetName="saveCustomerData":

<Button
  android:id="..." 
  android:layout_width="..." 
  android:layout_height="..." 
  android:background="..." 
  gn:setBackgroundPressed="..." 
  gn:style="..." 
  android:text="@string/pageOne_saveCustomerData"/>

in strings.xml:

<string name="pageOne_saveCustomerData">save customer data</string>

Actions: actions are basic building blocks of logic

Actions can simply execute some logic behind the scenes or they have some UI dependency. When there is UI usually some message to the user is shown, in that case we need to provide string resources for it, i.e. toasts, dialogs...

Each action should have individually defined string resourceID. In app composer those IDs should be defined by each app composer widget individually. We can call those IDs ActionSpecificId.

Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)

Some strings can be default for all ginstr app and in that case their resourceID is unique.

In $defaultApp action message should have the resource id formed as:

<string name="$meaningfulNameBasedOnPurpose">some generic text message</string>

where meaningfulNameBasedOnPurpose is the default message resourceID that is shown across multiple apps

in action it is shown as:

[gn:act_toast]|[@string/$meaningfulNameBasedOnPurpose]

i.e. we show message when screen validation is executed if some fields are not filled and this message is same in all apps:

In $defaultApp resourceId:

<string name="$toastValidateAllRequiredFields">please filled all required field marked with '*'</string>

in action:

...[gn:act_toast]|[@string/$toastValidateAllRequiredFields]...

Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only

In case some action message or UI should be shown and it does not relate to some generic message for all apps then resourceID is defined within action definition.

If action is used multiple times on same widget then the SUFFIX +1 is added at end of resourceID starting with 2

<string name="${pageName}_${widgetName}ActionNameActionSpecificId">${widgetName}</string>

i.e. if pageName="pageOne" and widgetName="customerName" and action that is used is toast : toast has only single message internally so ActionSpecifiId is not required.

<string name="pageOne_customerNameToast">customerName</string>

If two toasts would be executed on a widget customerName:

<string name="pageOne_customerNameToast2">${widgetName}</string>

If three toasts would be executed on a widget customerName:

<string name="pageOne_customerNameToast3">${widgetName}</string>

Yes/No choice dialog example

Example of action which contains multiple text resources

[gn:act_showYesNoDialog]|[@string/title,@string/message,@string/yesText,@string/noText]

in this case of this action contains multiple strings and ActionSpecificId is required.

i.e. if pageName="pageOne" and widgetName="customerName" and action that is used is gn:act_showYesNoDialog:

<string name="pageOne_customerNameShowYesNoDialogTitle">dialog title text</string>
<string name="pageOne_customerNameShowYesNoDialogMessage">dialog message text</string>
<string name="pageOne_customerNameShowYesNoDialogYesText">dialog yes text</string>
<string name="pageOne_customerNameShowYesNoDialogNoText">dialog no text</string>

ListViews: display data in rows

Data is displayed in rows and the format of the row recycles each time new row is shown, this means that "design" of row remains while few dynamic contents that depend on data from row, change.

Labels should have the resource id formed as: @string/${pageName}_${widgetName}${columnName} i.e. if pageName="pageOne"<code> and <code>widgetName="customerName"<code> and name of column in listview is <code>customer:

<string name="pageOne_customerNameCustomer">customer column label</string>

GnMediaAction widgets: used to take pictures,video,audio,documents

Consist of two widgets one is "label" which goes above GnMediaAction and other is GnMediaAction itself which is shown as icon label describes widget name while GnMediaAction takes and stores the media.

Labels for GnMediaAction should have the resource id formed as per Labels: for ginstr app input fields

Checkbox widgets: for true or false state

Consist of two widgets one is "label" which goes next to GnCheckBox widget and other is GnCheckBox itself which is shown as "square" which is filled with "check" symbol (depending if checked or not checked) Labels for GnCheckBox should have the resource id formed as per Labels: for ginstr app input fields

Dropdown widgets: selection lists

Consists of two widgets one is "label" which goes above GnDropDown widget and other is GnDropDown itself which is shown as selection box with text

Labels for GnDropDown should have the resource id formed as per Labels: for ginstr app input fields

Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)

In $defaultApp:

@string/$GnDropDownZeroItem
@string/$GnDropDownNoData

which is then used internally by GnDropdown

Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only

In $defaultApp:

@string/$GnDropDownZeroItem
@string/$GnDropDownNoData

On widget:

<com.ginstr.widgets.GnDropDown
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:singleItemMode="..." 
    gn:s_sourceType="..." 
    gn:data_source_request="..." 
    gn:data_source_field="..." 
    gn:s_ZeroItemText="@string/${pageName}_${widgetName}ZeroItem" 
    gn:msg_nodata="@string/${pageName}_${widgetName}NoData" 
    gn:zeroItemEventEnabled="..."/>

<string name="${pageName}_${widgetName}ZeroItem">custom zero item message</string>
<string name="${pageName}_${widgetName}NoData">custom no data message</string>

i.e. if pageName="pageOne"<code> and <code>widgetName="customerName"

<com.ginstr.widgets.GnDropDown
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:singleItemMode="..." 
    gn:s_sourceType="..." 
    gn:data_source_request="..." 
    gn:data_source_field="..." 
    gn:s_ZeroItemText="@string/pageOne_customerNameZeroItem" 
    gn:msg_nodata="@string/pageOne_customerNameNoData" 
    gn:zeroItemEventEnabled="..."/>

<string name="pageOne_customerNameZeroItem">custom zero item message</string>
<string name="pageOne_customerNameNoData">custom no data message</string>

GnRadioGroup widgets: multiple choice, single selection

GnRadioGroup offers set of predefined choices where user can choose only single option (or none depending on business logic). Consists of two widgets one is "label" which goes above GnRadioGroup widget and other is GnRadioGroup itself which is shown as group of X GnRadioButtons

Labels for GnRadioGroup should have the resource id formed as per Labels: for ginstr app input fields

GnRadioGroup radio buttons should have the resourceID formed as:

@string/${pageName}_${widgetName}${radioButtonName}

On widget:

<com.ginstr.widgets.GnRadioGroup
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:dataType="..." 
    android:orientation="...">

    <com.ginstr.widgets.GnRadioButton
        android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        android:text="@string/${pageName}_${widgetName}${radioButtonName}"/>
</com.ginstr.widgets.GnRadioGroup> 

i.e. if pageName="pageOne" and widgetName="textColor" and radioButtonName="red"

<com.ginstr.widgets.GnRadioGroup
    android:id="..." 
    android:layout_width="..." 
    android:layout_height="..." 
    gn:dataType="..." 
    android:orientation="...">

    <com.ginstr.widgets.GnRadioButton
        android:id="..." 
        android:layout_width="..." 
        android:layout_height="..." 
        android:text="@string/pageOne_textColorRed"/>
</com.ginstr.widgets.GnRadioGroup> 

In strings:

<string name="pageOne_textColorRed">red</string>