Client API Reference

Contents

Overview
SharePoint.OpenDocuments Class
SharePoint.SendForReview Class
SharePoint.SpreadsheetLauncher Class

Overview

The Client API Reference for SharePoint Team Services from Microsoft describes classes and methods that can be called from two dynamic link libraries (DLLs) that are installed locally (in the \Program Files\Microsoft Office\Office10 directory) during Microsoft Office setup. The OpenDocuments class is defined in owsclt.dll, while the SendForReview and SpreadsheetLauncher classes are defined in owssupp.dll. Developers can use these classes and methods to extend the functionality of the DLLs for automating various tasks on a SharePoint team Web site. Script can be used, for example, to open or create documents, send documents for review, and import or export lists to or from a team Web site.

To instantiate one of these classes, use the function new ActiveXObject("SharePoint.ClassName.1") in JavaScript, or CreateObject("SharePoint.ClassName.1") in Microsoft Visual Basic Scripting Edition (VBScript), where the progID, class, and version number are specified. The following example demonstrates how to open a document for editing in JavaScript:

<SCRIPT language="JavaScript">
function editDocumentWithProgID()   {
   EditDocumentButton = new ActiveXObject("SharePoint.OpenDocuments.1");
   if (EditDocumentButton)  {
      var strDocument = document.frmEditDoc.EditFile.value;
      var varProgID = document.frmEditDoc.FileProgID.value;

      EditDocumentButton.EditDocument(strDocument); }   }
</SCRIPT>

The following example shows how to accomplish the same task in VBScript:

<SCRIPT language="VBScript">
Sub SubmitEditFile_OnClick
   Dim EditDocumentButton
   Dim strDocument
   Dim EditDoc

   Set EditDocumentButton = CreateObject("SharePoint.OpenDocuments.1")
   EditDoc = IsObject(EditDocumentButton)

   If EditDoc Then
      strDocument = document.frmEditDoc.EditFile.value
      EditDocumentButton.EditDocument(strDocument)
   End If

End Sub
</SCRIPT>

In both examples, a form can be used to call the function and pass it a value for the strDocument variable, specifying the document's URL.

For a code example illustrating the import of contacts from an address book into the contacts list of a SharePoint team Web site, see Code Example for Importing Contacts.

SharePoint.OpenDocuments Class

Allows a team Web site user to create documents based on a specified template or to edit documents with their associated applications.

CreateNewDocument Method

Creates a new document based on the specified template and returns a Boolean value. True indicates that the document was successfully created.

Syntax

expression.CreateNewDocument(TemplateLocation, DefaultSaveLocation)

expression An expression that returns an OpenDocuments object.
TemplateLocation Required String. The URL of the template from which the new document is created, or the programmatic identifier of the application to be invoked when creating the new document.
DefaultSaveLocation Required String. The path specifying a suggested default location for saving the new document.

Example

The following example creates a new document whose progID and default save location are specified by the values for strFileType and strSaveLoc that are passed to the createNewDocument function. The example assumes the existence of a form named frmCreateDoc that has two input boxes, CreateFileType and FileSaveLoc.

<SCRIPT language="JavaScript">
function RefreshOnFocus()   {
   window.location.href = window.location;  }

function createNewDocument()    {
   NewDocumentButton = new ActiveXObject("SharePoint.OpenDocuments.1");

   if (NewDocumentButton)   {
      var strFileType = document.frmCreateDoc.CreateFileType.value;
      var strSaveLoc = document.frmCreateDoc.FileSaveLoc.value;

         if (NewDocumentButton.CreateNewDocument(strFileType, strSaveLoc)) {
            window.onfocus = RefreshOnFocus;    }   }   }
</SCRIPT>

EditDocument Method

Opens the specified document for editing with its associated application or with the specified editor and returns a Boolean value. True indicates that the document was successfully opened.

Syntax

expression.EditDocument(DocumentLocation, [ProgID])

expression An expression that returns an OpenDocuments object.
DocumentLocation Required String. The URL of the document to open for editing.
ProgID Optional String. The ProgID of the application with which the document is to be edited. If this argument is omitted, the default editor for the document is used.

Example

This example opens a specified document for editing. It assumes the existence of a form that calls the editDocumentWithProgID function and passes it the document's URL and the ProgID of the editing application.

<SCRIPT language="JavaScript">
function editDocumentWithProgID(){
   EditDocumentButton = new ActiveXObject("SharePoint.OpenDocuments.1");

   if (EditDocumentButton)  {
      var strDocument = document.frmEditDoc.EditFile.value;
      var varProgID = document.frmEditDoc.FileProgID.value;

      EditDocumentButton.EditDocument(strDocument, varProgID); }   }
</SCRIPT>

SharePoint.SendForReview Class

Allows a SharePoint team Web site user to initialize an e-mail review process for a particular document and enables comments and change tracking.

SendForReview Method

Launches a specially formatted e-mail message in the user's e-mail client application so that a document can be sent for review.

Syntax

expression.SendForReview(URL)

expression An expression that returns a SendForReview object.
URL Required String. The URL of the document to send for review.

Example

The following example launches an e-mail message to send a specified document for review. It assumes the existence of a form that calls the SendForReview function and passes it a value for the document's URL.

<SCRIPT language="VBScript">
Sub SendFile_OnClick
   Dim SendForReviewButton
   Dim RevButton
   Dim strUrl

   Set SendForReviewButton = CreateObject("SharePoint.SendForReview.1")
   RevButton = IsObject(SendForReviewButton)

   If RevButton Then
      strUrl = document.frmSendDoc.FileUrl.value
      SendForReviewButton.SendForReview(strUrl)
   End If
End Sub
</SCRIPT>

SharePoint.SpreadsheetLauncher Class

Allows a SharePoint team Web site user to import lists from spreadsheets or to verify if a compatible spreadsheet application is available for list export.

EnsureImport Method

Verifies that the control used for import and export of contacts is present and registered.

Syntax

expression.EnsureImport()

expression An expression that returns a SpreadsheetLauncher object.

Example

The following example creates a SpreadsheetLauncher object and verifies its presence and registration. For a full example that implements this code block, see Code Example for Importing Contacts.

Set objEnsureImport = CreateObject("SharePoint.SpreadsheetLauncher.1")

If IsObject(objEnsureImport) Then
   objEnsureImport.EnsureImport()
End If

GetCLSID Method

Returns a String representing the class identifier (CLSID) for the specified object. Use this value to construct an <OBJECT> tag to which Microsoft Internet Explorer can bind calls.

Syntax

expression.GetCLSID()

expression An expression that returns a SpreadsheetLauncher object.

Example

See the example given for the following method.

ImportList Method

Imports a list to the SharePoint team Web site and returns a String representing the URL for the new list, to which the user is automatically navigated upon completion of the import.

Syntax

expression.ImportList(List, Title, QuickLaunch, URL)

expression An expression that returns a SpreadsheetLauncher object.
List Required String. The name of the list to be created.
Title Required String. The displayed description of the list to be created. An empty string means a description is not displayed on the new list page.
QuickLaunch Required String. True if a link to the default view page of the new list is added to the Quick Launch bar.
URL Required String. The absolute URL for owssvr.dll (in the virtual server's Program Files\Common Files\Microsoft Shared\web server extensions\50\isapi directory) to which the constructed import request is posted.

Example

This example uses the ImportList method to import data from a spreadsheet into a SharePoint team Web site. After creating a SpreadsheetLauncher object, the example uses the GetCLSID method to construct an <OBJECT> tag for writing the object to the page.

<SCRIPT language="JavaScript">
SpreadsheetLauncherButton = new ActiveXObject("SharePoint.SpreadsheetLauncher.1");

if (SpreadsheetLauncherButton)  {
   var launcherCLSID = SpreadsheetLauncherButton.GetCLSID();
   var objectTag = '<OBJECT classid="clsid:' + launcherCLSID + '" id="SpreadsheetLauncherObj" style="display:none;"></OBJECT>';

   document.write(objectTag);   }

function DoImportSpreadsheet()  {
   var form = document.frmNewList;
   var resultUrl;

   resultUrl = SpreadsheetLauncherObj.ImportList(form['List'].value," ", false, 'http://STSServer1/_vti_bin/owssvr.dll?CS=109&');
   window.parent.location.assign(resultUrl);
   return false;    }
</SCRIPT>

The preceding example assumes the existence of a form like the following, which calls the DoImportSpreadsheet function and passes several INPUT values to the server.

<FORM name="frmNewList" onsubmit="return DoImportSpreadsheet();">
  <INPUT type="Text" title="Name" name="List" maxLength="255">
  <INPUT type="File" name="SpreadsheetFile" style="behavior: url(#SpreadsheetLauncherObj);">
  <INPUT type="Hidden" name="ListTemplate" value='SpreadsheetImport'>
  <INPUT type="Submit" value="Import">
  <INPUT type="Hidden" name="Project" value="ows">
  <INPUT type="Hidden" name="Cmd" value="NewList">
</FORM>

IqyImportEnabled Method

Returns a Boolean value, True indicating that the specified control supports import or export of Web query (.iqy) files. An .iqy file serves as a wrapper for a Web query, and it contains metadata for returning the actual list data. This method determines a registered handler for .iqy files, so that the browser launches the appropriate application when the file is downloaded.

Syntax

expression.IqyImportEnabled()

expression An expression that returns a SpreadsheetLauncher object.

Example

The following example exports the Contacts list of a team Web site to a spreadsheet, using the IqyImportEnabled method to verify that the export is possible.

<SCRIPT language="JavaScript">
function ExportList(using){
   ExporterObj = new ActiveXObject("SharePoint.SpreadsheetLauncher.1");

   if (ExporterObj && ExporterObj.IqyImportEnabled())   {
      window.parent.location.href = using + "&Source=" + window.location.href;  }   }
</SCRIPT>

The onclick attribute of an <A> tag that would call the ExportList function contains a URL such as the following, which uses the query.iqy file for processing the query:

javaScript:ExportList('http://STSServer1/_vti_bin/owssvr.dll?CS=109&Using=_layouts/query.iqy&List=Contacts&View=&CacheControl=1');javascript:return false;