SPaDevToolkit Core Library Documentation

Overview

The SPaDevToolkit Core Library contains classes used to accelerate the building of custom SharePoint applications. Using these classes, the following reusable components and applications can be built:

SharePoint Business Objects

The Core Library define classes from which to build custom business objects. It also contains utility classes that can be used in conjunction with business objects for simplifying data access. The Core Library can be divided into the following categories:

Controls

The classes in this category are used to build UI components for custom applications

Creating Business Objects for List Items:

	[Serializable]
	public class TripLogListItem : SPaListItem<TripLogListItem>

SPaListItem defines properties that uniquely identify list items including list id and item id. It also includes methods for retrieving, creating, updating and deleting list items.
        private DateTime _TripDate;
        /// <summary>
        /// Date of trip
        /// </summary>
        public DateTime TripDate
        {
            get { return _TripDate; }
            set { _TripDate = value; }
        }
        protected override void SetProperties(Microsoft.SharePoint.SPListItem listItem)
        {
            //Extract list item field values using standard conversion functions defined on the 
	    //SPaFieldConverter class for standard field types
            _TripDate = SPaFieldConverter.GetDateTimeField(listItem, "Trip_x0020_Date");
            o
            o
            o
            o
            base.SetProperties(listItem);
        }

The implementer can use one of many conversion methods defined by the SPaFieldConverter class that retrieve (or set) values from a field in the list and convert to a .NET type suitable for the business object property that represents the field. In the case above, the derived class calls the GetDateTime() method to retrieve a value from the Tripx0020Date field of the list item.
        protected override void SetFields(Microsoft.SharePoint.SPListItem listItem)
        {
            SPaFieldConverter.SetDateTimeField(listItem, "Trip_x0020_Date", _TripDate);
            o
            o
            o
            o
            base.SetFields(listItem);
        }

        protected override void Create()
        {
            _TripDate = DateTime.Now.Date;

            base.Create();
        }


	ListItem = SPaListItem<TripLogListItem>.CreateListItem(new SPaListInfo(_ListID, _WebUrl));

The ListID and WebUrl variables contain the id of the list where the item is created and the Url of the site where the list is located, respectively. These values are usually populated from the current context such as the QueryString variable containing the list id or the SPContext.Current.Web object. CreateListItem() initializes a new instance of the specified business object type and calls the Create() method allowing the business object to perform custom initialization.
ListInfo is a structure that uniquely identifies a list.
	ListItem = SPaListItem<TripLogListItem>.GetListItem(new SPaListInfo(_ListID, _WebUrl), _ItemID);

_ItemID contains the integer id of the item on the list. GetListItem() instantiates an instance of the business object and sets default properties defined by the base class such as LastModifiedDate, CreateDate, etc. GetListItem() then calls SetProperties() (see above) allowing the business object to set properties from fields in the list item it retrives using the SharePoint API.
            o
            o
            ListItem.TripDate = dtTripDate.SelectedDate;
            o
            o            
            ListItem.Save();


The client (a Web Control or Page for example) sets the properties of the business object and calls the Save() method to persist the changes in SharePoint. The Save() method of SPaListItem determines if the business object represents a new item (created using CreateListItem()) or an existing item (created using GetListItem()). Save() calls the SetFields() method allowing the business object to save properties to list item fields. Then, based on whether the object represents a new or existing object, it creates a new list item or updates an existing one using the SharePoint API.

Creating a User Interface to Edit List Items:

By default, every list in SharePoint has forms associated with it that allow users to create new items, view existing items and edit existing items. If these forms are nor explicitly assigned, SharePoint generates controls for list item fields dynamically at run-time. However, the SharePoint object model allows developers to create custom forms and assign them to lists. This allows for the creation of forms with more sophisticated UI presentation and logic that is not avaialble in standard forms (ex. AJAX, 3rd-Party controls, custom controls, etc.). SPaDevToolkit takes advantage of this extension mechanism and supplements it in a way that allows for simple creation of forms targetted for SharePoint.
    public partial class TripLogListControl : SPaListItemFormControl<TripLogListControl, TripLogListItem>


SPaListItemFormControl derives from System.Web.UI.UserControl. This allows derived classes to benefit from the design and run-time capabilities available to User Controls. To create a Form Control, the developer adds a UserControl to a Web Project. By default, the newly created control derives from UserControl. To transform the control into a SPaDevToolkit form control, the developer simply replaces the derivation from UserControl with a derivation from SPaListItemFormControl.

As part of the control class declaration, the developer supplies 2 additional type parameters with the SPaListItemFormControl generic class - TControl and TItem.

TControl is the first type parameter. It specified the type of the control class customer itself. In the example above, this is TripLogListControl. The second type parameter, TItem is the type of the business logic class that manages the business logic for the list item. Together, the control and business object classes work in tandem to define the UI, Business Logic and Data Access Layers of a mult-tier application that manages list items. This is a familiar concept to most developers and therefore simplifies that transition form developing straight ASP.NET interfaces to developing those same interfaces for SharePoint. The difference is that the model provided here hides a lot of the details of interacting with the SharePoint object model and allows the developer to focus on the UI and core Business Logic. [image:TripLogListFormControl.JPG]
        protected override void Page_Load(object sender, EventArgs e)
            //Initialize the list item (ListItem property)
            base.Page_Load(sender, e);

The base class method initializes an instance of the Business Object using the type specified in the Control class declaration. In this case it is TripLogListItem. The base class method does the following:
            dtTripDate.SelectedDate = ListItem.TripDate;
            txtPurpose.Text = ListItem.Purpose;
            txtDescription.Text = ListItem.Description;
            txtTotalMiles.Text = ListItem.TotalMiles.ToString();
            txtExpenses.Text = ListItem.Expenses.ToString();
            try
            {
                if (Page.IsValid)
                {
                    Save();
                    RedirectToParentList(lblErrorMsg);
                }
            }
            catch (Exception ex)
            {
                ShowFormError("Error saving Trip Log item: " + ex.Message, lblErrorMsg);
            }


If page validation passes, the control can save control properties back to the corresponding properties of the business object and persist the business object.
        private void Save()
        {
            ListItem.Description = txtDescription.Text;
            ListItem.Purpose = txtPurpose.Text;
            ListItem.TripDate = dtTripDate.SelectedDate;
            ListItem.MetWith = ppMetWith.CommaSeparatedAccounts.Split(',');
            ListItem.Link = txtRelatedLink.Text;
            ListItem.TotalMiles = string.IsNullOrEmpty(txtTotalMiles.Text.Trim()) ? 0 : decimal.Parse(txtTotalMiles.Text);
            ListItem.Expenses = string.IsNullOrEmpty(txtExpenses.Text.Trim()) ? 0 : decimal.Parse(txtExpenses.Text);
            ListItem.VisitType = (VisitType)Enum.Parse(typeof(VisitType), radVisitType.SelectedValue);
            
            ListItem.Save();
        }

Summary

Above we described the components of the SpaDevToolkit Core library. We also provided the basic steps for creating a List Item Business Object class and corresponding Form Item Control. Together, these classes define the business logic and ASP.NET-based UI for editing list items. See the Simple Form Sample included in the release. The binary release contains a working sample solution that can be deployed and run. The source code release contains the source code for all of the SPaDevToolkit and samples. Enjoy!