Visualforce Multiselect Drop-down Menu with jQuery Multiselect

Introduction

Building powerful user interactive  GUI (Graphical User Interfaces) requires letting your users have more control over the content they are consuming. This can be done by letting them filter the content to see only what they are interested it. Following my post on customizable drop-down Menus using jQuery Minimalect, I will show you today how to build even more powerful and more interactive drop-dowm menus that let users filter the content they are viewing by specify multiple options at once. This feature is called multi-select. For this article and demonstration I will use jQuery library or plugin call Multiselect.

When building Web applications that are heavy on user interaction, just be careful that the heavy user interaction isn't implemented at the expense of  performance, usability etc. Plan your application carefully before you begin implementing anything. Always remember, JUST BECAUSE YOU CAN DO IT, DOES NOT MEAN YOU SHOULD DO IT.

Use Case

As a use case, imagine you are building a custom Visualforce page which let's your Users browse Opportunities. Since Users in your organization work on opportunities at different stages, they might want to filter opportunities by stages. In this demonstration, we will create a multi-select drop-down Menu, which lets Users request only Opportunities they are interested in by specify the opportunity stages. Our end result looks like this.

So let's dive in.

Apex

Begin by using the Schema.DescribefieldResult to get and return a list of all stage names. This will be used on the page to build the multi-select drop-down. Use the Schema.DescribefieldResult  as opposed to hard coding your stages, so that you will not have to change your code, when the stages in your organization are customized.

1:  public List<String> opportunityStages {  
2:       get {  
3:            if(opportunityStages == null){  
4:                 opportunityStages = new List<String>();  
5:                 Schema.Describefieldresult stageNameField = Opportunity.StageName.getDescribe();  
6:                 List<Schema.Picklistentry> stages = stageNameField.getPickListValues();  
7:                 for(Schema.Picklistentry stage : stages){  
8:                      opportunityStages.add(stage.getValue());  
9:                 }  
10:            }  
11:            return opportunityStages;  
12:       }  
13:       private set;  
14:  }  

Visualforce

First start by downloading Multiselect  and adding the JavaScript and CSS to the page. Add them to the page as follows;

1:  <apex:stylesheet value="{!URLFOR($Resource.tutorials, '/css/jquery.multiselect.css')}" />  
2:  <apex:includeScript value="{!URLFOR($Resource.tutorials, '/js/jquery-1.9.1.js')}" />  
3:  <apex:includeScript value="{!URLFOR($Resource.tutorials, '/js/jquery.multiselect.js')}" />  

The look and feel of the examples here come from the default themes and styles. But you can apply you own themes and styles to suit the look and feel of your application.

Also note the version of jQuery I am using above. I am mentioning this here, because while preparing this article I initially used the latest version of jQuery which as of this writing is 1.11.1. But I couldn't get this to work together with the current version of Multiselect and had to downgrade my jQuery Version .1.9.1. So if you choose a different version of jQuery and run into an "Uncaught type error, undefined is not a function", then you might have to switch to a different version of jQuery.

Next build your drop-down as follows;

1:  <apex:outputPanel id="opportunityStageMultiSelectContainer">  
2:       <select id="opportunityMultiSelect" style="display:none" multiple="multiple">  
3:            <apex:repeat value="{!opportunityStages}" var="stage">  
4:                 <option value="{!stage}">{!stage}</option>  
5:            </apex:repeat>  
6:       </select>  
7:  </apex:outputPanel>  

The <apex:repeat> component is used to iterate over the list of stage names built in the Controller and an option is created for each stage name. The most important attribute here is the multiple attribute defined on the select element. This attribute is what makes multiple selection of options possible.

Créme de la Créme

And of course my favorite Créme de la Créme. Here we initialize the Multiselect plugin and specify options. These options define how the plugin will build our multiselect drop-down and how it will behave.

1:  $("#opportunityMultiSelect").multiselect({  
2:    selectedList: 3,  
3:    selectedText: "# of # selected",  
4:    noneSelectedText: "Opportunity Stages",  
5:    click: function(event, ui){  
6:            getSelectedStages();       
7:    },  
8:    checkAll: function(){  
9:            getSelectedStages();  
10:    },  
11:    uncheckAll:function(){  
12:            getSelectedStages();  
13:    }  
14:  });  

When the page is initially loaded and no options have been selected yet, the noneSelectedText is displayed. As options are selected, they are displayed until the number in selectedList is reached. After this the selectedText kicks in and says how many options have been selected so far;

SelectedText

Selected Options at the top

We have also defined what will happen when the user selects a single option, or all by clicking on Check all or none by clicking on Uncheck all. Although they all call the same function getSelectedStages() in our example, you could implement specific customized behavior here which suits your needs and the requirements you are working with.

1:  function getSelectedStages(){  
2:       var selected = $("#opportunityMultiSelect").multiselect("getChecked");  
3:       var stages = [];  
4:       $.each(selected, function(index, stage){  
5:            stages.push(stage.value);  
6:       });  
7:       passSelectedStagesToController(JSON.stringify(stages));  
8:  }  

In the getSelectedStages() method, we call the method getChecked() provided by the plugin to get all selected options. Please check out the documentation for all methods available and options you can set. For example, you can also use the options to set the text to be displayed in place of Check all  in this case All Opportunities

Finally we create an array, fill it with the selected stage names, create a JSON string and pass this to an actionFunction passSelectedStagesToController;

1:  <apex:actionFunction name="passSelectedStagesToController" action="{!retrieveOpportunitiesForSelectedStages}" rerender="hiddenDiv">               
2:       <apex:param assignTo="{!selectedStages}" name="selectedStages" value=""/>  
3:  </apex:actionFunction>  

The JSON String with the stage names is assigned to a String property on the Controller selectedStages. Notice that we have a rerender attibute on the actionFunction. You will normally rerender the portion of the display which is showing your results. Here the rerender attibute also plays a very important role. Without this attribute, the selectedStages parameter will not be set. As of this writing, I am guessing that this is a Salesforce Bug. A little googling has revealed that quite a few people have this problem as well. Also specifying the onComplete attribute on the actionFunction component will also cause the selectedStages parameter to be set. Very spooky stuff.

On the controller, in the action method specified in the actionFunction, you can then collect the stage names into a Set.

1:  public void retrieveOpportunitiesForSelectedStages(){  
2:       Set<String> stages = (Set<String>)JSON.deserialize(this.selectedStages, Set<String>.class);  
3:  }  

This set could then be used in your the WHERE condition of your SOQL query using the IN keyword. I will leave this up to you. But in this way you will be able to retrieve and pass only those Opportunities belonging to a particular stage back to the page.

Conclusion

I hope that from this article you were able to get a feeling of the end-to-end process of implementing the multi-select feature using, Apex, Visualforce and jQuery's Multiselect plugin. I hope that you are now able to appreciate the possibilities you have from using this. Challenge this article and propose alternative solutions and as any open questions you may have. Hope you enjoyed reading