Spyglass ![Build Status](https://camo.githubusercontent.com/33ee390f73f77f64bc6e45c3b8934150169286b49528231f91d991de35534f0a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f6c696e6b6564696e2f537079676c6173732f4d65726765253230636865636b73)
A powerful Android library that provides highly-customizable widgets (with smart defaults) to easily add social-media-esque mention (aka tag) support to your app
For a broad overview, check out our blog post at the LinkedIn engineering blog.
Features
- A subclass of
EditText
that contains enhanced functionality in order to tokenize user input and display mentions - A custom view, similar to a
MultiAutoCompleteTextView
, that displays suggestions in an embeddedListView
rather than aPopup
- Custom tokenizer interface, including a default implementation containing several options for customization
- Designed to handle suggestions dynamically as are retrieved from multiple data sources
- Supports both implicit and explicit (i.e. "@User Name") mentions
Getting Started
Grab via Maven:
<dependency>
<groupId>com.linkedin.android.spyglass</groupId>
<artifactId>spyglass</artifactId>
<version>3.0.1</version>
</dependency>
or Gradle:
api 'com.linkedin.android.spyglass:spyglass:3.0.1'
Overview
Spyglass is divided into three, customizable layers: tokenization, suggestions, and mentions. Together, these layers form the update lifecycle used within Spyglass:
- User types a character
- Tokenize input
- Generate and display suggestions
- User taps a suggestion
- Insert and display mention
Let's talk about each layer individually:
Tokenization
After the user types a character, Spyglass will use a tokenizer to determine which part of the inputted text it should be considering and whether it could be a valid mention. While you may create your own tokenizer, most people should use the highly-configurable default tokenizer, the WordTokenizer
. Here are some of the features you can define and customize:
- Define characters that will trigger an explicit mention (defaults to the '@' character)
- Set the number of characters required to have been typed in the current word before displaying any suggestions (defaults to 3)
- Define the maximum number of words to return as part of your current token (defaults to 1). This option would allow you to recommend suggestions based on more than just the currently-typed word (i.e. if value is 2 and user has typed "New Mex", you could recommend "New Mexico" before just "Mexico")
- Set which characters are considered word-breaking and line-breaking characters by the tokenizer (defaults to spaces, periods, and newline characters)
For more information about implementation and configuration options, see the documentation in the WordTokenizer
class.
If the input being inspected by the tokenizer is currently valid, it will generate a QueryToken
containing the keywords that will ultimately be used to generate suggestions.
Suggestions
Once the tokenizer has generated a valid QueryToken
, Spyglass must now determine which suggestions to display using that token. It will call an implementation of QueryTokenReceiver
. This is the only interface you are required to implement to use Spyglass. This interface defines one method that takes in the generated QueryToken
. Your app can then use the token to query data from any number of data sources (i.e. servers, databases, caches, etc.) asynchronously. The function must return a list of strings, where each string is as an identifier for one of the data sources used for the given QueryToken
. Each data source must then call the SuggestionsResultListener
with the resulting suggestions and the same string identifier representing the data source for the suggestions.
As the suggestions come in from multiple data sources, the suggestions must be displayed. If you use the RichEditorView
, the suggestions will be displayed via a default view without any special ordering. You may customize the view and the order of its suggestions by providing your own implementation of SuggestionsListBuilder
. If you are using the MentionsEditText
, you will need to implement your own SuggestionsResultListener
and use the given suggestions to build your own views (typically using either a ListView
, GridView
, or more recently, a RecyclerView
). When a suggestion is selected, you will also need to call the insertMention
method on the MentionsEditText
with the suggestion to insert as a mention.
Mentions
All mentions that Spyglass insert must be a subclass of the MentionSpan
. By default, you can easily tweak how your mentions appear (i.e. highlight and text colors). Additionally, you may alter how they behave when they are deleted via multi-stage deletions. We use this extensively in the LinkedIn app to allow users to delete only the last name of a mentioned member (leaving just the first name).
Usage
To use Spyglass, you have two options: the MentionsEditText
and the RichEditorView
.
The MentionsEditText
is a subclass of EditText
. It contains extra functionality for tokenizing user input into query tokens and inserting new mentions to be displayed. Note that it does not have any view associated with displaying suggestions. You must provide that. This gives you the most power to customize how your mentions-enabled text box feels and behaves. See the "Grid Mentions" example in the sample app for a demo.
The RichEditorView
is the quickest way to add mentions into your app. It is built on top of the aforementioned MentionsEditText
and displays suggestions in an embedded ListView
. It serves a similar functionality as Android's MultiAutoCompleteTextView
. Note that you can still alter how suggestion items are displayed in the list, and you can still alter the tokenization and mention displaying options used by the underlying MentionsEditText
.
Sample App
The ''spyglass-sample'' app contains several examples of using the library. For more detailed information, see the documentation here.
Testing
We use the Robolectric framework coupled with Mockito for our unit tests. You can run them via the gradle clean test
command.
Snapshots
You can use snapshot builds to test the latest unreleased changes. A new snapshot is published after every merge to the main branch by the Deploy Snapshot Github Action workflow.
Just add the Sonatype snapshot repository to your Gradle scripts:
repositories {
maven {
url "https://oss.sonatype.org/content/repositories/snapshots/"
}
}
You can find the latest snapshot version to use in the gradle.properties file.