A jQuery Library for SharePoint Web Services (WSS 3.0 and MOSS): the SPDisplayRelatedInfo Function

Cross posted from EndUserSharePoint.com

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.

Example

Let’s take a look at a customized edit form (EditForm.aspx copied into EditFormCustom.aspx) for a SharePoint list. In this list, we’re capturing sales opportunities in my favorite demo list. In addition to everything else, we want to capture the System that the customer might want to buy.

Here’s what the form might look like. It’s pretty humdrum (though it does have SPCascadeDropdowns applied to it so that the Country -> Region -> State relationships are enforced, as well as SPLookupAddNew for easy addition of Regions).

clip_image002

If we use the SPDisplayRelatedInfo function, we can spiff up the form quite a bit. Now when we choose a System, we can display an image of it and a link to the Lead Sales Rep:

When the user makes a different selection, the System Image and Lead Sales Rep will change accordingly. Much nicer, IMHO. What you can display in this manner for each column in your list on the form is really only left to your imagination, based on the available column types. You might include a link to a User Manual, for example, or show a list of available inventory at each of your warehouse locations.

Prerequisites

This is one of the places where you’ll be glad if you’ve followed my previous advice to set up reference lists for things like Products, States, and Regions. In this case, I have a list called Systems, which has three columns:

clip_image006

The System column in my Sales Opportunities list is a Lookup column into the Title column of the System list. That gives us a nice, tight relationship between the System value in the Sales Opportunity and the Title of the Systems list.

Syntax

As with all of the functions in the jQuery Library for SharePoint Web Services, everything is put in place from the UI or SharePoint Designer. There’s nothing to install server-side. You simply need to add references to the core jQuery library and the jQuery Library for SharePoint Web Services and then call the function. See the documentation on the Codeplex site for more details on how to set things up.

SPDisplayRelatedInfo currently takes the following options:

$().SPServices.SPDisplayRelatedInfo({
  columnName: "",// The display name of the column in the form
  relatedWebURL: "", // [Optional] The name of the Web (site) which contains the related list
  relatedList: "", // The name of the list which contains the additional information
  relatedListColumn: "", // The internal name of the related 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
});

In the example above, the function call looks like this:

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

How Does It Work?

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!).

Conclusion

Quite a few of the early functions I’ve implemented in the library can help you make your forms more interactive and interesting to use. Having worked with data for as long as I have, I know all too well how the GIGO rules can bite you. (Garbage In, Garbage Out, in case you haven’t seen the acronym before.) By utilizing some of the functions like SPDisplayRelatedInfo, you can help your users do a better job adding data into SharePoint lists, and maybe even make it a little bit more fun.

Similar Posts

5 Comments

    1. Ashiena:

      Sorry; I hadn’t seen that question. There’s no way to set up alerts on individual Wiki pages, so you should use the Discussions in the future. I’ll copy it over to the Discussions and try to answer it for you.

      M.

  1. Hi Marc,
    How can I assign the value returned to a column?
    Example: I have a dropdown with categories (text) , but I need the ID to be stored in a column called CatID to use it later for filtering with URL parameters. Thanks

    1. Jose:

      SPDisplayRelatedInfo wraps everything in elements with easily identifiable ids (check the docs). You can add code to the completefunc to do something with what’s in those elements.

      M.

Leave a Reply to ashiena Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.