Thursday, March 3, 2016

Add Cascading Drop-downs To Any SharePoint List or Library

Here is everything you need to add to five cascading drop-down fields to any SharePoint list or library. This can be accomplished in under 30 minutes.

Turn this...
      
Into this...
     

High-level Steps:

  1. If you don't already have one, create a list that stores all the allowed combinations for the cascading drop-downs (one column for each level of drop-down). I will refer to this list as the Source Options list.
  2. Add 2-5 single line of text columns to the list or library that will hold the values from the cascading drop-down fields. I will refer to this list/library as the Cascading Drop-down list.
  3. Modify and upload the JS Link file (supplied below) to a shared library in the same site collection as the Cascading Drop-down list and Source Options list.
  4. Download the compressed, production JQuery file and upload it to the same shared library as the JS Link file.
  5. Modify the New and Edit form web parts for the Cascading Drop-down list by entering a URL into it's JS Link property.

Assumptions:

  • All the lists and JavaScript files reside in the same site collection

Step 1: The Source Options list

This list can be any SharePoint list or external BCS list in the same site collection as the list that will display these choices as cascading drop-downs.  The column names can be whatever you choose so long as you know (or can figure out) what their internal names are. In the example table below, the levels correspond to Continent, Country, State, and City.  You can download this list template if you don't want to create your own from scratch.  If you only need two cascading drop-downs you can ignore Levels 3 and 4.
Level 1
Level 2
Level 3
Level 4
North America
United States
MD
Germantown
North America        
United States        
MD        
Rockville
North America        
United States        
MD        
Silver Spring
North America        
United States        
VA        
Manassas
North America        
United States        
VA        
Arlington
South America        
Argentina        
Buenos Aires        
Buenos Aires
Central America        
Costa Rica        
San Jose        
San Jose
North America        
Mexico        
Chihuahua        
Chihuahua
North America        
Mexico        
Juarez        
Juarez

Step 2: The Cascading Drop-down list/library

This is the list or library that has 2-4 columns which need to be presented as cascading drop-downs. If your list or library doesn't have these columns already just add them (single line of text). I highly recommend creating them with initial names that do not include spaces or special characters. You can rename them later and add the spaces or special characters back in.

Step 3: The JS Link file

Here is where we get into the meat and potatoes of this solution. Download the CascadingDropDowns.js file (what I'm calling the JS Link file) and modify the variables in the first 34 lines to configure it to match your Source Options list and the Cascading Drop-down list/library. These lines are commented pretty well already but I'll summarize here.
  • restUrl variable: enter the display name of the Source Options list into the URL that is provided inside the GetByTitle parenthesis. Be sure to include the single quotes around it. For example:
    • /_api/web/lists/GetByTitle('My Source Options List')/items
  • LevelNInternalName variables: set these to the internal names of each corresponding Cascading Drop-down list/library column. Levels 3 and 4 can be set to an empty string (two double quotes) if they aren't needed. For example:
    • var Level1InternalName = "Continent";
  • LevelNSource variables: set these to the internal name of the corresponding column in the Source Options list. Levels 3 and 4 can be set to an empty string (two double quotes) if they aren't needed. For example:
    • var Level1Source = "Level1";
  • cascadingFieldContext.Templates.Fields JSON definition: each first level item needs to match the corresponding LevelNInternalName variable. Do not change "NewForm", "EditForm" or any of the renderLevelNField entries.

Once you have modified those lines, upload this file to a shared library in your site collection such as the Site Assets library.

Step 4: The JQuery file

This solution's JS Link file relies on JQuery and in order for JQuery to be loaded properly it needs to be available somewhere in your site collection. If you don't already have this stored somewhere in your site collection I recommend putting it in the same shared library as the JS Link file. You can download JQuery here.  The JS Link file was built using version 2.2.1.

Step 5: Wire up the JS Link file

If the cascading drop-down is to be used in a library then we only need to do the following on the Edit Properties page. For lists however, the following needs to be done on both the New and Edit Properties pages.
  1. Browse to the Edit Properties page
    1. You will need to create an item in the Cascading Drop-down list or upload a document to the  Cascading Drop-down library if one does not already exist.
    2. Check the box next to the item/document and then click Edit Properties from the Items or Files ribbon menu.                                                                          
  2. Browse to the list and click the New Item button at the top to display the New form.
  3. Once on the Edit Properties or New form properties page, click the Settings Gear icon at the top right of the page and click the Edit Page option.
  4. Click the drop-down arrow at the top right of the form web part and click the Edit Web Part option.                                                                                 
  5. Collapse the Appearance web part properties section and expand the Miscellaneous section
  6. Enter the following into the JS Link property assuming you put the JQuery and JS Link files
    1. ~sitecollection/SiteAssets/jquery-2.2.1.min.js|~sitecollection/SiteAssets/CascadingDropDowns.js
  7. Click the Ok button on the Web Part Properties panel.
  8. Click the Stop Editing button on the Page ribbon menu.

Conclusion

That's it! Now anyone entering a new item, uploading a new document into your list/library or editing the item or document's properties will have the cascading drop-down functionality. Don't forget to enter all the allowed options in your Source Options list.