Ember Multiselect Checkbox Plugin

Because, in my experience, nothing has been easy with Ember.js

For my final project at the Flatiron School Attention to detail and I created an app to assist someone in creating a dynamic balance sheet for group trips like ski trips or bachelor parties. Our goal was a 1 page application in which you could handle all of your expenses by adding attendees, grouping them up, and creating expenses that have both a financier (an attendee) and several beneficiaries (the groups). You can see it live here.

Some of the actions we wanted to be available were to be able to add and edit attendees when creating or editing a group and to add groups when creating an attendee. For both of these create actions and this one edit action we needed a multi-select checkbox. Since I had only been learning Ember.js for about 8 days when we started putting this project together I was surprised to find many core functionalities that I am used to using in Ruby and Rails were completely unavailable in Ember. So I went out and found a plugin to handle exactly what we were looking for. Enter ember multi-select-checkbox plugin.

The link to the plugin is here. I will go over some of the things covered in the documentation that I found confusing until I was working with the plugin for several hours.

Installation

You can install this very easily with NPM:

npm install ember-multiselect-checkboxes

Run npm install && bower install in your terminal to make sure it is all properly setup after you have installed the plugin.

Use

For our project we used this plugin 2 different ways and by doing so I was able to get a pretty complete understanding of what all of the options are and how they affect what displays on the page.

The first example comes from the edit-groups component:

{{multiselect-checkboxes options=model.attendees selection=grp.attendees onchange=(action ‘updateSelection’) labelProperty=’name’}}

Here we are exposed to 4 of the properties that we can use to control what is displayed and how.

First there is options. This is the array of items we want to iterate over. For us, model is the current event/gathering that is being viewed. So here we are passing in all of that gathering’s attendees.

Next, is selection. This is the sub-section of the options that you want to be displayed as checked by default. If you wanted everything to be defaulted as checked then you can pass in the same variable that you passed into options. Since I wanted to display the attendees in the group as part of that group when you make an edit I specifically passed in just the group-we-are-editing’s attendees as a selection. In some cases (like the default group) it will show them all as pre-selected, but that is totally up to how you set it up.

Next, is onChange. This is the name of the action that gets called anytime someone checks or un-checks a checkbox. You define this action in the .js file of the same name as your component’s .hbs file. (For me the component is named edit-groups.hbs and this action is defined in edit-groups.js.) Here I would actually make the changes to the group, adding and removing attendees as a user checks and un-checks options.

Finally, there is labelProperty. This is what gets displayed next to the checkbox. Our attendees model had an attribute of name. So the checkboxes display the name next to them.

labelProperty ties in to a property I never used pretty closely, called valueProperty. valueProperty is what actually gets passed into the onChange action. If I had set this to name then I would only pass in the name of each attendee. By leaving this property out I was able to pass the entire Object into the action.

The second example comes from our add-attendees component:

{{#multiselect-checkboxes options=groups selection=selectedGroups onchange=(action ‘updateSelection’) class=”checkbox” as |group isSelected|}}
 <li class=”checkbox”><label>{{input type=’checkbox’ checked=isSelected}}<b>{{group.name}}</b></label></li>
{{/multiselect-checkboxes}}

Here, we didn’t need labelProperty since we defined what we wanted to display ourselves between the handlebar helper tags. In this case it’s the group’s name. options, selection, and onChange function in the exact same way as in the above example with a single caveat. onChange now needs to be told what to watch in order to see that a checkbox has been selected. I passed it into the iteration as isSelected. Then on the individual list elements, in the input helper, you have to define the checked as equal to isSelected. Now anytime a box is changed it is passed into the onChange action the same way it is above.

Also, by setting up our helper with an opening and a closing we are able to define exactly how we want the HTML elements to appear inside the list. You can also change how the list is wrapped. By default it is an unordered list with list elements and labels inside. By using tagName, you can change the wrapped from a <ul> tag to a <div> tag or any other tag.

The only 2 parts I did not cover completely were the properties that turn off the onChange action and the details of what the onChange action actually looks like. If you are interested in the more specific details for those I think the documentation does a good enough job to explain them both.

Conclusion

Ember is hard to learn. Plugins make it a little more friendly.

Like what you read? Give Robert Hopkins a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.