TOMSSuggestionBar
A keyboard accessory that presents suggestions. Suggestions are displayed as morphing labels and fetched from a custom database.
The main approach of this project is to make a control that works like Apples keyboard suggestion bar (as seen in iOS 8 announcement) with custom data.
Demo
Installation with CocoaPods
TOMSSuggestionBar is available through CocoaPods. To install it, simply add the following line to your Podfile:
Podfile
platform :ios, '7.0'
pod "TOMSSuggestionBar", "~> 0.1.2"Quick Start
Simply instantiate TOMSSuggestionBar and subscribe a textField to the suggestions.
The following suggestionBar would suggest name values of instances of type Person which was defined in Model.xcdatamodeld.
TOMSSuggestionBar *suggestionBar = [[TOMSSuggestionBar alloc] init];
[suggestionBar subscribeTextInputView:self.textField
toSuggestionsForAttributeNamed:@"name"
ofEntityNamed:@"Person"
inModelNamed:@"Model"];Customization
Appearance
The suggestionBars appearance can be easily modified.
/**
Instantiate a suggestionBar with an alternative number of suggestionFields.
*/
TOMSSuggestionBar *suggestionBar = [[TOMSSuggestionBar alloc] initWithNumberOfSuggestionFields:5];
/**
Easily customize the bars colors and font.
*/
suggestionBar.backgroundColor = [UIColor redColor];
suggestionBar.tileColor = [UIColor greenColor];
suggestionBar.textColor = [UIColor blueColor];
suggestionBar.font = [UIFont systemFontOfSize:18];Delegate or DataSource
You may adopt TOMSSuggestionDelegate or TOMSSuggestionDataSource and register as the suggestionBars delegate or dataSource.
Delegate protocol
/**
Gets called when a suggestion tile is tapped.
@param suggestionBar The suggestionBar containing the tapped tile.
@param suggestion The text on the tapped tile.
@param associatedObject The instance fetched from CoreData that is represented by the tapped text.
*/
- (void)suggestionBar:(TOMSSuggestionBar *)suggestionBar
didSelectSuggestion:(NSString *)suggestion
associatedObject:(NSManagedObject *)associatedObject;DataSource protocol
/**
Returns a `NSString` that is a substring of the overall textInput. It represents the substring that is relevant for fetching instances from CoreData for suggestions.
@param suggestionBar The suggestionBar that is displaying the contents.
@param textInput The whole text within the suggestionBars subscribed textInput.
@param caretLocation The location of the caret.
*/
- (NSString *)suggestionBar:(TOMSSuggestionBar *)suggestionBar
relevantContextForInput:(NSString *)textInput
caretLocation:(NSInteger)caretLocation;
/**
Returns a `NSPredicate` to define a fetch request for a specific context.
@param suggestionBar The suggestionBar that is displaying the contents.
@param context The currently relevant textsnipped that should be used in the predicate.
@param attributeName The name of the attribute that values are displayed of.
*/
- (NSPredicate *)suggestionBar:(TOMSSuggestionBar *)suggestionBar
predicateForContext:(NSString *)context
attributeName:(NSString *)attributeName;
/**
Returns a `NSArray` of `NSSortDescriptor` to specify the order in which fetched instances are displayed.
@param suggestionBar The suggestionBar that is displaying the contents.
@param attributeName The name of the attribute that values are displayed of.
*/
- (NSArray *)suggestionBar:(TOMSSuggestionBar *)suggestionBar
sortDescriptorsForAttributeName:(NSString *)attributeName;Exemplary implementation
An implementation of Delegate and DataSource could look like the following example.
The succeeding example of the delegate simply replaces the last word in the text field with the tapped suggestion.
The succeeding example of the dataSource works quite similar to the internals default configuration. It returns the last word of the input text as relevant context. The predicate for fetching attribute values is implemented as fuzzy matching.
- (void)viewDidLoad
{
[super viewDidLoad];
TOMSSuggestionBar *suggestionBar = [[TOMSSuggestionBar alloc] init];
[suggestionBar subscribeTextInputView:self.textField
toSuggestionsForAttributeNamed:@"name"
ofEntityNamed:@"Person"
inModelNamed:@"Model"];
suggestionBar.delegate = self;
suggestionBar.dataSource = self;
}
#pragma mark - TOMSSuggestionDelegate
- (void)suggestionBar:(TOMSSuggestionBar *)suggestionBar
didSelectSuggestion:(NSString *)suggestion
associatedObject:(NSManagedObject *)associatedObject
{
NSString *replacement = [suggestion stringByAppendingString:@" "];
self.textField.text = [self.textField.text stringByReplacingCharactersInRange:[suggestionBar rangeOfRelevantContext]
withString:replacement];
}
#pragma mark - TOMSSuggestionDataSource
- (NSString *)suggestionBar:(TOMSSuggestionBar *)suggestionBar
relevantContextForInput:(NSString *)textInput
caretLocation:(NSInteger)caretLocation
{
NSRange lastWordRange = [textInput rangeOfString:@" "
options:NSBackwardsSearch];
NSString *relevantContext;
if (lastWordRange.location == NSNotFound) {
relevantContext = textInput;
} else {
relevantContext = [textInput substringFromIndex:lastWordRange.location + 1];
}
return relevantContext;
}
- (NSPredicate *)suggestionBar:(TOMSSuggestionBar *)suggestionBar
predicateForContext:(NSString *)context
attributeName:(NSString *)attributeName
{
return [NSPredicate predicateWithFormat:@"%K LIKE[cd] %@", attributeName, [NSString stringWithFormat:@"*%@*", context]];
}
- (NSArray *)suggestionBar:(TOMSSuggestionBar *)suggestionBar sortDescriptorsForAttributeName:(NSString *)attributeName
{
return @[[NSSortDescriptor sortDescriptorWithKey:attributeName ascending:YES]];
}Author
License
TOMSSuggestionBar is available under the MIT license. See the LICENSE file for more info.