Web Storage System Forms: The Renderer

This article discusses Web Storage System Forms, focusing on the renderer, which is implemented as an ISAPI extension for Internet Information Server. This article looks at how to build Web-based applications using the rendering capabilities of Web Storage System Forms. Introduction With Microsoft Exchange 2000 and the release of Microsoft SharePoint Portal Server 2001 (formerly code-named "Tahoe"), Microsoft introduces the Web Storage System (WSS), which provides a new collaborative platform for Web-based development. The WSS can store all kinds of documents and data. It combines the aspects of a file system, database, and a Web server. Similar to the Windows file system, the WSS stores items in hierarchical folders. As a database, it responds to queries and supports standard data access. Finally, like a Web server, it furnishes a user interface in HTML via the standard Web protocols. To make it easier to develop a user interface, the Web Storage System introduces Web Storage System Forms (WSS Forms), which provides a way to extend either existing or new Web-based forms. WSS Forms utilizes the WSS Forms Registry, which in turn provides custom-built applications with the ability to handle the rendering of an item or folder referenced in an HTTP request. This is accomplished through registration items. Registration items connect form and view information with data stored in the Web Storage System. Registration items contain several properties (such as browser types, localization information, and version information) that help determine what HTML is returned to the client. A developer can add registration items that both override the default forms and handle custom data types defined in the WSS. For more information on the WSS Forms Registry, see the WSS Platform SDK (http://msdn.microsoft.com/wss). When a client requests a piece of data from the WSS, it performs a search for a matching form registration. If a match is found, the WSS responds according to the properties of the registration entry. At this point it can either use the forms renderer, which takes an HTML page and data binds it, or can execute an Active Server Page (ASP). In the case of an ASP page, the functionality of the forms renderer can be accessed through a scriptable object model (WSS.Form). HTML forms are simple and easy to author. While ASP forms require writing code, they can also be more flexible. In this article, we'll look further into the renderer and creating HTML forms. Requirements Exchange 2000 While the release version of Exchange 2000 includes the WSS Forms Registry, it does not have support for the WSS forms renderer. The renderer technology is provided as an add-on to Exchange through the Exchange 2000 Technology Preview (http://msdn.microsoft.com/wss). The final release will be included in Exchange 2000 Service Pack 1. As with all prerelease code, we recommend that you not install the technology preview on a production Exchange Server. SharePoint Portal Server SharePoint Portal Server 2001 uses the same Web Storage System technology as Exchange 2000. SharePoint Portal Server supports both the WSS Forms Registry and WSS Forms. The examples provided apply both to Exchange 2000 and SharePoint Portal Server. ISAPI Renderer Overview With the Web Storage System, item data is separated from the user interface. This is somewhat different from the way in which data was bound in Exchange 5.5, where a piece of data was defined by a specific Outlook form. The WSS forms renderer provides an easy method of performing data binding (the process of connecting data in the store with HTML through the use of the WSS Forms Registry). Additionally, the renderer provides a method of creating and updating objects as well as the rendering of server-side views. Renderer Execution and Architecture To take advantage of the ISAPI renderer, the developer must use the WSS Forms Registry. An application programmer simply needs to create a form registration with the execute URL entry set to /exchweb/bin/exwform.dll. This is the relative path to the ISAPI DLL. When a client requests an item stored in the Web Storage System, WSS searches the Forms Registry for a matching form registration item. When a match is found, it transfers the HTTP request to exwform.dll and provides it with a different query string containing the contents of the registration fields (FormUrl, DataUrl, RegUrl, ExecuteParameters, and Web Storage System FormsBrowserFlags). The renderer then begins to process the form. When the ISAPI renderer instantiates, it uses the Web Storage System's OLE DB provider (ExOLEDB.Datasource) to read the HTML form specified in the FormUrl field, parsing the HTML for special tags and generating a list of all data bound fields. Next, the renderer makes a request for the required properties against the data item specified in the DataUrl. The DataUrl field contains the specific URL path to the item in the store being requested. The values retrieved go through any necessary conversion need for display, such as formatting for numbers or time zone conversions. The retrieved values are then inserted into the HTML form according to the element to which each is data bound. In some cases, a value is inserted into a property on the element or it may be inserted after the element start tag. Table 1 describes the values used for various HTML elements. Table 1. HTML element values Element Rendering Information Input Description: Use their value attribute set HTML: Rendered: Select Description: Selects the option with a value matching the property value. HTML: Rendered: Anchors Description: Use to set the anchor href attribute HTML: Rendered: Img Description: Use to set the image src attribute HTML: Rendered: SPAN Description: Use to set the text inside the span tag HTML: Rendered: PropValue DIV Description: Use to set the text inside the div tag HTML:

Rendered:

PropValue

Depending on the form requirements, some additional requests are issued against the WSS. For views, the renderer performs a search for the set of properties in a folder needed to populate the view, and then generates an HTML table for the rendering. The type of view generated can vary according to the Web browser the client uses. Internet Information Server (IIS) inspects the HTTP useragent header and the browsecap.ini file to determine the client browser being used. The browsecap.ini file contains settings for the different browsers and versions. Within it, any browser with a setting of WebFormsBrowserFlags=NoViewRender won't be rendered on the server. By default, this flag is set for Microsoft Internet Explorer (IE) 5.0 and later, and Microsoft Outlook 10. The renderer also supports dynamically populating a select control based on items in a specified folder. The renderer performs some additional processing on special elements, such as the and

element is processed, the renderer generates the "action" (see the section "Form Syntax and Rendering Item"). Once everything is complete, the rendered form is sent back to the client. Form Syntax and Rendering Item A form is simply an HTML page with some additional markup that identifies certain elements as being data bound tags or tags that require special processing, such as views. When you use this technology, therefore, you need write no code to databind an HTML element to a record in the Web Storage System. Instead, you can mark an element as data-bound by adding two attributes to the HTML tag: 1) class="field" 2) name="property name" When the class is set to "field," the renderer inserts the value for the property specified in the name attribute onto or into the HTML element. Let's examine the various parts of the following sample form to see how it is designed: Sample Page

The first relevant part of this form is the

element, which has an actionspec attribute defined on it. When the renderer processes the form, it uses the actionspec as a template for generating the action attribute. The action attribute contains the URL path that the Web browsers use to submit the data when it is posted back to the server. When you want to view data in the Web Storage System, you make a request to the URL to the item, not the URL to the HTML form. Similarly, the URL used to save changes is the URL to the item. Since the URL of the item changes according to the data that is requested, it needs to be generated dynamically. This is why the actionspec attribute is used. An absolute or relative URL can be specified, or a set of macros can be used to help generate the URL. The available macros include those shown in Table 2. Table 2. URL macros Macro Description %FormUrl% The URL to the form being rendered. %FormContainer% The URL to the folder containing the form being rendered. %DataUrl% The URL to the data item being rendered. %DataContainer% The URL to the folder containing the data item being rendered. When the renderer processes these macros, the resulting HTML code contains the URL relevant to the appropriate macro described above. The second relevant part of the form is the two data-bound input tags. Any tag can be data bound, but how the renderer actually performs the data binding depends on the HTML element used. To identify an element as being data bound, it needs to have a class and name attribute. The class is always set to class="field." The name attribute must be set to the Web Storage System schema property name that the data bound element refers to. For more information on the Web Storage System schema, see the WSS Platform SDK available from http://msdn.microsoft.com/wss. Updating Items To change the properties on an existing item, a Web browser needs to submit a POST request against the item to be updated. The data submitted to the server consists of a series of name/value pairs where the name is a schema property and the value is the data to be written. The POST request must match a form registration entry that invokes the renderer. This is accomplished by setting the ExecuteUrl property to /exchweb/bin/exwform.dll in the form registration. When these criteria are met, the renderer updates the item with the values submitted in the request. By default, it then displays the item again with the updated values. In many applications, you will want to redirect to another page after an update. This is accomplished through the redir=url token. This token can be placed in the ExecuteParameters property of a form registration or directly in the HTML form as part of the actionspec value. Creating New Items Creating new items is very similar to updating items. To create a new item, a Web browser needs to POST a series of name/value pairs to the server where the name is a schema property and the value is the data to be saved. This request must be made against a folder in an Exchange virtual root (a root created with the Exchange System Manager MMC and not the Internet Services Manager MMC). Additionally, the folder must have a corresponding form registration to match the request. The form registration must contain the CreateNew token in the ExecuteParameters property. Passing in the CreateNew token to the renderer instructs it to create a new item rather than updating the properties on the folder. The renderer creates a new item and then by default displays it back to the client browser. Just as with the update process described in the previous section, you can use the redir=url token to redirect to another location after creating the item. By default, the item created will have a displayname of {GUID}.eml (where GUID represents a 128 bit globally unique identifier). To provide a user-friendly name, the hintforurl property (http://schemas.microsoft.com/exchange/nosave/hintforurl) can be added to a custom form with a value equal to a field on the form. The renderer uses the value contained in the property referenced by hintforurl as the name of the item to be created. See the following HTML code example: In this case, the hintforurl tells the renderer to use the FileName property as the hint. The value submitted to the server for the FileName property is "SampleItem." The rendered creates the resulting item with the name "SampleItem.eml." In the case of name conflicts, a number is appended to the hint, as in "SampleItem-2.eml." Note that the input type is set to "hidden." Since this field is used behind the scenes, this setting prevents the field from being displayed in a browser. Document Upload Web Storage System Forms provides a simple method of uploading a document to become the default stream for an item in the store. For example, using WSS Forms, a developer can quickly build a document repository system where a user enters some category information in a Web form and selects a document for upload. In the background, the forms renderer handles uploading the document and appending the supplied metadata to the uploaded item. Making the document the default stream is different from adding an attachment to an item. Instead, when the user clicks the item that you upload, the stream is displayed to the browser. If the requested item has an associated application for the data type, the associated application opens the item (for example, Microsoft Paint opening a .bmp file). You can implement the upload method by formatting the encoding type of the form to multipart/form-data (

Comments

Plain text