SharePoint, Data View web parts and functions in the ddwrt namespace

THIS BLOG POST TURNED INTO AN MSDN ARTICLE. SEE http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odc_SP2003_ta/html/OfficeSharePointDDWRT.asp FOR THIS ARTICLE. BUT… ALSO CHECK THIS BLOG POST, IT CONTAINS SOME INFO CENSORED IN THE ARTICLE;-)

Summary

Topic: Data View web part, XSLT, XSLT Extension Object, ddwrt namespace, Windows SharePoint Services, SharePoint Portal Server 2003, FrontPage 2003

SharePoint has a powerful type of web parts: Data View web part (DVWP) that has the ability to provide an XSLT transformation on XML data retrieved from a data source. FrontPage 2003 has great support for defining the data source to retrieve XML data from, for WYSIWYG creating of XSLT views on this data, and for converting CAML list views (WSS list views) to XSLT.

In the XSLT generated by FrontPage an XSLT Extension Object is used to provide functions in the ddwrt namespace to perform often needed functionality like accessing properties of a list or firing events to connected web parts. This article tries to shed some light on these undocumented but much used functions.

Introduction

This is an article I started exactly one year ago, but never finished. I was using one of the most powerful features you get when using FrontPage in combination with Windows SharePoint Services (WSS) and Microsoft Office SharePoint Portal Server 2003 (SPS): the ability to create Data View web parts (DVWP). It is one year later, Christmas again, and in the meantime not much information appeared on the subject of this article: the functions available in the ddwrt namespace as used in the FrontPage generated Data View XSLT code.

Many introductory articles have already been written on the topic of DVWPs, so I will not repeat all this useful information. I consider those articles as prerequisite reading and will try to go from there by showing the available functions, and what they do.

Disclaimer: I’m on vacation and only have access to Reflector, the Microsoft.SharePoint.dll and Word, so no possibility to check out things. I have to rely on my notes taken in the past, and the disassembled code using Reflector. If you find any untruthful information or if you have any additional information: let me know and I will correct/include it in this article.

 FrontPage and DVWPs

One of the first things to mention is that although FrontPage is a great tool to create a DVWP, all the logic is already available in SharePoint (WSS) itself (see also http://weblogs.asp.net/soever/archive/2004/05/14/131698.aspx). This logic consists of the following parts:

• Microsoft.SharePoint.WebPartPages.DataViewWebPart, a class available in the Microsoft.SharePoint.dll assembly that implements the DVWP functionality.
• Microsoft.SharePoint.WebPartPages.DdwRuntime, an internal class available in the Microsoft.SharePoint.dll assembly that is made available as a XSLT Extension Object that provides a set of functions in the ddwrt namespace. The set of functions this article is about!!
• Data view web part definition, a .dwp file describing the assembly implementing the web part and the configuration parameters for the web part.

It is possible to create data DVWPs without using FrontPage. It is difficult, but it is possible. A DVWP is just a .dwp file which is an XML file that contains information for the data query and the XSLT transformation.

One thing FrontPage does really good is the conversion of a SharePoint list view (defined in Collaborative Aplication Markup Language, or CAML for short) to an XSLT transformation that transforms the data retrieved using the list web service to the same view as defined in CAML. In the past I wrote a weblog entry (http://weblogs.asp.net/soever/archive/2004/03/10/87295.aspx) about how FrontPage accomplishes this wizardry using an XSLT transformation that is available in your office directory.

Besides the CAML transformation, FrontPage provides WYSIWYG functionality to create a nice view on data. It does this by interactively defining an XSLT transformation on XML data retrieved from multiple types of data sources.

DataViewWebPart, Vars and the ddwrt namespace

It is the Data View web part implemented in the class Microsoft.SharePoint.WebPartPages.DataViewWebPart that utilizes the internal class Microsoft.SharePoint.WebPartPages.DdwRuntime to provide utility functions. John Janssen stated in a usenet discussion: “They were created to maintain parity between data views and list views (so that in the convert case the data view behaves just the same as the list view).” But the problem is that we want to give our own twist to how the result works, otherwise we didn’t have to convert them in the first place! The utility functions are made available by creating an XSLT Extension Object. To take a peek in the kitchen have a look at the obfuscated function Microsoft.SharePoint.WebPartPages.DataViewWebPart.q(). In this functions three important things happen:

1. The DdwRuntime class is added as an Extension Object
2. The Vars name-value collection as available in the XSLT transformation through ddwrt:Vars[“name”], filled with all kind of interesting information
3. A large set of XSLT parameters is defined.

The powerful thing of the Vars collection is that this collection is persisted over page request in the ASP.NET viewstate, so it can be used to persist information from the XSLT transformation of the current page request to the XSLT transformation of the next page request.

The Vars name-value pairs that I could find:

XSLT parameters I could find (no namespace):

If you look at the XSLT code generated by FrontPage you will find a large set of additional XSLT parameters. To have a look at the values of a lot of these parameters you could include the following XSLT code that writes out their values to the HTML code generated for the DVWP:

<!-- Dump parameters -->

PageUrl: <xsl:value-of select="$PageUrl"/><br/>

HttpHost: <xsl:value-of select="$HttpHost"/><br/>

List: <xsl:value-of select="$List"/><br/>

URL_Display: <xsl:value-of select="$URL_Display"/><br/>

HttpVDir: <xsl:value-of select="$HttpVDir"/><br/>

View: <xsl:value-of select="$View"/><br/>

FilterLink: <xsl:value-of select="$FilterLink"/><br/>

Language: <xsl:value-of select="$Language"/><br/>

dvt_adhocmode: <xsl:value-of select="$dvt_adhocmode"/><br/>

dvt_adhocfiltermode: <xsl:value-of select="$dvt_adhocfiltermode"/><br/>

dvt_fieldsort: <xsl:value-of select="$dvt_fieldsort"/><br/>

dvt_sortfield: <xsl:value-of select="$dvt_sortfield"/><br/>

dvt_groupfield: <xsl:value-of select="$dvt_groupfield"/><br/>

dvt_groupdisplay: <xsl:value-of select="$dvt_groupdisplay"/><br/>

dvt_sortdir: <xsl:value-of select="$dvt_sortdir"/><br/>

dvt_groupdir: <xsl:value-of select="$dvt_groupdir"/><br/>

dvt_filterfield: <xsl:value-of select="$dvt_filterfield"/><br/>

dvt_filterval: <xsl:value-of select="$dvt_filterval"/><br/>

dvt_filtertype: <xsl:value-of select="$dvt_filtertype"/><br/>

dvt_firstrow: <xsl:value-of select="$dvt_firstrow"/><br/>

dvt_p2plinkfields: <xsl:value-of select="$dvt_p2plinkfields"/><br/>

dvt_nextpagedata: <xsl:value-of select="$dvt_nextpagedata"/><br/>

dvt_grouptype: <xsl:value-of select="$dvt_grouptype"/><br/>

dvt_sorttype: <xsl:value-of select="$dvt_sorttype"/><br/>

dvt_groupsorttype: <xsl:value-of select="$dvt_groupsorttype"/><br/>

dvt_apos: <xsl:value-of select="$dvt_apos"/><br/>

filterParam: <xsl:value-of select="$filterParam"/><br/>

ImagesPath: <xsl:value-of select="$ImagesPath"/><br/>

ListUrlDir: <xsl:value-of select="$ListUrlDir"/><br/>

EMail: <xsl:value-of select="$EMail"/><br/>

ListUrlDir_TRUE: <xsl:value-of select="$ListUrlDir_TRUE"/><br/>

URL_DISPLAY: <xsl:value-of select="$URL_DISPLAY"/><br/>

URL_EDIT: <xsl:value-of select="$URL_EDIT"/><br/>

URL_New: <xsl:value-of select="$URL_New"/><br/>

WebQueryInfo: <xsl:value-of select="$WebQueryInfo"/><br/>

URL_Edit: <xsl:value-of select="$URL_Edit"/><br/>

URL_Lookup: <xsl:value-of select="$URL_Lookup"/><br/>

<!-- Dump parameters -->

The ddwrt namespace, a reference

And now we come to the meat of this article. A reference guide to the set of functions implemented in the ddwrt namespace. Have a look at the XSLT code generated by FrontPage, and you know what I’m talking about: those functions starting with ddwrt:.

What follows is an overview of all public functions in the internal class DdwRuntime that is automatically available in the XSLT code in a DVWP.

Nothing really interesting is happening here, and you don’t call the constructor yourself. This function is automatically called on instantiating the DdwRuntime class as an XSLT Extesion Object. Don’t bother about it.

This function returns the passed szStr string parameter. The preserveWhiteSpace parameter is ignored.

This function goes through the string szStr and does the following replacements:

So the function converts a plain text string containing special characters (in the HTML sense) and newlines to a string that can be inserted into HTML and remains formatted in the same way.

This function goes through the string szData and does the following replacements:

So the function converts a string to a format that can be passed as a parameter in the URL string. If you look at the name of the function, this function is used to encode the connection information that is communicated between connected web parts. Web part connection information is probably encoded because connection information between web parts on separate web part pages are passed on the URL. Creating web part connections between web parts on different web part pages is not available through the web interface for defining web part connections, but FrontPage 2003 does provide functionality to make web part connections between web parts on different pages.

The Counter() function returns an incremental number. The number even increases over pages refreshes so you are ensured of a new number on each call, even over page requests.

If the parameter szFieldName equals the name of the currently selected filter field (assumable the internal name of the field), this function returns the text /_layouts/images/filter.gif , otherwise it returns the text /_layouts/images/blank.gif.

public string FieldFilterOptions(string szName);
This function always returns an empty string.

This function always returns the text urn:schemas-microsoft-com:office:office#, this is the namespace used for all fields defined in for example a SharePoint list.

If the parameter szName equals Desc,  the text /_layouts/images/rsort.gif is returned, otherwise the text /_layouts/images/sort.gif is returned,

This function always returns an empty string.

This function always returns an empty string.

The parameter szDate is converted to a DateTime. Based on the formatFlag parameter which can have a value from 0..15, a new DateTime string is constructed in the given locale lcid. This result is returned by the function.

The parameter szDate is converted to a DateTime. Based on the szFormat parameter which is a standard DateTime formatting flag, a new DateTime string is constructed in the given locale lcid using GetDateTime(szDate).ToString(szFormat, lcid).

The parameter szValue is converted to a DateTime, and returned in the format “d” using GetDateTime(szValue).ToString(“d”, CultureInfo.InvariantCulture). If the conversion to a DateTime fails, the value of the szValue parameter itself is returned.

Fire a connected web part event with a call to __dopostback(), which is the function called in ASP.NET to do a post back to the server. This function uses the GenFireServerEvent() function to do the actual firing of the event. The following event text is “fired”: __connect={szConnectStr};szOtherPostback. See http://www.kbalertz.com/kb_838685.aspx for an example of firing a connection event from XSLT code.

Fire a server event with a call to __dopostback()(), which is the function called in ASP.NET to do a post back to the server. The szEventStr is the actual event text to “fire”.

This function returns DateTime.Parse(szDate).ToUniversalTime().ToLocalTime().

The current coordinated universal time (UTC) is converted to local time, adjusting to the local time zone and daylight saving time.

This function returns the file extension of the give URL parameter szUrl.

Given the string parameter szval, this function returns the part before the first “;” or “#” character. So for example for the string “abaca;dabra”, the string “abaca” is returned.

There is a name-value collection available in the called Vars. This function retrieves the value for the entry with the name szName from the collection.

This function returns true if the parameter szCreatedTime is “younger” than 2 days, otherwise false is returned.

This function returns true if the current user doing the page request is a privileged user (administrator) in the current web, and false if the user is not an administrator. False is returned if the page request is not in the context of a SharePoint web. This function returns the result of a call to SPWeb.IsPriviledgedUser on the current web.

Given the string parameter szInputString, this function returns the first len characters, with the string szMoreText appended. Note: This function makes a mess of HTML strings, because the string is just cut off, without taking HTML formatting tags into account.

This function returns the value of the given property szPropName when the page request is in the context of a list. There are some special properties defined that don’t really have to map to properties directly available on the list.