jQuery Library for SharePoint Web Services

Function

$().SPServices.SPDisplayRelatedInfo

Functionality

SPDisplayRelatedInfo is a function in the jQuery Library for SharePoint Web Services that lets you display information which is related to the selection in a dropdown. This can really bring your forms to life for users: rather than just selecting bland text values, you can show them images and links that are related to their choices.

The SPDisplayRelatedInfo works like this:

• When the function is first called, it attaches an event handler to the dropdown control. The logic here varies a bit depending on what type of dropdown it is.
• When the selected option in the dropdown changes, SPDisplayRelatedInfo calls two Lists Web Service operations:
  • GetList on the relatedList to get information about its columns (fields)
  • GetListItems to get the items where the specified column’s value matches the current selection. Note that there can be multiple items returned; generally displayFormat: “table” makes more sense if you’ll want to display multiple items.
• For each column it’s asked to display, SPDisplayRelatedInfo calls a private function (showColumn) to render the column value based on its type. Most of the normal column types are covered, though locale conversions can’t be done from the client side (yet!). The related information is shown directly below the dropdown in a DIV which is inserted into the form on setup.

Tip: If you don't want to see the column headers, pass in ms-hidden for headerCSSClass. (This is a CSS class in core.css which sets display: none.)

Prerequisites

• You'll need to have a list (relatedList) which contains the values in the dropdown in one column and the related values you'd like to display in additional columns. If you're already using SPCascadeDropdowns, then you'll already have a list (or lists) in place which you can use here.

Here is an example of the form where you want to use SPDisplayRelatedInfo:

In this example, I have a list called Systems, which has three columns:

Syntax

$().SPServices.SPDisplayRelatedInfo({	
	columnName: "",		// The DisplayName of the column in the form
	relatedWebURL: "",		// [Optional] The name of the Web (site) which contains the relationships list
	relatedList: "",		// The name of the list which contains the related information
	relatedListColumn: "",	// The StaticName of the column in the related list
	relatedColumns: [],	// An array of internal names of related columns to display
	displayFormat: "table",	// [Optional] The format to use in displaying the related information.  Possible values are: "table", "list".
	headerCSSClass: "ms-vh2",	// [Optional] CSS class for the table headers
	rowCSSClass: "ms-vb",	// [Optional] CSS class for the table rows
	debug: true		// [Optional] 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.

Example

$().SPServices.SPDisplayRelatedInfo({
	columnName: "System",
	relatedList: "Systems",
	relatedListColumn: "Title",
	relatedColumns: ["System_x0020_Image", "Lead_x0020_Sales_x0020_Rep"],
	displayFormat: "list"
});

So I’m asking SPDisplayRelatedInfo to show me the values in the System_x0020_Image and Lead_x0020_Sales_x0020_Rep columns (these are the StaticNames of the list columns as opposed to the DisplayNames) in the Systems list under the System column in my form using the list display format where the System value matches the Title value in the Systems list. I’m just taking the default CSS classes for the example. As you can see, you can pass in any CSS class you’d like to make the SPDisplayRelatedInfo output match your site branding.

The displayFormat takes one of two options:

• “table” displays the matching items much like a standard List View Web Part would, in a table with column headers
• “list” also uses a table, but displays the item(s) in a vertical orientation, like in the example