dinneo / acbtokenfield

A swift extension on NSTokenField which makes it highly customizable and removes a lot of boilerplate code from implementation

ACBTokenField

A swift extension on NSTokenField which makes it highly customizable and removes a lot of boilerplate code from its implementation.

Features

• Extension on NSTokenField, no need to subclass/or change anything in XIB/Storyboard
• Added few properties which makes it customizable such as shouldDisplayClearButton, shouldDisplaySearchIcon, leftView, shouldEnableTokenMenu etc..
• No need to implement delegate methods for simpler use cases. Just set an array of token names list or provide a default list of tokens for all indices. Rest will be handled by NSTokenField. See demo provided below(1 - 3).
• Supports NSTokenFieldDelegate as well with the customization. Just set tokenDelegate and implement the methods(see gif4) as usual.
• Added support for getting selectedTokenIndex so that tokens can be customized based on the index. tokenIndex provided in NSTokenFieldDelegate method has a bug and hence always returns zero. selectedTokenIndex will help in the meantime.
• Support for adding tokens
• Support for resetting tokens
• Support for delete token callback
• Support for getting actual token count
• Get tokenIndex based on the representedObject param in delegate methods.

Demo

Setup

Carthage, Cocoapods or Swift Package Manager can be used to integrate this to a project.

Carthage

github "akhilcb/ACBTokenField" ~> 2.3.0

Cocoapods

pod 'ACBTokenField', '~> 2.3.0'

Swift Package Manager

dependencies: [
    .Package(url: "https://github.com/akhilcb/ACBTokenField.git", majorVersion: 2)
]

Quick start

Inorder to implement this in a project just copy the files NSTokenField+ACBExtension.swift, ACBAssociation.swift, ACBToken.swiftand invoke the following function on any NSTokenField. As mentioned above, no need to subclass or change anything in XIB or Storyboard file

tokenField.convertToACBTokenField()

If you would like to have clear button and/or search icon in tokenfield, you can copy the icons ClearDarkGray and Glass from Assets.xcassets. Otherwise you can use your own images and set the properties clearIconName and searchIconName of NSTokenField. You are good to go.

Note: Cell class will be dynamically changed to ACBTokenFieldCell and delegate will be set. Please do not modify these properties. Use tokenDelegate instead of delegate.

Setup

There are additional features which you can make use of such as setting an Array of token names list which represents token list at each index of token field. You don't have to implement the NSTokenField delegate in this case. This will take care of displaying suggestions/displaying menu on tokens/editing tokens etc.

tokenField.tokenKeywordsList = [["France", "Germany", "Italy", "USA", "Spain", "India", "Brazil"],
                                ["Pizza", "Pasta", "Butter Chicken", "Jamon", "Cheesecake"],
                                ["Deer", "Dog", "Bear", "Panda", "Jaguar", "Bull"],
                                ["Car", "Truck", "Bus", "Motorcycle", "Minivan"]]

Set an array as shown above and it will show suggestions/menu based on the list above. Above list displays country names at index 0, food names at index 1, animal names at index 2 etc.. If you don't want to define token suggestions for each index separate like this, you can make use of below property to have default suggestions for all other indices except those present above.

tokenField.defaultTokenKeywords = ["Red", "Blue", "Green", "White", "Purple", "Black"]

This will show default suggestions and token menu for all other tokens in tokenField whose index is not specified in tokenKeywordsList.

You can also set leftView property of token field to any NSView or subclass of NSView. For eg:- you can add an NSButton as leftView and have an action to set to it(See gif5).

Setting properties

//set any required properties
tokenField.shouldEnableTokenMenu = true
tokenField.tokenDelegate = self
tokenField.leftView = lockButton

tokenField.didDeleteTokenBlock = { (tokenIndex, _) in
    print("Token at index = ", tokenIndex, "is removed")
}

Implement delegate

public func tokenField(_ tokenField: NSTokenField, completionsForSubstring substring: String, indexOfToken tokenIndex: Int, indexOfSelectedItem selectedIndex: UnsafeMutablePointer<Int>?) -> [Any]? {
    switch tokenIndex {
        case 0:
            return actors
        case 1:
            return actresses
        case 2:
            return movies
        case 3:
            return years
        default:
            return nil
    }
}

Screenshots

License

MIT License

Copyright (c) 2017, Akhil C Balan(https://github.com/akhilcb)

All rights reserved.