(Created page with "<div style="float:right; clear:both; margin-left:0.5em;">__TOC__</div> <span STYLE="font-size: xx-large">strings.xml naming convention</span> Category:ginstr_developers_manu...") |
(No difference)
|
Revision as of 11:21, 18 May 2020
Contents
- 1 Definitions
- 2 Resources folder
- 3 String resource fallback mechanism and overriding rules
- 4 Validators for ginstr app widgets
- 4.1 Forming rules for different cases:
- 4.1.1 Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)
- 4.1.2 Resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app
- 4.1.3 Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only
- 4.1.4 Example of decimal numerical validator for english (EN)
- 4.1.4.1 Resource id is loaded from $defaultApp and is used as is (no override in ginstr app)
- 4.1.4.2 Resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app
- 4.1.4.3 Resource id "template" is not loaded and does not exist in $defaultApp and is used directly in ginstr app only
- 4.1 Forming rules for different cases:
- 5 Buttons: execute some logic
- 6 Actions: actions are basic building blocks of logic
- 7 ListViews: display data in rows
- 8 GnMediaAction widgets: used to take pictures,video,audio,documents
- 9 Checkbox widgets: for true or false state
- 10 Dropdown widgets: selection lists
- 11 GnRadioGroup widgets: multiple choice, single selection
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:
- resource id is loaded from $defaultApp and is used as is
- resource id "template" is loaded from $defaultApp and has parameters which are variable per ginstr app
- 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<BR/>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"
:
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"
and
widgetName="customerName"
and name of column in listview is
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" and 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>