Author: David Wylie

The TokenBox component provided by this library can be filled with tokens, each with its own text.

Clicking the tokens removes them from the TokenBox.

There’s also a MultiSelectDropDown component that combines a TokenBox with a DropDown.

When items from the DropDown are selected, they go into the TokenBox.

To set the list of items in the DropDown, set the items property of the MultiSelectDropDown component, either in the Properties panel or programmatically.

There’s a unique property that flags whether the items can be selected more than once.

If unique is True, items are removed from the DropDown when they’re put into the TokenBox, and put back into the DropDown when they’re removed from the TokenBox.

The MultiSelectDropDown also has a placeholder property. The DropDown starts with this as the selected_value. After values are selected, the DropDown’s selected_value goes back to being placeholder. By default, it’s ‘Select a value’.

Clone it and use it

It’s completely free to use, so click on the clone link and use it in your app!

You can use it from another app by using the App Dependencies dialog.

When you clone the library, you will also get an example app that shows you how to include it and make use of it.

How the TokenBox works

The TokenBox is very simple - it’s a Flow Panel with methods for adding and removing tokens (inventively named add and remove). Tokens are simply Buttons with the appropriate text and an ‘x’ (fa:times) icon to show that clicking them deletes them.

The add method instantiates the Button, sets its click handler to be the remove method, and adds it to the Flow Panel.

The remove method just calls remove_from_parent on the Button that was clicked.

The TokenBox also has add_callback and remove_callback properties. Assign a function to these, and it will be run at the end of the add method, or the beginning of the remove method. That’s how the MultiSelectDropDown knows when tokens have been removed and can add them back to its items list. The callbacks are passed the Button instance as an argument.

How the MultiSelectDropDown works

The MultiSelectDropDown consists of a TokenBox and a DropDown. When something is selected from the DropDown, its change event triggers. There’s a change event handler that adds the value of the selected item to the TokenBox. At the end of the change handler the selected_value gets set back to self.placeholder, to allow the user to select the same value again.

The add_to_dropdown and remove_from_dropdown methods add and remove items from the DropDown’s list of items.

When the unique property is True, adding items to the TokenBox removes them from the DropDown, and removing items from the TokenBox adds them to the DropDown. This is implemented by using add_to_dropdown and remove_from_dropdown as the as the add_callback and remove_callback of the TokenBox.