SPaDevToolkit Core Library Documentation

Overview

• SharePoint Business Objects - These are like traditional business objects that contain business rules and access data access objects to store and retrieve data from an underlying data store. The difference is these objects are geared toward manipulation of SharePoint content such as lists items that have the SharePoint content database as the backend data store.
• Controls - These are the UI components of custom applications that include the management of list items as a core feature. These controls are tightly integrated with List Item Business Objects to simplify the management of list items.

SharePoint Business Objects

• List Item Business Objects - Base classes for defining business objects that manipulate list items
• Data Access - Classes used to access various type of list item fields and convert between common SharePoint field types and .NET types.

Controls

• Form Controls - Classes used to create SharePoint forms, ex. List item forms.
• Pages - Classes used to build various type of SharePoint pages that contain custom logic

Creating Business Objects for List Items:

• List Item Business Objects classes are created by deriving from SPaListItem which is defined in the core library:

	[Serializable]
	public class TripLogListItem : SPaListItem<TripLogListItem>

• Derived classes add custom logic by first defining properties that represent the custom columns of the list the business object represents. For example, the TripLogListItem class whose declaration is shown above defines a property called TripDate that records the date of trip. There is a date column in a SharePoint list that corresponds to this property:

        private DateTime _TripDate;
        /// <summary>
        /// Date of trip
        /// </summary>
        public DateTime TripDate
        {
            get { return _TripDate; }
            set { _TripDate = value; }
        }

• The derived class overrides the SetProperties() method to set custom properties given a SPListItem object retrieved by the base class:

        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);
        }

• In a corresponding manner, the derived class overrides the SetFields() method of SPaListItem to set list item fields using property values. SetFields() is called by the base class when the business object is being saved.

        protected override void SetFields(Microsoft.SharePoint.SPListItem listItem)
        {
            SPaFieldConverter.SetDateTimeField(listItem, "Trip_x0020_Date", _TripDate);
            o
            o
            o
            o
            base.SetFields(listItem);
        }

• When a list item is created the Create() method of SPaListItem is called. The derived class overrides this method to perform initialization or other business logic:

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

            base.Create();
        }

• Create a new list item - To create a new list item, the client using the business objects uses code similar to the following:

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

• Get an existing list item - To retrieve an existing list item, the client uses code similar to the following:

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

• Save a list item - To save a list item, the client using the business objects uses code similar to the following:

            o
            o
            ListItem.TripDate = dtTripDate.SelectedDate;
            o
            o            
            ListItem.Save();

Creating a User Interface to Edit List Items:

• Create a Form Control - A Form Control encapsulates the entire presentation and logic for managing a list item. A form control inherits from SPaListItemFormControl.

    public partial class TripLogListControl : SPaListItemFormControl<TripLogListControl, TripLogListItem>

• Developing the Control Presentation - Create the presentation for a form control is just like creating any other Web UserControl. A snapshot in Visual Studio 2008 design mode of the sample control we use in this document is illusrated below:

• Developing the Control Logic
  • Page_Load() - The derived control should override the Page_Load() event method:

        protected override void Page_Load(object sender, EventArgs e)

• The first call inside Page_Load() should be to the overriden base class method:

            //Initialize the list item (ListItem property)
            base.Page_Load(sender, e);

• Parses the QueryString to determine the context of the form, including the form mode (i.e. New, Display, Edit) and the identity of the list and list item. The identity of the list and list item are passed in the QueryString by SharePoint.
• Instantiates the Business Object. On initial load the Business Object is instantiated using SPaListItem.CreateListem() or SPaListItem.GetListItem() depending on whether the form mode is for a new item or not. On PostBack, the method retrieves the Business Object from ViewState where it is saved during the initial load. The Business Object is saved to the ListItem property of the base class and is available to the derived class on return from Page_Load().

• Back in the derived control's Page_Load() method, the control can then set control properties using properties of the Business Object saved in ListItem.

            dtTripDate.SelectedDate = ListItem.TripDate;
            txtPurpose.Text = ListItem.Purpose;
            txtDescription.Text = ListItem.Description;
            txtTotalMiles.Text = ListItem.TotalMiles.ToString();
            txtExpenses.Text = ListItem.Expenses.ToString();

• Save Logic - Other than setting control properties as shown above, at a minimum the control should define logic for saving the list item when the user clicks OK.

            try
            {
                if (Page.IsValid)
                {
                    Save();
                    RedirectToParentList(lblErrorMsg);
                }
            }
            catch (Exception ex)
            {
                ShowFormError("Error saving Trip Log item: " + ex.Message, lblErrorMsg);
            }

        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