This exercise will take you through the steps of creating a multi screen data entry application. You will also implement a simple bit of form validation.
SharePoint Setup
For this application you will need to create a Calendar list named “Activities” with a custom column called “Activity”. This custom column should be a Choice field with some options for a type of activity (ie: “Team Sports”, “Arts and Crafts” etc…).
Design Considerations
Applications built for mobile devices have to take into account the screen size of the mobile device. This make data entry and navigation of more complex data structures somewhat challenging. What we have found is that a wizard approach works very well. Give the users steps to take with smaller bits at a time. This exercise will take you through entering a single list item even though it will take two screens to do so.
Prerequisites
This exercise will be diving right into the code inside QueryList. If you are lost by this concept, have a look and Your First Mobile-Enabled SharePoint Feature and Introduction to QueryList and Event Handling to get caught up.
The Data
So we have a calendar that can store activities by type. We want to create a simple mobile application that allows the user to post an activity to this calendar. We have 7 fields that we want to capture and we want to split those into two screens to make it easier to enter from the mobile device. The fields we will capture are:
· Activity
· Title
· Location
· Description
· Date
· Start Date/Time
· End Date/Time
We also want to require a Title value to be entered, so just keep that in the back of your mind as it will be the validation portion of this exercise.
A Method For Each Screen
You can write your mobile applications however you like. In this exercise we will be splitting our screen building code into separate methods. This will make more sense when you see how validation is going to work.
QueryList()
We want to have a total of 3 screens that a user will see in this application. The first two are for collecting data and the third is to tell them they have successfully added their activity to the calendar. Also notice the validation that we are doing when the user trys to go to the "pick-date" screen.
public override void QueryList(EntreeScopeObject EntreeScope, EntreeListObject output)
{
//- Add a title and set list style to use
output.ListTitle = "Data Entry Exercise";
output.ListStyle = EntreeListStyles.list_groups;
//- We are using a "screen" property to define what screen we are trying to go to
if (EntreeScope["screen"] == "done")
{
//- This is the final method in our application, it writes to the SharePoint list
SubmitScreen(EntreeScope, output);
} else if (EntreeScope["screen"] == "pick-date"){
//- This will attempt to render the second screen to the user
//- If the title was not entered it will send them back to the first screen with an error
if (!EntreeScope.FormProperties.ContainsKey("ActivityTitle") || EntreeScope.FormProperties["ActivityTitle"] == string.Empty)
{
//- The title was not entered so the user will get the first screen again
Screen1(EntreeScope, output);
//- LoadFormData is a helper that will set all the form items to the
//- values that were sent by the user.
output.LoadFormData(EntreeScope);
//- ErrorString will tell the user what they did wrong
output.ErrorString = "Title is Required";
}
else
{
//- Data from the first screen was valid so the user gets the second screen
Screen2(EntreeScope, output);
}
} else {
//- Render the first screen
Screen1(EntreeScope, output);
}
}
Screen1() - The First 4 Data Elements
For the first screen we want to display the Activity dropdown, Title, Location and Description textboxes and a button to go to the next step. We will create this inside a method called Screen1. This method will have the same exact parameters as QueryList (EntreeScopeObject, EntreeListObject) because we will be calling it from QueryList passing those parameters through.
private void Screen1(EntreeScopeObject EntreeScope, EntreeListObject output)
{
//- Need a reference to the list for the Activity column
SPWeb web = SPContext.Current.Web;
SPList Activities = web.Lists["Activities"];
EntreeListGroup lGrp = output.AddListGroup();
lGrp.ListHeader = "New Activity";
//- Using the overload method for AddFormItem that will
//- create the ListItem based on the SharePoint column (only works for simple field types)
EntreeFormItem type = lGrp.AddFormItem("ActivityType", Activities.Fields["Activity"]);
type.Name = "Type";
//- Textbox for entering the title
EntreeTextBox title = lGrp.AddFormItem<EntreeTextBox>("ActivityTitle");
title.Name = "Title";
//- Textbox for entering the location
EntreeTextBox location = lGrp.AddFormItem<EntreeTextBox>("ActivityLocation");
location.Name = "Location";
//- Textbox for entering the description
EntreeTextBox description = lGrp.AddFormItem<EntreeTextBox>("ActivityDescription");
description.Name = "Description";
description.RowCount = 4;
description.TextMode = EntreeTextBox.EntreeTextBoxStyle.MultiLine;
//- ListItem that will serve as the button for going to the next step
EntreeListItemTitle next = lGrp.AddListItem<EntreeListItemTitle>();
next.Title = "Select Date/Time";
//- ClickAction that will take you to the next step
EntreeClickActionObject ca = output.CreateClickAction();
ca["screen"] = "pick-date";
ca.FormSubmit = true;
//- Adding the action to the item
next.SetClickAction(ca);
}
Note: The validation error message is displayed from QueryList in this exercise
Screen2() The Date/Time Elements
The second screen will be where the user can select a date for their activity and start/end times. You will also notice in the ClickActionObject that we are adding all of the form values that were entered on the first screen. These values will be needed to add the list item when the user submits.
private void Screen2(EntreeScopeObject EntreeScope, EntreeListObject output)
{
EntreeListGroup lGrp = output.AddListGroup();
lGrp.ListHeader = "Activity Schedule";
//- TextBox for the date
EntreeTextBox date = lGrp.AddFormItem<EntreeTextBox>("Date");
date.Name = "Date";
//- Dropdown list for the start time.
EntreeDropDownList startTime = lGrp.AddFormItem<EntreeDropDownList>("StartTime");
startTime.Name = "Start Time";
for (int i = 0; i < 10; i++)
{
//- Adding times in one hour increments 8am - 5pm
string time = (8 + i).ToString() + ":00";
startTime.Items.Add(time, time);
}
//- Dropdown list for the end time.
EntreeDropDownList endTime = lGrp.AddFormItem<EntreeDropDownList>("EndTime");
endTime.Name = "End Time";
for (int i = 0; i < 10; i++)
{
string time = (8 + i).ToString() + ":00";
endTime.Items.Add(time, time);
}
//- ListItem that will be the button to submit the activity
EntreeListItemTitle next = lGrp.AddListItem<EntreeListItemTitle>();
next.Title = "Create Activity";
//- Notice how we are adding all of the form data from the previous screen
//- Think of this like ViewState
//- All these values will be needed when saving the list item
EntreeClickActionObject ca = output.CreateClickAction();
ca["screen"] = "done";
ca["ActivityTitle"] = !EntreeScope.FormProperties.ContainsKey("ActivityTitle") ? "" : EntreeScope.FormProperties["ActivityTitle"];
ca["ActivityType"] = !EntreeScope.FormProperties.ContainsKey("ActivityType") ? "" : EntreeScope.FormProperties["ActivityType"];
ca["ActivityLocation"] = !EntreeScope.FormProperties.ContainsKey("ActivityLocation") ? "" : EntreeScope.FormProperties["ActivityLocation"];
ca["ActivityDescription"] = !EntreeScope.FormProperties.ContainsKey("ActivityDescription") ? "" : EntreeScope.FormProperties["ActivityDescription"];
ca.FormSubmit = true;
//- Adding the action to the item
next.SetClickAction(ca);
}
SubmitScreen() - Add the Item to SharePoint
The final step in our data entry wizard is to add the item to SharePoint with all the data that was entered by the user. We are not doing any validation here, but you could certainly attempt to validate the date string or EndTime > StartTime etc...
private void SubmitScreen(EntreeScopeObject EntreeScope, EntreeListObject output)
{
try
{
//- This should all be familiar to you as a SP developer
SPWeb web = SPContext.Current.Web;
web.AllowUnsafeUpdates = true;
SPList Activities = web.Lists["Activities"];
SPListItem newItem = Activities.Items.Add();
//- Values from the first screen are in the Properties of EntreeScope
newItem["Title"] = EntreeScope["ActivityTitle"];
newItem["Activity"] = EntreeScope["ActivityType"];
newItem["Location"] = EntreeScope["ActivityLocation"];
newItem["Description"] = EntreeScope["ActivityDescription"];
//- Values from the second screen are in the FormProperties
newItem["EventDate"] = EntreeScope.FormProperties["Date"] + " " + EntreeScope.FormProperties["StartTime"];
newItem["EndDate"] = EntreeScope.FormProperties["Date"] + " " + EntreeScope.FormProperties["EndTime"];
newItem.Update();
//- Tell the user they were successful
output.ErrorString = "New Activity Successfully Created!";
}
catch (Exception er)
{
output.ErrorString = er.ToString();
}
}
Conclusion
There is a lot of good information crammed into this exercise. You should be able to expand upon the wizard concept and provide very rich data entry applications to mobile users. The one thing that is lacking here is the date picker.... Want a calendar control instead? The next exercise be all about custom controls and we will build a calendar datepicker for the mobile device!