Web Storage System Forms - The Renderer
Web Storage System Forms ”The Renderer
Beyond providing easy URLs to work with and a rich forms registry, Web Storage System Forms also allow you to perform no-code data binding, database lookups to populate controls, and built-in document upload as standalone documents or as attachments, and they provide an easy way to create views by using an XML view descriptor. We will look at all of these features in Web Storage System Forms and discuss when to use Web Storage System Forms technology and when to roll your own using ASP forms. These features are provided by the WSS Forms Renderer.
| Note | If you are going to work with Web Storage System Forms using ASP pages in the public vroot for Public Folders, be sure to enable Script execution in the Microsoft Internet Information Service (IIS) Services Manager. Otherwise, you will receive the standard IIS "unauthorized to view this page in your browser" error. Also, when you use WSS Forms, you need to enable freedocs support via the registry on your server. You will want to add a DWORD value HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ MSExchangeWEB\OWA\EnableFreedocs . Set the DWORD to one of the following values:
The default behavior (Freedocs are inaccessible in public folders) will cause workflow applications that request Freedocs, such as a Web Forms application using the exwform.dll renderer, to not function correctly. You will receive a 403 error which is a forbidden error. |
Registering Your WSS Forms to Use the Renderer
If you want to use the WSS Forms Renderer and not build your own ASP pages that do data binding via EXOLEDB or another method, you must change your form registrations slightly. You have to change your ExecuteURL to /exchweb /bin/exwform.dll so the renderer will be the DLL that is executed when the form is loaded. Also, you have to change your FormURL and DataURL to point to your HTML form and the Exchange item that you want to render, respectively. The HTML form you pass can be just a simple HTML form with no server-side or client-side script, or it can be a full-blown ASP page that contains both server-side and client-side script. With ASP forms you can still use HTML binding, but you can also add more complex scripts and code than you can in a pure HTML form. It is up to you how complex you make your forms. However, you can use the built-in renderer and view capabilities in WSS Forms in either case, as you will see.
WSS Forms Data Binding
The WSS Forms Renderer provides the ability to perform automatic data binding, whether you are creating new items, displaying items, or updating existing items. To provide a no-code solution, the WSS Forms Renderer uses some special HTML markup to specify that you want an HTML element data-bound to a particular field in your Exchange data. This special markup uses HTML element class=field and sets the Name of the HTML element to the full property name that you want to data-bind to. For example, the following HTML binds the subject of a message to a text box on the form:
<input type="text" name="urn:schemas:httpmail:subject" class="field">
Depending on the type of HTML element you bind to an item in Exchange, you will get different results. For example, the previous example binds a text box to a single-value string in Exchange. However, you can bind the same text box to a multivalue string. Using a comma or a semi- colon as your delimiter , you can post multiple values for your multivalue string back to Exchange. Check boxes and radio buttons are also supported as data-bound fields. If a value from the data-bound field matches the value in the check box or radio button group , that HTML element is checked or selected. Finally, you can also data-bind other types of HTML elements, such as DIVs, SPANs, anchors, and even IMG (image) tags.
Let's take a look at a slightly more complex form in HTML:
<HTML> <body> <form method="POST" class="form" name="theform" actionspec="%DataURL%?cmd=contents"> <H1>My list</H1> <BR> Read only: <input type="checkbox" name="DAV:isreadonly" class="field" form="theform" value="ON"> <p> Hidden: <br><input type="radio" name="DAV:ishidden" value="1 class="field" form="theform">True<BR> <input type="radio" name="DAV:ishidden" value="0" class="field" form="theform">False <p> Friendly name: <DIV name="DAV:displayname" class="field" form="theform"> </DIV><p> Expiration date: <input type="text" name="urn:schemas:httpmail:expiry-date" class="field" form="theform" size="20" wsformat="dddd, MMMM d, yyyy"><p> Keywords: <select size="1" name="urn:schemas-microsoft-com:office:office#Keywords" class="field" form="theform"> <option value="option1">Option 1 </option> <option value="option2">Option 2 </option> </select> <p> Content state: <textarea rows="2" cols="20" name="http://schemas.microsoft.com/exchange/contentstate" class="field" form="theform"></textarea> <p> <input type="hidden" name="DAV:contentclass" value="My_list" form="theform"> <BR> <input type="submit" value="Submit" name="B1"><input type="reset" value="Reset" name="B2"> <input type="hidden" name="http://schemas.microsoft.com/exchange/nosave/hintforurl" value="DAV:isreadonly"> </form> </body> </html>
The first thing you might notice is the ActionSpec attribute on the form. The WSS Forms Renderer takes the ActionSpec attribute and uses it as a template to create the Action attribute. The Action attribute is what occurs after the form is posted. In this example, you see %DataURL%?Cmd=contents . The macro %DataURL% is one of the macros you can use in your WSS Forms. It is automatically expanded by the renderer into the URL to the data item in Exchange. The macros you can use are shown in Table 20-3.
| Macro | Description |
|---|---|
| %FormURL% | The URL to the form being rendered. This can either be a relative or absolute URL, depending on how you registered the form in your form registration. |
| %FormContainer% | This is the URL to the folder containing the form being rendered. |
| %DataURL% | This is the URL to the data item being rendered in the form. |
| %DataContainer% | This is the URL to the folder containing the data item being rendered. |
Creating New Items
One of the most common tasks you will do using WSS Forms is to create new items. To create a new item, you just create a form registration for the folder where you want to create your new item. Be sure to make the ExecuteParameters property in your registration equal to CreateNew . This instructs the WSS Forms Renderer to create a new item rather than update the properties of the folder itself. If you do this, you will notice two things. First, after you create and submit the item, the item is automatically displayed back in the browser. Second, the display name of the item is a long, nasty GUID. Solving both of these problems is easy with WSS Forms.
For the first problem, you will want to use the Redir token. This token is part of your ExecuteParameters property ”or you can put it right into your ActionSpec attribute in your form. For example, the following ExecuteParameter property for a form registration specifies that a new item should be created and then the browser should be redirected to a specific folder:
ExecuteParameter: cmd=CreateNew&Redir=http://server/public/myfolder/
To fix the second problem, the WSS Forms technology provides a way for you to give hints to the renderer on what you want the name of the item to be. You must specify a field on the form to use as the hint ”you do this by adding the http://schemas.microsoft.com/exchange/nosave/hintforurl property on your form. For example, the following HTML specifies the subject of the message to be the hint for the URL. If another item has the same subject, Exchange will add a numbered suffix to the end, as in mymessage-1.eml .
<input type="text" name="urn:schemas:httpmail:subject" value="test"> <input type="hidden" name="http://schemas.microsoft.com/exchange/nosave/hintforurl" value="urn:schemas:httpmail:subject">
Updating Items
The WSS Forms Renderer will automatically update an item if a user modifies any of the values. Just be sure to use the Redir token (which we discussed earlier) to redirect your users to a folder view or another page. Otherwise, they will be stuck viewing the same item over and over again.
Formatting Fields
When working with your fields, you might want to change the way the data is formatted when displayed in the browser. For example, you might want to show a date as a long date or show just the time portion of a date/time field. Instead of forcing you to write code to perform this formatting, the WSS Forms Renderer allows you to add a special attribute to your HTML fields called wsformat . For the wsformat , you pass a format string that specifies the type of data that should be rendered for that field and how you want the data to appear. Table 20-4 lists the format strings, data types, and examples for each format string.
| Format String | Data Type | Example |
|---|---|---|
| "" | String, Multi-valued String | Unformatted text |
| "#,#" | Integer, Real | 1,2345 “1,2345 |
| "#,#.0" | Integer, Real | 1,234.5 “1,234.5 |
| "#,#.00" | Integer, Real | 1,234.56 “1,234.56 |
| "" | Date/Time | 10/1/2001 3:15:43 PM |
| "M/d/yyyy h:mm:ss tt" | Date/Time | 10/1/2001 3:15:43 PM |
| "MMMM d, yyyy" | Date/Time | October 1, 2001 |
| "d-MMM-yy" | Date/Time | 1-Oct-01 |
| "M/d/yyyy" | Date/Time | 10/1/2001 |
| "MMMM yy" | Date/Time | October 01 |
| "M/yyyy" | Date/Time | 10/2001 |
| "h:mm tt" | Date/Time | 3:15 PM |
| "h:mm" | Date/Time | 3:15 |
The following example shows how to use the wsformat attribute:
<input type="text" name="urn:schemas:httpmail:expiry-date" class="field" form="theform" size="39" wsformat="M/d/yyyy h:mm:ss tt">
The XML View Descriptor, which we'll discuss later in the chapter, also uses these format strings.
Dynamic Database Lookups
When you work with the HTML SELECT element, you can have the WSS Forms Renderer look up the values for the element using another folder in Exchange. You can thus avoid hardcoding values into your SELECT elements. This solution also lets you avoid writing code to do this dynamic population. Instead, as you've seen with the rest of the WSS Forms technology, you only have to do some simple HTML markup. For example, say you have a folder called Options that contains items with the options you want to display dynamically in a drop-down list on your HTML form. Let's say the subject of the message is what you want to display for the option in the user interface and that the text of the message is what you really want the value of the option to be when selected and posted to the server. To accomplish your dynamic lookup using WSS Forms, you provide the following HTML:
<select size="1" name="urn:schemas-microsoft-com:office:office#Keywords" class="field" form="theform" values="urn:schemas:httpmail:subject" valuesfolder="/public/options" optionvalues="urn:schemas:httpmail:textdescription">
Now imagine that the Options folder is filled with three messages: Green, Orange, and Blue. Green and Blue have no text and Orange has "This is text" as its text body. When the WSS Forms Renderer displays your drop-down list, this is the HTML it will send to the browser:
<select size="1" name="urn:schemas-microsoft-com:office:office#Keywords" form="theform" values="urn:schemas:httpmail:subject" valuesfolder="/public/options" optionvalues="urn:schemas:httpmail:textdescription"> <option value="This is text">Orange</option> <option value=" ">Green</option> <option value=" ">Blue</option> </select>
Okay. Let's get a little bit more complicated. You might be wondering how to filter which items are returned from the folder that contains your options. Well, you can optionally pass filtersrc and orderby values that tell the WSS Forms Renderer the SQL WHERE filter you want to use and the ORDER BY clause to use, respectively. In our example, say we want to filter only by a certain value such as Orange in the subject and you want those items to be sorted in ascending order by subject. This is what our new form HTML would look like for our SELECT element:
<select size="1" name="urn:schemas-microsoft-com:office:office#Keywords" class="field" form="theform" values="urn:schemas:httpmail:subject" valuesfolder="/public/options" optionvalues="urn:schemas:httpmail:textdescription" filtersrc=""urn:schemas:httpmail:subject" ='Orange'" orderby=""urn:schemas:httpmail:subject" ASC">
Notice that you have to quote your WHERE and ORDER BY clauses using the HTML " . Otherwise, you will get errors from the renderer because your SQL clauses will be formatted incorrectly. Also note that if you have any existing hardcoded OPTION elements in your SELECT element, they will first be rendered by WSS Forms and then your dynamic options will be placed in the SELECT element. Table 20-5 lists the parameters you can use with a SELECT element to make it a dynamically populated element.
| Parameter | Required? | Description |
|---|---|---|
| Values | Yes | Specifies the property with the value to insert for the display name for the OPTION element in your SELECT element |
| valuesfolder | Yes | Specifies the URL to the folder from which the WSS Forms Renderer should pull data to populate the SELECT element |
| Filtersrc | No | Specifies the WHERE clause to apply to the items contained in your valuesfolder parameter |
| optionvalues | No | Specifies the property to use as the value for each of the OPTION elements in your SELECT element |
| orderby | No | An ORDER BY clause to apply to the items contained in your valuesfolder parameter |
EAN: 2147483647
Pages: 227