This app is intended to be used from ODK Collect as a counter.
- ODK website: https://getodk.org
- ODK forum: https://forum.getodk.org
- ODK developer Slack chat: http://slack.getodk.org
In order to use the app you need to create a form which contains an ExIntegerWidget and add an appearance according to this pattern:
appearance="ex:org.opendatakit.counter(form_id='counter-form', form_name='Counter Form', question_id='1', question_name='Counter 1', increment=true())"
form_id - a unique form identifier
form_name - a form name (displayed to the user)
question_id - a unique question identifier
question_name - a question name (displayed to the user)
increment=true() - an optional parameter. If set to true an initial value displayed in the Counter app is 0 and it will be increased by 1 after 0.5s otherwise the initial value is set to 1 and autoincrement doesn't take place.
autoincrement=true() - an optional parameter. If set to true it works like increment=true() but additionally the buttons to manually change the value are disabled.
When both increment and autoincrement are used autoincrement takes precedence.
You can use translations in form_name and question_name by following this pattern:
appearance="ex:org.opendatakit.counter(form_id='counter-form', form_name=jr:itext('/data/form_name:label'), question_id='2', question_name=jr:itext('/data/Counter2:label'), increment=true())"
form_id and question_id are needed since we store last saved values for pairs <form_id, question_id> to set the value of a counter when a user opens the app for the same pair <form_id, question_id> again. The selected value is returned to the ODK Collect via the RESULT_OK mechanism.
To get started, use the provided sample forms: XLSForm (xlsx), XForm (xml).
-
Download and install Git and add it to your PATH
-
Download and install Android Studio
-
Fork the counter project (why and how to fork)
-
Clone your fork of the project locally. At the command line:
git clone https://github.com/YOUR-GITHUB-USERNAME/counter
If you prefer not to use the command line, you can use Android Studio to create a new project from version control using https://github.com/YOUR-GITHUB-USERNAME/counter.
- Open the project in the folder of your clone from Android Studio. To run the project, click on the green arrow at the top of the screen. The emulator is very slow so we generally recommend using a physical device when possible.
Any and all contributions to the project are welcome.
Issues tagged as quick win should be a good place to start. There are also currently many issues tagged as needs reproduction which need someone to try to reproduce them with the current version of ODK Counter and comment on the issue with their findings.
If you're ready to contribute code, see the contribution guide.
All releases are verified on the following devices (ordered by Android version):
- Samsung Galaxy Young GT-S6310 - Android 4.1.2
- Infinix Race Bolt Q X451 - Android 4.2.1
- Samsung Galaxy J1 SM-J100H - Android 4.4.4
- Huawei Y560-L01 - Android 5.1.1
- Sony Xperia Z3 D6603 -Android 6.0.1
Our regular code contributors use these devices (ordered by Android version):
- XOLO Q700s plus - Android 4.4.2
- Samsung Galaxy S4 GT-I9506 - Android 5.0.1
- Samsung Galaxy Tab SM-T285 - Android 5.1.1
- Motorola G4 4th Gen XT1625 - Android 7.0
Project maintainers have the keys to upload signed releases to the Play Store.
Maintainers have a secrets.properties file in the app folder with the following:
// app/secrets.properties
RELEASE_STORE_FILE=/path/to/counter.keystore
RELEASE_STORE_PASSWORD=secure-store-password
RELEASE_KEY_ALIAS=key-alias
RELEASE_KEY_PASSWORD=secure-alias-password
To generate official signed releases, you'll need the keystore file, the keystore passwords, a configured secrets.properties file, and then run ./gradlew assembleRelease. If successful, a signed release will be at app/build/outputs/apk.