Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ioki-mobility/TextRef
An abstraction over Android strings with formatting support
https://github.com/ioki-mobility/TextRef
android android-library hacktoberfest library text
Last synced: 9 days ago
JSON representation
An abstraction over Android strings with formatting support
- Host: GitHub
- URL: https://github.com/ioki-mobility/TextRef
- Owner: ioki-mobility
- License: mit
- Created: 2018-11-06T11:52:02.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-05-22T19:03:20.000Z (6 months ago)
- Last Synced: 2024-05-22T20:25:36.350Z (6 months ago)
- Topics: android, android-library, hacktoberfest, library, text
- Language: Kotlin
- Homepage:
- Size: 456 KB
- Stars: 16
- Watchers: 3
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-list - ioki-mobility/TextRef - An abstraction over Android strings with formatting support (Kotlin)
README
# TextRef
[](https://github.com/ioki-mobility/TextRef/actions/workflows/test-lib.yml)
[](https://central.sonatype.com/namespace/com.ioki.textref)
[](https://s01.oss.sonatype.org/content/repositories/snapshots/com/ioki/textref/)
[](https://javadoc.io/doc/com.ioki.textref)
[](https://github.com/ioki-mobility/TextRef/blob/master/LICENSE.md)
## What?
TextRef is an abstraction over Android text. It wraps a `String` or a string/plurals resource ID.
With the help of an Android `Context` a final `String` can be resolved. Format args are supported too!
## How?
**Create**
```kotlin
TextRef.string("My string")
TextRef.stringRes(R.string.my_string)
TextRef.pluralsRes(R.plurals.number_of_items, 3)
TextRef.string("The arguments are %d and %s", 5, "foo")
```
**Resolve**
```kotlin
val text: String = textRef.resolve(context)
```
## Why?
* **String agnostic APIs:** Make functions return TextRefs to allow for any type of text representation
* **Less dependent on Context:** No need to resolve string resources close to business logic such as view models
* **Lazy formatting:** Pass format args and let TextRef do the formatting as late as possible.
* **Simplified testing:** No need to mock `Context.getString`
## Example
Here's a simple MVP use case:
```kotlin
// View
fun renderUserName(text: TextRef) {
userNameTextView.text = text.resolve(context)
}
// Presenter
val userName = if (user != null) {
TextRef.string(user.name)
} else {
TextRef.stringRes(R.string.guest)
}
view.renderUserName(userName)
```
## Requirements
* API Level >= 21
## Jetpack Compose support
Next to the core implementation we also support Jetpack compose:
```kotlin
@Composable
fun RenderText(textRef: TextRef, nullableTextRef: TextRef?) {
Text(text = textRef(textRef))
textRefOrNull(nullableTextRef)?.let { Text(text = it) }
}
```
## Download
TextRef is hosted on Maven Central. Here's how you include it in your gradle project:
**Step 1.** Add the Maven Central repository to your `build.gradle[.kts]`:
```kotlin
repositories {
mavenCentral()
}
```
For the snapshot version:
```kotlin
repositories {
maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}
```
**Step 2.** Add the dependency:
```kotlin
dependencies {
implementation("com.ioki.textref:textref:")
}
```
**Step 2.1.** Add the optional **Jetpack compose** dependency:
```kotlin
dependencies {
implementation("com.ioki.textref:compose:")
}
```
## Releasing
**Step 1.** Make sure you are on the `main` branch.
**Step 2.** Add the changes to the top of [CHANGELOG.md](CHANGELOG.md)
**Step 3.** Update the version in [`build.gradle.kts`](build.gradle.kts)
**Step 4.** Commit
```bash
git commit -m "Prepare next release" .
```
**Step 5.** Create a git tag with the version of the CHANGELOG and push the tag
```
git tag x.y.z
git push origin x.y.z
```
**Step 6.** Update the version [`build.gradle.kts`](build.gradle.kts) to the **next minor version** +`-SNAPSHOT`
**Step 7.** Commit and push the `main` branch
```bash
git push origin main
```