SharePoint Data View Web Part Extension Functions in the ddwrt Namespace

 

Serge van den Oever
Macaw

October 2005

Applies to:
    Microsoft Windows SharePoint Services 2003
    Microsoft Office SharePoint Portal Server 2003
    Microsoft Office FrontPage 2003

Summary: This overview of the ddwrt namespace describes the ddwrt functions used in the Extensible Stylesheet Language Transformation (XSLT) code of the Data View Web Part. (17 printed pages)

Contents

Introduction
About the ddwrt Namespace Functions
Conclusion
Additional Resources
About the Author

Introduction

Microsoft Windows SharePoint Services provides the powerful Data View Web Part that can perform an Extensible Stylesheet Language Transformation (XSLT) on XML data retrieved from a data source. When you are working with a Web site based on Windows SharePoint Services from within Microsoft Office FrontPage 2003, you can use the Data View Web Part to do the following:

  • Define a query and data source from which to retrieve the XML data. Data sources can be SharePoint lists or external databases such as Microsoft SQL Server.
  • Define the XSLT transformation that converts XML retrieved from the data source into HTML. FrontPage offers a WYSIWYG experience for editing these XSLT views, including live data preview.

During the XSLT transformation process, the Data View Web Part uses an XSLT extension object that provides several functions in the ddwrt namespace. These functions perform tasks such as accessing properties of a SharePoint list or firing events to connected Web Parts. This article describes the functions implemented by the extension object.

**Note   **The information in this article was originally published as an entry in my blog, Serge van den Oever [Macaw].

You can create Data View Web Parts without using FrontPage because the logic for creating Data View Web Parts is included with Windows SharePoint Services. However, you will find it easier to create them using FrontPage. FrontPage can create a WYSIWYG data view that is fully editable in its design surface using normal HTML editing features. As you edit the HTML representing the view, using standard dialog boxes and commands such as Insert Table, FrontPage rewrites the underlying XSLT to accomplish the intended result.

FrontPage is also able to convert a SharePoint List View Web Part (defined in Collaborative Application Markup Language or CAML) to an equivalent XSLT transformation using the Data View Web Part. You can then use FrontPage to fully edit the data view in a WYSIWYG way. The generated XSLT transforms the data retrieved from the SharePoint list to the same HTML output generated by the CAML.

The logic for the Data View Web Part consists of the following:

  • Microsoft.SharePoint.WebPartPages.DataViewWebPart, a class available in the Microsoft.SharePoint.dll assembly that implements the Data View Web Part functionality.
  • Microsoft.SharePoint.WebPartPages.DdwRuntime, an internal class available in the Microsoft.SharePoint.dll assembly that is made available as an XSLT extension object, which implements a set of functions in the ddwrt namespace. This set of functions is the focus of this article.

A Data View Web Part is persisted as a .dwp file that contains XML describing all of its properties, including the data query and the XSLT transformation.

DataViewWebPart and the ddwrt Namespace

The Data View Web Part is implemented in the Microsoft.SharePoint.WebPartPages.DataViewWebPart class and uses the internal Microsoft.SharePoint.WebPartPages.DdwRuntime class to provide utility functions. Many of these functions were designed to maintain parity between data views and list views. You can use these functions in the XSLT of any Data View Web Part.

The DDWRT extension object provides a collection of variables that is persisted across page requests in the ASP.NET view state, so it can pass information from the XSLT transformation of the current page request to the XSLT transformation of the next page request. You can access this collection with the GetVar function. The following table shows the default set of defined name-value pairs.

Table 1. Default name-value pairs

Name Value
Filter Empty string. Set to the current filter field name and value, if any.
View {GUID}. If the Web Part is a view of a list, this is the view identifier.
FreeForm FALSE. Set to TRUE if the view is not using a tabular style.
WPQ This is the Web Part Qualifier used to distinguish between multiple parts on the page. For example, WPQ1, WPQ2, and so on.

In addition, several XSLT parameters are passed to the transformation, as shown in Table 2.

Table 2. XSLT parameters

Parameter Value
HttpHost URL of the Web server.
Language LCID of the language used on the site, for example 1033 for an English-language site.
ImagesPath URL of the images path, in the context of the current Web site, for example: http://server/sites/test/_layouts/images/
HttpPath URL of the path to the appropriate owssvr.dll file in the context of the current Web site. For example, http://server/sites/test/_vti_bin/owssvr.dll?CS=109, where CS=109 means that the UTF-8 character set is used for all communication to owssvr.dll.
HttpVDir Root directory of the current subsite. For example, for the page http://server/sites/test/default.aspx, the value is http://server/sites/test/.
PageUrl The URL of the currently requested page. For example, http://server/sites/test/default.aspx.
Project The site-relative URL of the root folder of a list, if the current page request is in the context of a list. This is the name of the folder that contains all the files used in working with the list, for example, Lists/Announcements.
View {GUID}. If the Web Part is a view of a list, this is the view identifier.
ListProperty_TemplateUrl When the current page request is in the context of a list, and the list is a document library, this is the URL of the template document for this document library.
ListUrlDir_FALSE When the current page request is in the context of a list, this is the complete URL to the root folder of the list, for example, http://server/sites/test/Lists/Announcements.
ListUrlDir_TRUE When the current page request is in the context of a list, this is the site-relative URL of the root folder of the list. (This is the same as parameter Project).
URL_New, URL_NEW When the current page request is in the context of a list, this is the URL to the page for creating a new item in the list (newform).
URL_Edit, URL_EDIT When the current page request is in the context of a list, this is the URL to the page for editing an existing item in the list (editform).
URL_Display, URL_DISPLAY When the current page request is in the context of a list, this is the URL to the page containing the default view of the list (displayform).

The XSLT code generated by FrontPage 2003 includes <xsl:param> definitions in the stylesheet to hold the values passed to the transformation. To see the value of these parameters, add the following XSLT code to the HTML code generated for a Data View Web Part.

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

About the ddwrt Namespace Functions

Following is information about the set of functions implemented in the ddwrt namespace. These functions are prefixed with ddwrt in the XSLT code that is generated by FrontPage.

    AutoHyperLink
    AutoNewLine
    ConnEnclode
    Counter
    FieldFilterImageUrl
    FieldFilterOptions
    FieldPrefix
    FieldSortImageUrl
    FieldSortParameters
    FilterLink
    FormatDate
    FormatDateTime
    GenDisplayName
    GenFireConnection
    GenFireServerEvent
    GetFileExtension
    GetStringBeforeSeparator
    GetVar
    IfNew
    IsPrivilegedUser
    Limit
    ListProperty
    MapToAll
    MapToControl
    MapToIcon
    NameChanged
    PresenceEnabled
    SelectOptions
    SetVar
    ThreadStamp
    Today
    TodayIso
    UrlBaseName
    UrlDirName
    UrlEncode
    URLLookup
    UserLookup

public string AutoHyperLink(string szStr, bool preserveWhitespace);

Returns the passed szStr string parameter with any detected URLs turned into hyperlinks. If the preserveWhitespace parameter is false, repeated white-space characters are collapsed.

When personalization is on, this creates a hyperlink from a user's alias to either their MySite or their UserInfo page.

AutoNewLine

public string AutoNewLine(string szStr);

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

This function goes through the string szStr and performs the replacements shown in Table 3.

Table 3. Replacements performed by AutoNewLine function

From To
& &amp;
\ &#39;
< &lt;
> &gt;
\n <br/>
<space> If not the first space in a row, translated to &nbsp;

So: "a b" -> "a b", but "a b" -> "a &nbsp;b"

" &quot;
\x00a0 &nbsp;

ConnEncode

public string ConnEncode(string szData);

Encodes the connection information that is communicated between connected Web Parts by converting szData to a format that can be passed as a parameter in the URL string.

This function goes through the string szData and performs the replacements shown in Table 4.

Table 4. Replacements performed by ConnEncode function

From To
# &23
& &26
` &27
* &2A
; &3B
\ &5C

Web Part connection information is encoded because connection information between Web Parts on separate Web Part Pages is passed in 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.

Counter

public string Counter();

Returns an incremental number. The number remains unique over page requests unless the application module is unloaded.

FieldFilterImageUrl

public string FieldFilterImageUrl(string szFieldName);

If the parameter szFieldName equals the name of the currently selected filter field (assuming the internal name of the field), this function returns the path to a filter icon; otherwise, it returns the path to a blank icon. The returned string is either "/_layouts/images/filter.gif" or "/_layouts/images/blank.gif".

FieldFilterOptions

public string FieldFilterOptions(string szName);

Unused. Returns an empty string.

FieldPrefix

public string FieldPrefix();

Returns the text "urn:schemas-microsoft-com:office:office#", which is the namespace used for all fields defined in a SharePoint list.

FieldSortImageUrl

public string FieldSortImageUrl(string szName);

Returns the path to a sort direction icon. If the parameter szName equals "Desc", the text "/_layouts/images/rsort.gif" is returned, otherwise, the text "/_layouts/images/sort.gif" is returned.

FieldSortParameters

public string FieldSortParameters(string szName);

Unused. Returns an empty string.

public string FilterLink();

Unused. Returns an empty string.

FormatDate

public string FormatDate(string szDate, long lcid, long formatFlag);

The parameter szDate is converted to a DateTime. Based on the formatFlag parameter, which can have a value 0–15, a new DateTime string is constructed in the given locale lcid. Table 5 shows the results returned from this function.

Table 5. Results returned by the FormatDate function

Flag Formatting String Result
1 (0001) "d" Date only as M/d/yyyy. Example: "08/17/2000".
3 (0011) "D" Date only as dddd, MM dd, yyyy. Example: "Thursday, August 17, 2000".
4 (0100) "t" Time only as h:mm. Example: "16:32".
5 (0101) "g" DateTime as M/d/yyyy h:mm. Example: "08/17/2000 16:32".
7 (0111) "f" DateTime as dddd, MM dd, yyyy h:mm. Example: "Thursday, August 17, 2000 16:32".
12 (1100) "T" Time only as h:mm:ss. Example: "16:32:32".
13 (1101) "G" DateTime as M/d/yyyy h:mm:ss. Example: "08/17/2000 16:32:32".
15 (1111) "F" DateTime as dddd, MMMM dd, yyyy h:mm:ss. Example: "Thursday, August 17, 2000 16:32:32".

FormatDateTime

public string FormatDateTime(string szDate, long lcid, string szFormat);

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

For documentation, see the DateTime.ToString Method.

GenDisplayName

public string GenDisplayName(string szValue);

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.

GenFireConnection

public string GenFireConnection(string szConnectStr, string szOtherPostback);

Generates a hyperlink used to fire a connected Web Part event with a call to __dopostback(), which is the function called in Microsoft ASP.NET to do a post back to the server. This function uses the GenFireServerEvent() function internally. The following text is returned: __connect={szConnectStr};szOtherPostback.

GenFireServerEvent

public string GenFireServerEvent(string szEventStr)

Generates a hyperlink used to 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.

GetFileExtension

public string GetFileExtension(string szUrl);

Returns the file extension of szUrl (the portion after the "." character). If no extension is present, returns an empty string.

GetStringBeforeSeparator

public static string GetStringBeforeSeparator(string szval);

Given the string parameter szval, this function returns the part before the first ";" or "#" character. For example, if szval is "abraca;dabra", the string "abraca" is returned.

GetVar

public string GetVar(string szName);

There is a name-value collection available to the XSLT extension object. This function retrieves the value for the entry with the name szName from the collection.

IfNew

public bool IfNew(string szCreatedTime);

Returns true if the parameter szCreatedTime is less than two days old; otherwise, it returns false.

IsPrivilegedUser

public bool IsPrivilegedUser();

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

Limit

public string Limit(string szInputText, int len, string szMoreText);

If the given string parameter szInputString is longer than len characters, this function returns the first len characters, with the string szMoreText appended. Otherwise the input string is returned unmodified.

**Note   **This function should not be used with HTML strings. The string is truncated without taking the HTML markup into account.

ListProperty

public string ListProperty(string szPropName);

Returns the value of the given property szPropName when the page request is in the context of a SharePoint list. Certain special properties are defined that do not map directly to properties available on the list, as described in Table 6.

Table 6. Special properties for ListProperty

Field Name Information
title The title that is displayed for the list.
description The description for the list.
direction Direction of the reading order for the list. This property contains the string "ltr" if the reading order is left-to-right, "rtl" if the reading order is right-to-left, or it contains "none".
basetype Number with the base type of the list. Windows SharePoint Services contains the following base types:
  • DiscussionBoard: Discussion board
  • DocumentLibrary: Document library
  • GenericList: Generic type of list template used for most lists
  • Issue: Issue-tracking list
  • Survey: Survey list
  • UnspecifiedBaseType: No base type specified
  • Unused: Unused
servertemplate String with the name of the template that the list is based on.
defaultviewurl URL of the page providing the default view for the list.
url URL of the list.
rootfolderurl URL of the root folder of the list. The root folder is the folder that contains all the files that are used when working with the list. In most cases, this is the Forms folder.
version The version number of the list.
name The internal name of the list.
moderatedlist 1 if content approval is enabled; otherwise, 0.
attachmentsdisabled 1 if attachments cannot be added to items in the list; otherwise, 0.
multiplemtgdatalist 1 if the list in a Meeting Workspace site can contain data for multiple meeting instances within the site; 0 if not.
templateurl URL of the template document used to create a new document in a document library.
webimagewidth If a picture library, the webimagewidth is the width value used to display images in a picture library (in pixels); otherwise an empty string.
webimageheight If a picture library, the webimageheight is the height value used to display images in a picture library (in pixels); otherwise, an empty string.
thumbnailsize If a picture library, the thumbnailsize is the size in pixels of the height or width, whichever is longest, to use for thumbnails in the picture library; otherwise, an empty string.
itemcount Number of items in the list. The value of the itemcount does not include folders in a document library but does include files within subfolders in a document library.

MapToAll

public string MapToAll(string szProgID, string szExt);

Returns a concatenation of Icon|EditText|Control, as defined in the docicon.xml file. If the specified parameter szProgID (for example, "Word.Document") is not found in "docicon.xml", the ProgID is determined by the extension specified in the szExt parameter (for example, "doc").

This function uses the function MapToControl() to determine the value of Control, and the function MapToIcon() to determine the value of Icon. The EditText is the text displayed with a hyperlink to edit the document, as in "Edit with EditText".

MapToControl

public string MapToControl(string szProgID, string szExt);

Returns the value of Control for the given ProgID (szProgID) or extension (szExt). A Control is the control to open the document with, such as "SharePoint.OpenDocuments".

MapToIcon

public string MapToIcon(string szProgID, string szExt);

Returns the Icon for the given ProgID (szProgID) or extension (szExt). The Icon is the name of the .gif file, without the complete path to the file, which is typically "/_layouts/images/Icon".

NameChanged

public string NameChanged(string szName, long id);

Indicates whether szNamevalue has changed since the last time this function was called. It returns an empty string if the value has not changed; otherwise, the previous value is returned.

This function is used in XSLT grouping features, which are implemented by sorting the list and iterating through the rows, checking whether the grouped-by value is different on each row.

  • If id is -1, the caller wants to break out of the enumeration, and an empty string is returned.
  • If id is -100, the caller wants to know how many items have been processed to this point. After the call, the counter is reset.
  • Otherwise, the id is a positive integer identifying the index of the group-by field being tested (1, 2, 3, and so on). Use a different index for each group-by field.

PresenceEnabled

public string PresenceEnabled();

If the current page request is in the context of a SharePoint site, this function returns true when presence is enabled for the site; otherwise, false.

If the current page request is not in the context of a SharePoint site, an empty string is returned.

SelectOptions

public string SelectOptions(string szName);

Unused. Returns an empty string.

SetVar

public string SetVar(string szName, string szValue);

Sets the value szValue for the name szName in the name-value collection maintained by the XSLT extension object. See GetVar.

ThreadStamp

public string ThreadStamp();

Returns the timestamp of the current HTTP context in the format yyyyMMddHHmmss.

Today

public string Today();

Returns DateTime.Now.ToString("G", CultureInfo.InvariantCulture);

TodayIso

public string TodayIso();

Returns DateTime.Now.ToString("s", CultureInfo.InvariantCulture);

UrlBaseName

public string UrlBaseName(string szUrl);

Returns the basename of the file in the given URL szUrl. For example, if szUrl is /a/b/basename.ext, the value basename is returned.

UrlDirName

public string UrlDirName(string szUrl);

Returns the directory name of the file in the given URL szUrl. For example, if szUrl is "/a/b/basename.ext", the value "/a/b/" is returned.

UrlEncode

public string UrlEncode(string szUrl);

Returns HttpUtility.UrlEncode(szUrl). The string parameter szUrl is encoded so it can be safely used as part of a URL.

URLLookup

public string URLLookup(string ListName, string FieldAttributeName, string FieldPosition);

Returns the desired URL link based on the input of a list name, field attribute name, and field position in the list. The ListName parameter contains the name of the listname, for example, UserInfo. It could also have values of "newform", "editform", and "displayform".

The FieldAttributeName parameter contains a Windows SharePoint Services list field internal name, and FieldPosition contains a Windows SharePoint Services list field "id" value, for example, 1, 2, and so on.

For example, if this function is called with the parameter ListName set to "UserInfo", the following URL is returned: /_layouts/lcid/userdisp.aspx?Force=True&ID=ID of user.

**Note   **The

Force=True

parameter forces redirection to a page that displays the information as stored in the UserInfo table. If you want to redirect to the public MySite of a user in a SharePoint Portal Server application, you can remove the

Force=True

command using a simple string replacement.

UserLookup

public string UserLookup(string UserName, string FieldName);

Returns e-mail, ID, or login information about the specified user.

The UserName parameter contains the value as defined in SPUser.Name, for example, DOMAIN\User. It is in the format defined by FieldName, which can be either "Email", "ID", or "Login".

Conclusion

This is only a small part of the world of Data View Web Parts. There is so much more information you can explore to grasp the complete power of this Web Part.

Although the possibilities of Data View Web Parts are almost unlimited, be aware of the following disadvantages of using them:

  • To make more advanced modifications beyond the standard capabilities of FrontPage, you need an experienced XSLT coder.
  • Data View Web Parts are difficult to reuse from one situation to another because certain information is hard-coded in the XSLT markup. This also makes it hard to maintain modifications made to multiple instances of a Data View Web Part.
  • For security reasons, you cannot create Microsoft JScript code in your XSLT code using msxsl:script. All extension code available in your XSLT must either come from standard XSLT code, or from the functions described in this article.
  • In the XSLT transformation of Data View Web Parts, the following functionality is blocked: xsl:include and xsl:import. This blocks the possibility of code reuse through inclusion or reusable XSLT code files.

Additional Resources

For additional information, see the following resources:

About the Author

Serge van den Oever is a specialist developer at Macaw, a Dutch company specializing in building Internet solutions based on Microsoft technology. His main area of expertise is software architecture using the Microsoft .NET Framework and Microsoft server products. He is currently responsible for the knowledge development department of Macaw, where SharePoint Products and Technologies are extensively used for communication and collaboration. Serge has been involved in many large SharePoint Products and Technologies intranet implementations, and his experience with the SharePoint Products and Technologies platforms goes back to the time when it was still code-named "Tahoe".

For more information, read Serge van den Oever's blog.