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, there are no coding requirements to manage the hierarchical relationships (once it is in place) and you can let your users manage the content in the reference lists.
This function works with any number of options in the dropdowns as well as multi-select parent and child columns, as shown in the following table. This is significant because each of the three column types are rendered significantly differently by SharePoint.
| | | parentColumn |
|---|
| | | <20 options | 20+ options | multi-select |
|---|
| childColumn | <20 options |  | | |
|---|
| | 20+ options | | | |
|---|
| | multi-select | | | |
|---|
When the relationshipList contains lookup columns for both the relationshipListParentColumn and relationshipListChildColumn columns, the function uses the relationshipListParentColumn's ID rather than the relationshipList item's ID. This means that "secondary lists" are also supported.
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 OR a list column which is a lookup into another list column ("secondary list").
Countries List
Regions List
States List
Syntax
$().SPServices.SPCascadeDropdowns({
relationshipWebURL: "",
relationshipList: "",
relationshipListParentColumn: "",
relationshipListChildColumn: "",
relationshipListSortColumn: "",
parentColumn: "",
childColumn: "",
CAMLQuery: "",
promptText: "Choose {0}...",
completefunc: null,
debug: false
});
The URL of the Web (site) which contains the relationshipList. If not specified, the current site is used. Examples would be: "/", "/Accounting", "/Departments/HR", etc. Note: It's always best to use relative URLs.
relationshipListThe name or GUID of the list which contains the parent/child relationships. If you choose to use the GUID, it should look like: "{E73FEA09-CF8F-4B30-88C7-6FA996EE1706}". Note also that if you use the GUID, you do not need to specify the
relationshipWebURL if the list is in another site.
relationshipListParentColumnThe
StaticName of the parent column in the relationship list
relationshipListChildColumnThe
StaticName of the child column in the relationship list
relationshipListSortColumnIf specified, sort the options in the dropdown by this column otherwise the options are sorted by
relationshipListChildColumnparentColumnThe
DisplayName of the parent column in the form
childColumnThe
DisplayName of the child column in the form
promptTextText to use as prompt. If included, {0} will be replaced with the value of childColumn. The default value is
"Choose {0}...".
completefuncIf specified, the completefunc will be called each time there is a change to parentColumn. Potential uses for the completefunc: consistent default formatting overrides, additional lookup customizations, image manipulations, etc. You can pass your completefunc in either of these two ways:
completefunc: function() {
...do something...
},
or
completefunc: doSomething, // Where doSomething is the name of your function
The CAMLQuery option allows you to specify an additional filter on the relationshipList. The additional filter will be <And>ed with the existing CAML which is checking for matching items based on the parentColumn selection. CAMLQuery should contain a CAML fragment such as:
CAMLQuery: "<Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq>"
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.
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, note that 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>