https://github.com/percolate/mentions
Easily add @ mention functionality to your Android applications
https://github.com/percolate/mentions
Last synced: 9 months ago
JSON representation
Easily add @ mention functionality to your Android applications
- Host: GitHub
- URL: https://github.com/percolate/mentions
- Owner: percolate
- License: bsd-3-clause
- Created: 2015-08-25T03:38:00.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2023-03-16T17:59:37.000Z (over 3 years ago)
- Last Synced: 2025-04-19T03:07:40.981Z (over 1 year ago)
- Language: Java
- Homepage:
- Size: 197 KB
- Stars: 100
- Watchers: 50
- Forks: 23
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Mentions
[](https://circleci.com/gh/percolate/mentions)
[](http://codecov.io/github/percolate/mentions?branch=master)
[](https://jitpack.io/#percolate/mentions)
[](https://www.codacy.com/app/mohit-sarveiya/mentions?utm_source=github.com&utm_medium=referral&utm_content=percolate/mentions&utm_campaign=Badge_Grade)
This library provides a simple and customizable away to setup @ mentions on any
EditText. Here's all it takes to get started.
## Usage Examples
We provide a builder through which you can setup different options for @
mentions.
Here is an example:
```java
EditText commentField = findViewById(activity, R.id.my_edit_text);
Mentions mentions = new Mentions.Builder(activity, commentField)
.highlightColor(R.color.blue)
.maxCharacters(5)
.queryListener(new QueryListener() {
void onQueryReceived(final String query) {
// Get and display results for query.
}
})
.suggestionsListener(new SuggestionsListener() {
void displaySuggestions(final boolean display) {
// Hint that can be used to show or hide your list of @ mentions".
}
})
.build();
```
The library allows you to display suggestions as you see fit. Here is an example
in the sample app [Display Suggestions](https://github.com/percolate/mentions/blob/master/Mentions/sample/src/main/java/com/percolate/mentions/sample/activities/MainActivity.java#L95).
When the user chooses a suggestion to @ mention, show it in the `EditText` view
by:
```java
final Mention mention = new Mention();
mention.setMentionName(user.getFullName());
mentions.insertMention(mention);
```
Inserting the mention will highlight it in the `EditText` view and the library
will keep track of its offset. As the user types more text in the view, the
library will update the offset and maintain the highlighting for you.
If you need to get the mentions currently shown in your `EditText` view (to send
to your API or do further processing):
```java
final List mentions = mentions.getInsertedMentions();
for (Mentionable mention : mentions) {
println("Position of 1st Character in EditText " + mention.getMentionOffset());
println("Text " + mention.getMentionName())
println("Length " + mention.getMentionLength());
}
```
### Builder methods
#### highlightColor(int color)
- After a mention is chosen from a suggestions list, it is inserted into the
`EditText` view and the mention is highlighted with a default color of orange.
You may change the highlight color by providing a color resource id.
#### maxCharacters(int maxCharacters)
- The user may type @ followed by some letters. You may want to set a threshold
to only consider certain number of characters after the @ symbol as valid
search queries. The default value 13 characters. You may configure to any
number of characters.
#### suggestionsListener(SuggestionsListener suggestionsListener)
- The SuggestionsListener interface has the method displaySuggestions(final
boolean display). It will inform you on whether to show or hide a suggestions
drop down.
#### queryListener(QueryListener queryListener)
- The QueryListener interface has the method onQueryReceived(final String
query). The library will provide you with a valid query that you could use to
filter and search for mentions. For example, if the user types @Tes, the
callback will receive "Tes" as the query.
## Adding to your application
Simply add Mentions as a gradle dependency. Distribution is done through
jitpack.io.
See for instructions
[](https://jitpack.io/#percolate/mentions)
## Running Tests
The library contains unit tests written in [Kotlin](https://kotlinlang.org/)
with [Mockito](http://mockito.org/) and [Robolectric](http://robolectric.org/).
To run the tests and generate a coverage, please execute the command
```
gradlew clean coverage
```
## License
Open source. Distributed under the BSD 3 license. See
[LICENSE.txt](https://github.com/percolate/mentions/blob/master/LICENSE.txt) for
details.