ben tedder : code things

SharePoint Sketches: SPServices Cascading Dropdowns

I've been finding design solace in my notebook lately, and I'm realizing this is turning into a mini-series on sketched-out, front-end development in SharePoint. So for this part of the series I'm covering SPServices Cascading Dropdowns.

Although cascading dropdown menus have been a feature of SPServices for ages, I have never taken the time to sit down and walk through how it all works. As I was using it on a recent project I decided I needed to draw out what I was reading in the Documentation to make sure I understood. So, here's how SPCascadeDropdowns plays out in my mind (descriptions below):

jQuery SPServices SPCascadeDropdowns

Description:

In this solution I've used SPServices Cascading Dropdowns to create a new "Student" list item. As well as storing the student's name, the create form allows me to select a division (Elementary School, Middle School, or High School), and then select a teacher who is part of that division using cascading dropdowns.

Setup:

Create 3 lists:

  • Divisions
    • Column 1 – Title (one list item for each division)

    <li>
      Teachers
    </li>
    <ul>
      <li>
        Column 1 &#8211; Title (for Teacher's name)
      </li>
      <li>
        Column 2 &#8211; Division (Lookup column from <strong>Divisions</strong> list)
      </li>
    </ul>
    
    <li>
      Students
    </li>
    <ul>
      <li>
        Column 1 &#8211; Title (for Student's name)
      </li>
      <li>
        Column 2 &#8211; Division (Lookup column from <strong>Divisions</strong> list)
      </li>
      <li>
        Column 3 &#8211; Teacher (Lookup column from <strong>Teachers</strong> list)
      </li>
    </ul>
    

Once you have your three lists, populate the first two (Divisions and Teachers) with your content.

Next, open up the NewForm.aspx (or EditForm.aspx) file for your list in SharePoint Designer. Look for the PlaceHolderAdditionalPageHead Content Placeholder. Put the following script inside that placeholder (assuming you've already loaded jQuery and SPServices elsewhere):

<script type="text/javascript">
$(document).ready(function(){
    $().SPServices.SPCascadeDropdowns({
        relationshipList: "Teachers",
        relationshipListParentColumn: "Division",
        relationshipListChildColumn: "Title",
        parentColumn: "Division",
        childColumn: "Teacher",
        debug: true
    })
})
</script>

Explanation of how script works

The trickiest part of SPservices and the SPCascadeDropdowns function is figuring out which columns to use where. So here's the breakdown:

relationshipList: This is the list in your setup that contains both of the columns you eventually want to use in the cascade (but not the target list where the cascading happens). In this case it is the "Teachers" list because it contains both of the columns we'll use.

relationshipListParentColumn: This is the "base" column from the relationshipList ("Teachers"), the one you will use to begin the cascading process. In this case it is "Division," because we first select a division, and then select a teacher.

relationshipListChildColumn: This is the column from the relationshipList ("Teachers") that comes after the base column has been selected. In this case it is "Title," NOT "Teacher," because remember we're looking at the relationship list.

ParentColumn: This is the column in your target list ("Students") (and therefore in the New and Edit forms) that will begin the cascade. In this case it is "Division," because as I mentioned earlier it is the column that we select first to obtain the cascaded list of teachers.

ChildColumn: This is the column in your target list ("Students") that will be altered based on what you choose in the ParentColumn. In this case it is "Teacher," because we want to receive a drop-down list of teachers once we select a division.

Once you stop and look at it, everything seems to make sense. But it can be slightly confusing when your source tables all have similar column names because they are lookup columns.

Hope this helps!