Function

$().SPServices.SPDisplayRelatedInfo

Certification

Certified for SharePoint 2007 Certified for SharePoint 2010

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.

How Does It Work?

The SPDisplayRelatedInfo function 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 in a DIV which is inserted into the form. The DIV is named "SPDisplayRelatedInfo_" + columnStaticName in case you need to do any post-processing.


NOTE: This function is only meant to be used on the NewForm or EditForm; it works when a dropdown's value is changed. If you'd like to do something similar on a DispForm, I'd recommend using a Data View Web Part (DVWP) with an AggregateDataSource.

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: "",
relatedWebURL: "",
relatedList: "",
relatedListColumn: "",
relatedColumns: [],
displayFormat: "table",
headerCSSClass: "ms-vh2",
rowCSSClass: "ms-vb",
numChars: 0,
matchType: "Eq",
CAMLQuery: "",
  matchOnId: false,     // Added in v0.7.1
completefunc: null,
debug: true
});

columnName
The DisplayName of the column in the form

relatedWebURL
The URL of the Web (site) which contains the relatedList. If not specified, the current site is used. Examples would be: "/", "/Accounting", "/Departments/HR", etc. Note: It's always best to use relative URLs.

relatedList
The name or GUID of the list which contains the related information. 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 relatedWebURL if the list is in another site.

relatedListColumn
The StaticName of the column in the related list

relatedColumns
An array of StaticNames of related columns to display

displayFormat
The format to use in displaying the related information. The default is "table". 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


headerCSSClass
If specified, the CSS class for the table headers. The default is "ms-vh2".

rowCSSClass
If specified, the CSS class for the table cells. The default is "ms-vb".

numChars
If used on an input column (not a dropdown), no matching will occur until at least this number of characters has been entered. The default is 0.

matchType
If used on an input column (not a dropdown), type of match. Can be any valid CAML comparison operator, most often "Eq" or "BeginsWith". The default is "Eq".

CAMLQuery
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. Bacause it is combined with the CAML required to make the function work, CAMLQuery here should contain a CAML fragment such as:

CAMLQuery: "<Eq><FieldRef Name='Status'/><Value Type='Text'>Active</Value></Eq>"

matchOnId
By default, we match on the lookup's text value. If matchOnId is true, we'll match on the lookup id instead. The default value is false.

completefunc
If specified, the completefunc will be called each time there is a change to columnName. 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

debug
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

$().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.



In this example, I'm displaying some information about the Region. To make the output look better, I'm doing a little post-processing on the Total_x0020_Sales column. You’ll see that I’m both prepending the value with “$” and right justifying it. In my case, the column is Region and the Total_x0020_Sales column is the 4th one, so I’m using :nth-child(4).

$().SPServices.SPDisplayRelatedInfo({       
               columnName: "Region", 
               relatedWebURL: "/Intranet/JQueryLib",
               relatedList: "Regions",
               relatedListColumn: "Title",
               relatedColumns: ["ID", "Country", "Title", "Total_x0020_Sales"],
               displayFormat: "table", 
               completefunc: addDollarSigns,
               debug: true
});

 

function addDollarSigns() {
               $("#SPDisplayRelatedInfo_Region td:nth-child(4)").prepend("$").css("textAlign", "right");
}

Last edited Dec 17, 2013 at 10:01 PM by sympmarc, version 38

Comments

Toby_1 Mar 9 at 11:46 AM 
Anyone ever get this to work within Nintex Forms? I keep getting "Unable to get property 'length' of undefined or null reference". It does it when trying to read the list that I'm pointing to

stevefeldman Nov 19, 2013 at 1:47 PM 
This technique is very useful for adding and updating. Can the call be attached to something else so the related info appears in a display form?

Steve

jeszy May 17, 2013 at 2:46 AM 
Works like a wonder!!!

I am having a problem with the related info being displayed in the Drop Off Library (Records Center). Is the code expected to work where there are multiple Content Types to select from? The columnName is unique to each Content Type but it does not seem to be working. Any idea?

Thank you =)

scvinod Dec 7, 2012 at 2:03 AM 
HI Marc,
Nice method. My requirement is to implement this in the Display form rather than a new form or edit form. Is it possible?

KJGlynn Oct 23, 2012 at 2:00 PM 
Can I just check that this will work where the colName is a lookup column in another list? I've put this into my New Form but absolutely nothing happens. I've tried to get it to throw errors no matter where I put the code on the page and no additional information is displayed. I'm thinking that as the column is already a lookup, the event handler isn't being triggered. Is that right?

ribrem Jun 8, 2012 at 2:21 PM 
just a quick question I hope. Is it possible to "bring over" the related fields but hide them? I would like to be able to use the related field values to default a couple of the form fields if the related field values are not blank but I don't want to display the related fields. Thanks!

jderoubaix May 21, 2012 at 8:33 AM 
Thanks a lot for your library !
Work very well on dropdown list, but I have an issue with the input field :
Nothing appears when I used an input field... Any idea ?

remo1114 Feb 14, 2012 at 3:27 AM 
Hi
Related to previous comment:

$().SPServices.SPDisplayRelatedInfo({
columnName: "Col4",
relatedList: "ListB name",
relatedListColumn: "Title",
relatedColumns: ["Description"],
displayFormat: "table",
debug: true


I got this working, but I want this as editable text( so that user can add/edit the terms as per requirement) and should be saved in List A when saved, but shouldn't update in List B when saved.

Thanks

remo1114 Feb 14, 2012 at 1:19 AM 
Hi
I am working on some cascading stuff, bit related to this thread. Please help me out.
I have few columns in List A: col1, col2, col3, col4 and col5
In List B: only 2 columns

Title(single line of Text) Description(multiple line of Text)
------ ---------
Term1 Terms and conditions text.........................
Term2 Terms and Conditions Text.......................

ListA:
Col4 -->lookup column ( Get Information from: ListB ; Title)

NewForm//
So whenever user select something(ex: Term1) in ddl in listA then the Text( ListB: Description) should display ListA - and text should be editable, save in ListA but not update in List B if edited .

My Script:

<script type="text/javascript" src="/testsite/SiteAssets/jquery-1.7.1.min.js"></script>
<script language="javascript" type="text/javascript" src="/testsite/SiteAssets/jquery.SPServices-0.7.1.js"></script>
<script language="javascript" type="text/javascript" src="/testsite/SiteAssets/jquery.SPServices-0.7.1.min.js"></script>
<script language="javascript" type="text/javascript">

$(document).ready(function() {

$().SPServices.SPDisplayRelatedInfo({
columnName: "Col4",
//relatedWebURL: "",
relatedList: "ListB",
relatedListColumn: "Title",
relatedColumns: "Description",
displayFormat: "table",
//headerCSSClass: "ms-vh2",
//rowCSSClass: "ms-vb",
//numChars: 0,
//matchType: "Eq",
//CAMLQuery: "<Eq><FieldRef Name='Description'/><Value Type='Text'>Active</Value></Eq>",
//matchOnId: true, // Added in v0.7.1
//completefunc: addDollarSigns,
debug: true
});

});

</script>

Pleas help me out.
Appreciate any ideas.

dchillman Sep 14, 2011 at 9:04 PM 
I've googled without luck, so thought I would post here. I was trying to create a cascaded lookup on a "NewItem" form, but the field I wanted to populate the lookup with is a multiline text field (lets call it QuestionText), which apparently isn't allowed. Associated with the QuestionText field is a QuestionID field. I was thinking I could use the QuestionId field in the cascaded lookup, then use this SPDisplayRelatedInfo to get the associated QuestionText value, and used it as the default value for another field on the form. However, I am also wondering if it is possible to add a dynamic tooltip to the cascaded lookup that uses the SPDisplayRelatedInfo as its source, so each value in the lookup (QuestionID) has its related QuestionText as the tooltip? Any hints to get me started would be appreciated. thanks

cvgandhi Jun 16, 2010 at 8:04 PM 
Appreciate it so much...
It is even more Useful by using it for post-processing.
Thanks mate.

loomy79 May 31, 2010 at 9:27 AM 
Congratulations!!
Method Rocks !!

AdrienM May 14, 2010 at 12:25 PM 
Very nice method!