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
AutoHyperLink
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 |
|---|---|
| & | & |
| \ | ' |
| < | < |
| > | > |
| \n | <br/> |
| <space> | If not the first space in a row, translated to
So: "a b" -> "a b", but "a b" -> "a b" |
| " | " |
| \x00a0 | |
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.
FilterLink
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:
|
| 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:includeandxsl:import. This blocks the possibility of code reuse through inclusion or reusable XSLT code files.
Additional Resources
For additional information, see the following resources:
- Customizing the Data View Web Part in FrontPage 2003
- Blog: FrontPoint (maintained by members of the Microsoft Office FrontPage team, discusses using FrontPage together with Microsoft SharePoint Products and Technologies)
- Microsoft Office Developer Center
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.