Customizing Web Views in File Dialog Boxes

  • Article

Customizing Web Views in File Dialog Boxes

In SharePoint Team Services from Microsoft, Web views provide browser-like functionality in the file dialog boxes of an application, allowing users to modify how document libraries are displayed when opening or saving files. When a team Web site is created, the server places a Web view page, named FileDlg.htm, both in the site's wwwroot/_layouts folder and in the Forms folder of its document library. The _layouts folder file presents a view of all the document libraries on a site, while the Forms folder file of a given document library presents a view of all the documents contained in that library. As a result, users are presented with a view of libraries similar to a browser, and they can sort by the various fields to help them make selections.

By customizing FileDlg.htm within the _layouts folder, you can add filtering for which document libraries are displayed in the client application's dialog boxes. By customizing FileDlg.htm within the Forms folder, you can add such features as variable filtering for a given document library, which makes it easy for users to find specific types of files. For example, you can filter by documents written by a particular author, or you can filter by documents pertaining to customers in a specific geographic region. Messages and other information relevant to a target user or application can thus be made accessible from within the application itself, instead of from a Web page accessed separately by the browser. In addition to standard HTML and script, you can use Collaborative Application Markup Language (CAML) to customize Web views.

The use of Web views requires that the client application have the following capabilities, which may need to be implemented by programming a Web browser control:

  • Send HTTP requests in order to retrieve the list of document libraries on a Web site or the list of documents within a given document library.
  • Analyze an HTML document and look for certain tags and attributes. It must recognize the fileattribute and ID parameters specified in a row of the view table. The fileattribute parameter can be set to file or folder, while ID specifies the URL of FileDlg.htm.
  • Know how to respond to actions taken by users within the Web view, such as a click representing the selection of a row or the second click of a double click.

Syntax

The following example illustrates the URL syntax that can be used for posting commands to the server, which displays the Save dialog box for the Research document library of a subweb on the server:

http://STSServer1/Subweb1/_vti_bin/owssvr.dll?location=Research&dialogview=FileSave

The location parameter specifies the server-relative URL of the document library, but if left blank, it specifies displaying the list of all document libraries on the team Web site. The dialogview parameter can be set to FileOpen (Open dialog box), FileSave (Save dialog box), or SaveForm (Web File Properties form that is displayed when creating and then saving a file to a document library).

The next example, however, specifies different parameters from those implemented in the preceding example. Using FileDlg.htm for processing the request, it filters a Project1 document library in order to only display work by the Graphics team:

http://STSServer1/Subweb1/_vti_bin/owssvr.dll?Using=Project1/Forms/FileDlg.htm&FilterField1=Team&FilterValue1=Graphics

As evident here, parameters generally used for filtering on SharePoint Team Services lists can be added to the URL when you're working with Web views. In other words, parameters such as the following can be used: FileDialogFilterValue, FilterFieldn, FilterValuen, SortField, SortDir, and Using. For information on these parameters, see Using the URL Protocol.

Example

The following example illustrates the kind of customization that you can make to a Web view. It adds a drop-down list box that allows users to filter the view according to file type. First, a block of CAML is used to define a view table for viewing the files returned from the server.

<!--Use CAML to define the view.-->
<ows:XML>
  <SetList Scope="Request">Documents</SetList>
  <View Name="DocDlgView">
    <ViewFields>
      <FieldRef Name="DocIcon"/>
      <FieldRef Name="Title"/>
      <FieldRef Name="Created_x0020_By"/>
      <FieldRef Name="Last_x0020_Modified"/>
    </ViewFields>
    <ViewHeader>
      <HTML><![CDATA[<TABLE ID="DocDlgView" width="100%" style="cursor:
        default;" border=0 rules=rows cellspacing=0 cellpadding=2><TR>]]></HTML>
      <Fields>
        <HTML><![CDATA[<TH Class="ms-vh">]]></HTML>
        <Field/>
        <HTML><![CDATA[</TH>]]></HTML>
      </Fields>
      <HTML><![CDATA[</TR>]]></HTML>
    </ViewHeader>
    <ViewBody>
      <HTML><![CDATA[<TR fileattribute=file ID="]]></HTML>
      <HttpHost URLEncodeAsURL="TRUE"/>
      <LookupColumn Name="FileRef" URLEncodeAsURL="TRUE"/>
      <HTML><![CDATA[" onmousedown="selectrow()" onclick="selectrow()">]]></HTML>
      <Fields>
        <HTML><![CDATA[<TD class="ms-vb">]]></HTML>
        <Field/>
        <HTML><![CDATA[</TD>]]></HTML>
      </Fields>
      <HTML><![CDATA[</TR>]]></HTML>
    </ViewBody>
    <ViewFooter>
      <HTML><![CDATA[</TABLE>]]></HTML>
    </ViewFooter>
    <ViewEmpty><HTML><![CDATA[<TABLE ID="FileDialogViewTable" width="100%" style="cursor: default;"
        border=0 rules=rows cellspacing=0 cellpadding=2><TR><TH></TH>]]></HTML>
      <Fields>
        <Switch>
          <Expr><Property Select="Name"/></Expr>
          <Case Value="FileRef"/>
          <Default><HTML><![CDATA[<TH Class="ms-vh">]]></HTML>
            <Field/>
            <HTML><![CDATA[</TH>]]></HTML>
          </Default>
        </Switch>
      </Fields>
      <HTML><![CDATA[</TR></TABLE>]]></HTML>
      <HTML><![CDATA[<TABLE width="100%" border=0 rules=rows><TR>]]></HTML>
      <HTML><![CDATA[<TD Class="ms-vb">]]></HTML>
      <HTML>There are no documents of the specified type in this document library.</HTML>
      <HTML><![CDATA[</TD></TR></TABLE>]]></HTML>
    </ViewEmpty>
  </View>
</ows:XML>

The above code sets "Documents" as the list to use, and specifies the fields to display in the view's header and body, as well as the default text to display if the library doesn't contain files of the specified type. Notice that the ViewBody section includes the fileattribute attribute,**** specifying that the view is for files, not for a folder, and the ID attribute, specifying the URL of FileDlg.htm through the HttpHost and LookupColumn elements, which combine to form the complete URL. This code substitutes for the bot (bot="ListView") that by default defines the view table of FileDlg.htm.

The next code block describes the drop-down list box that is to be used in the Web view.

<!--Create the drop-down list box for selecting the file type to display.-->
<TD ALIGN="right"><a style="visibility:hidden" target="_self" ID="FilterLink"
href="http://STSserver/_vti_bin/owssvr.dll?location=Shared%20Documents&dialogview=FileOpen"></a>
  <SELECT id="mnuView" onchange="FilterLink.href=FilterLink.href+mnuView.value; FilterLink.click();">
    <OPTION value="">All</option>
    <OPTION value="&FileDialogFilterValue=*.*">All</option>
    <OPTION value="&FileDialogFilterValue=*.htm">*.htm</option>
    <OPTION value="&FileDialogFilterValue=*.doc">*.doc</option>
    <OPTION value="&FileDialogFilterValue=*.xls">*.xls</option>
    <OPTION value="&FileDialogFilterValue=*.ppt">*.ppt</option>
  </SELECT>
</TD>

The <A> tag's href attribute defines the base URL for the command, and the onchange attribute in the subsequent <SELECT> tag adds an appropriate file type for the FileDialogFilterValue parameter. This code is added immediately after the <TD> tag that contains the bot defining the page title area (class="ms-pagetitle"). To make the box flush right, the width attribute of the <TABLE> tag containing the selector must be set to 100%.

Finally, the following script updates the drop-down list box so that it reflects the current selection.

<!--Update the drop-down list box.-->
<script>
function UpdateSelector()   {
var sSel="<ows:GetVar Name='FileDialogFilterValue'/>";
var oOptions=mnuView.options;
for (i=0; i<oOptions.length; i++)    {
   if (oOptions[i].text==sSel)  {
      mnuView.options.selectedIndex=i;
      break;            }}}
</script>

This script can be added just before the body section of the page. A call to the UpdateSelector function must be added to the onload attribute of the <BODY> tag.

Note   For navigation, the window.navigate method could be implemented within the Select element of this example, but in order to prevent users from being able to use the file dialog box as a Web browser, it hasn't been implemented here. Instead, the above selector contains an <A> tag whose target attribute is set to _self in order to redirect the browser to FileDlg.htm.

For more information about the SharePoint Team Services URL protocol, see Using the URL Protocol. For information about CAML, see the CAML Schema Reference.