Sharepoint WebControl Part II : Creating Custom OWS Control for Webpart

English:
(This articles has already been posted in www.msd2d.com. Now I post it again in my own blog.)

The first part of this series discuss how to reuse OWS controls from Sharepoint.WebControls. Strictly speaking, there are few steps to employ them in webpart; first, create OWSForm as field containers; second, add OWS * Field controls to the form; next submit the form either using OWSSubmit control or your own control and finally collect the value from POST value collections.

In fact, that Sharepoint.WebControls only define 2 ows field; dateField and numberField - which is far from our expectation. However if you keen to browse OWS.JS (the default javascript’s include in Sharepoint), then you’ll find that there are many other OWS inputs around such as URLField, BooleanField, NoteField, RichTextField, TextField etc. (Figure-1). Obviously, those input are just common input type found in HtmlControls of ASPNET or HTML basic tag. The OWS provides uniform appearance and finer user interface - such as the one we found in date picking tools of DateField or formatting tab of RichTextField etc. So our discussion here is to create the first custom OWS control, using available objects in OWS.JS scripts. For sake of simplicity and cleared purpose, I will take a simple example the TextField - giving you the methodology to create your own OWS*Field control and leaving the other field for you to implement.

Figure-1. Many OWS field object doesn’t has correlated webcontrols.

The Base Class: OWSControl

Remember that every OWS * Field control we made must be glued properly to the form (OWSForm) (Part I). To enable this operation our control must recognize its parent - therefore we also expect that our control will determine its parent form automatically. The OWSControl has this kind of operation, so we can make it as the base class and inherit our control from it. Inheriting from OWSControl also assemble correct OWS control hierarchy (Part I).
At last for the class, since we are going to post data through POST value collection, we also need to implement System.Web.UI.IPostBackDataHandler interface.

public class OWSTextField : Microsoft.SharePoint.WebControls.OWSControl, IPostBackDataHandler

Confirm Field Definition in OWS.JS

Basically the new control renders javascript function for specified field as defined in OWS.JS. The javascript object and function has been assembled by Microsofts, so we must verify the parameters in the script objects definition. For example, figure-2 shows how TextField function was defined in OWS.JS - which will be rendered by our control.

Figure-2. Consult OWS.JS for desired field object

As we can see there are 6 fields need to be defined - with an additional “Required” flags :

1. frm is parent form name (the form container)
2. stName is current field name (the object’s field name)
3. stDisplay is display name for current field
4. stValue is value for current field
5. cchMaxLength is maximum character for the field
6. cchDisplaySize is textbox size
7. Required flag as an additional field required information
   

Parent form name (1) can be obtained from the base class property “ParentOWSForm.Name”. The current field name (2) must be uniquely defined. Since, our control’s grandfather is WebControl we can get “UniqueID” from current control. And the rest of parameters (3-7) will be our control’s field.

Next Implement LoadPostData

LoadPostData is one of default contract when we implement IPostBackDataHandler interface. In this function we can implement a procedure to check whether the postback value collections contains our parameters and put the value in current control’s Value field.

public bool LoadPostData(string postDataKey, NameValueCollection postCollection) {
string text1 = postCollection[postDataKey];
if (((text1 != null) && (text1 != “”)) && (text1 != this.Value)) {
this.Value = text1;
return true;
}
return false;
}

Finally, Override Render Method

Overriding render method is simple since you only need to construct javascript object for the field and call BuildUI() function of the object.

Summary

To take the advantage of uniform appearance and finer user interface for all input - we can use the OWS.JS field objects.
Using those fields object can be as simple as rendering javascript to construct the object and then terminated by calling its BuildUI() function.

Technorati : Sharepoint