Function
$().SPServices.SPCascadeDropdowns
Functionality
The SPCascadeDropdowns function lets you set up cascading dropdowns on SharePoint forms. What this means is that you can enforce hierarchical relationships between column values. The function uses the GetListItems operation of the Lists Web Service to refresh the allowable values based on relationships which are maintained in reference lists. By implementing this function, you can remove all of the coding requirements to manage the hierarchical relationships (once it is in place) and let your users manage the content.
This function should work with any number of options in the dropdowns. It will not work with multi-select columns, though that enhancement is planned.
Note that "multiple cascades" are supported, such as Country -> Region -> State. In this example, we have two "cascades" in place: Country -> Region, and Region -> State. There's not a lot to show here, but the available options in the dropdowns will change based on the relationships defined in the lists shown below. So, if you choose
Country =
United States, the options for
Region will be limited to
Northeast, Southeast, Midwest, Mountain, Southwest, Northwest. If you choose
Country =
Canada, the options for
Region would be
Eastern Provinces, Western Provinces.
Demo Page
Take a look at our
demo page.
Prerequisites
- Relationship list contains at least two columns: relationshipListParentColumn and relationshipListChildColumn
- The dropdown for childColumn is a lookup into relationshipList's relationshipListChildColumn column
Countries List
Regions List
States List
Syntax
$().SPServices.SPCascadeDropdowns({
relationshipWebURL: "", // [Optional] The name of the Web (site) which contains the relationships list
relationshipList: "", // The name of the list which contains the parent/child relationships
relationshipListParentColumn: "", // The StaticName of the parent column in the relationship list
relationshipListChildColumn: "", // The StaticName of the child column in the relationship list
relationshipListSortColumn: "", // [Optional] If specified, sort the options in the dropdown by this column,
// otherwise the options are sorted by relationshipListChildColumn
parentColumn: "", // The DisplayName of the parent column in the form
childColumn: "", // The DisplayName of the child column in the form
debug: false // If true, show error messages; if false, run silent
});
By
StaticName above, we mean the underlying column name, e.g.,
Region_x0020_Name . The
DisplayName would be
Region Name, i.e., the name of the column which is shown on the form.
Setting
debug: true indicates that you would like to receive messages if anything obvious is wrong with the function call, like using a column name which doesn't exist. I call this
debug mode. As with all of the functions in the library, this function "runs silent", meaning that no messages or alerts are presented to the user if something goes wrong. This means that no inherent functionality is lost due to a problem. By using debug mode, you can receive messages to help you get things set up; I recommend turning debug mode off once everything is in place and running correctly.
Examples
This is the sum total of what you'll need to add to your page to make the function work for the example above. The first two lines simply pull the script files into the page, and the
$(document).ready(function() line is a jQuery function that says "Run this script when the page has been fully rendered". In the first call to the function, we're turning
debug mode on by setting
debug: true.
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery-1.3.2.js"></script>
<script language="javascript" type="text/javascript" src="../../jQuery%20Libraries/jquery.SPServices-0.4.5.min.js"></script>
<script language="javascript" type="text/javascript">
$(document).ready(function() {
$().SPServices.SPCascadeDropdowns({
relationshipList: "Regions",
relationshipListParentColumn: "Country",
relationshipListChildColumn: "Title",
parentColumn: "Country",
childColumn: "Region",
debug: true
});
$().SPServices.SPCascadeDropdowns({
relationshipList: "States",
relationshipListParentColumn: "Region",
relationshipListChildColumn: "State",
relationshipListSortColumn: "ID",
parentColumn: "Region",
childColumn: "State"
});
});
</script>