Data Forms – No Problem with Telerik RadControls for WP8

Introduction

Hello everyone and welcome back to the series on “Conference Buddy” an app being written in Windows Phone 8 as well as Windows 8, but before we dig in, let’s take a look at what we have covered:

• Speech Recognition – Allows your end-users to navigate and interact with your app using their voice. This is a very powerful control and I would encourage you to review the blog post I wrote on it as well as the Telerik Picture Gallery sample app.
• MultiResolutionImage –Makes it easy for Windows Phone 8 developers to support images in the various screen resolutions supported in Windows Phone 8.
• DataForm – Is the topic of today’s post and this new component allows you to automatically generate the UI for your input forms, with support for validation and custom layouts.
• Along with many others detailed here.

As stated earlier, in this post we are going to explore the DataForm control provided by Telerik that you can grab now from your account.
You may optionally download the source code here.

Data Forms (or Input Forms) are a way of life – just deal with it!

This is what we have heard since the beginning of Line-of-Business (LOB) XAML applications, if you need to gather data from your user then get ready to drag a TextBlock, TextBox, CheckBox, RadioButton and for so forth onto your designer. After doing that, it is time to name the UI elements and position them where they look nice on the screen. Any additional data validation will need to come from code. If you left out a field, well it is back to the designer as you have to reposition your UI elements into the right Grid.Row or Grid.Column if you are using the Grid layout control. I’m pleased to announce that your life just got a lot easier with DataForms in RadControls for Windows Phone 8.

A Common Layout – How Users are doing it Without RadControls for Windows Phone 8.

Before we take a look at how we implement this in Telerik’s DataForm control, let’s look at how current users are doing it.

The MainPage.xaml for a typical data form may look like the following:

   1: <StackPanel Grid.Row="1" >

   2:             <TextBlock  TextWrapping="Wrap" Text="E-Mail: " Style="{StaticResource PhoneTextSmallStyle}"/>

   3:             <TextBox x:Name="txtEmail" TextWrapping="Wrap" />

   4:             <TextBlock  TextWrapping="Wrap" Text="First Name: " Style="{StaticResource PhoneTextSmallStyle}"/>

   5:             <TextBox x:Name="txtFirstName" TextWrapping="Wrap" />

   6:             <TextBlock  TextWrapping="Wrap" Text="Last Name: " Style="{StaticResource PhoneTextSmallStyle}"/>

   7:             <TextBox x:Name="txtLastName" TextWrapping="Wrap" />

   8:             <TextBlock  TextWrapping="Wrap" Text="Title: " Style="{StaticResource PhoneTextSmallStyle}"/>

   9:             <StackPanel Orientation="Horizontal">

  10:                 <RadioButton x:Name="rdMr" Content="Mr." />

  11:                 <RadioButton x:Name="rdMrs" Content="Mrs." />

  12:                 <RadioButton x:Name="rdMiss" Content="Miss." />

  13:             </StackPanel>

  14:             <TextBlock  TextWrapping="Wrap" Text="Company: " Style="{StaticResource PhoneTextSmallStyle}"/>

  15:             <TextBox x:Name="txtCompany" TextWrapping="Wrap" />

  16:             <TextBlock  TextWrapping="Wrap" Text="Phone Number: " Style="{StaticResource PhoneTextSmallStyle}"/>

  17:             <TextBox x:Name="txtPhoneNumber" TextWrapping="Wrap" />

  18:         </StackPanel>

As you can see, I took the easy way out and just used a StackPanel to put all of my UI Elements in place. Each input field is given a name to reference it in code in order to save the data. The UI looks like what is shown in Figure 1 once complete.

Figure 1: Contact Collector UI Elements generated by XAML.

You can retrieve any of the UI Elements data by calling the {Name.Property} of each control. Again, so far we have seen a lot of XAML and are using built-in styles to position the data properly. What if you could define your UI through a class and have it generate your UI automatically? Well that is where the new DataForm comes into play.

Taking a look at the Telerik Data Form Control in RadControls for Windows Phone 8.

Figure 2: Contact Collect Detail Screen Design

Now that we have seen how to create a data form using plain-ole XAML, let’s examine how to implement it using our control for “Conference Buddy”. Again, we will take a look at a prototype app design for the contact page as shown in Figure 2 (click to enlarge it). As you can see it spans multiple pages, but let’s get started by adding in the first page.

Again, you will need the RadControls for Windows Phone 8 in order to follow along with this tutorial.

Begin by using the RadControls for Windows Phone 8 template and adding references to the following files:

• Telerik.Windows.Controls.Primitives (Added by Default)
• Telerik.Windows.Core (Added by Default)
• Telerik.Windows.Controls.Input (You will need to add manually)

We are going to use the DataForm to automatically generate our UI in our app, so let’s begin by adding a class to this project to collect contact details. As you can see from the screenshot, the contact details on the first page consist of: E-mail, First Name, Last Name, Title, Company and Phone Number. You can name the class Contact and we will add the other fields later. The code that is contained in this file looks like the following:

   1: using System;

   2: using System.Linq;

   3:  

   4: namespace ContactDetailsWP8

   5: {

   6: public class Contact

   7:     {

   8: private string email;        

   9: private string firstName;

  10: private string lastName;

  11: private UserTitle title;

  12: private string company;

  13: private string phonenumber;

  14:  

  15: public enum UserTitle

  16:         {

  17:             Mr,

  18:             Mrs,

  19:             Miss

  20:         }

  21:  

  22: public string Email

  23:         {

  24:             get

  25:             {

  26: return this.email;

  27:             }

  28:             set

  29:             {

  30: this.email = value;

  31:             }

  32:         }

  33: 

  34: 

  35: public string FirstName

  36:         {

  37:             get

  38:             {

  39: return this.firstName;

  40:             }

  41:             set

  42:             {

  43: this.firstName = value;

  44:             }

  45:         }

  46:  

  47: public string LastName

  48:         {

  49:             get

  50:             {

  51: return lastName;

  52:             }

  53:             set

  54:             {

  55:                 lastName = value;

  56:             }

  57:         }

  58:  

  59: public UserTitle Title

  60:         {

  61:             get

  62:             {

  63: return title;

  64:             }

  65:             set

  66:             {

  67:                 title = value;

  68:             }

  69:         }

  70:  

  71: public string Company

  72:         {

  73:             get

  74:             {

  75: return this.company;

  76:             }

  77:             set

  78:             {

  79: this.company = value;

  80:             }

  81:         }

  82:  

  83: public string PhoneNumber

  84:         {

  85:             get

  86:             {

  87: return phonenumber;

  88:             }

  89:             set

  90:             {

  91:                 phonenumber = value;

  92:             }

  93:         }

  94:  

  95:     }

  96:  

  97: }

In this class, we have defined the same fields shown in Figure 1.

Taking a look at our MainPage.xaml

Our UI is simply going to contain the DataForm control and that is it. Let’s go ahead and add the proper XML namespace as shown below:

   1: xmlns:telerikInput="clr-namespace:Telerik.Windows.Controls;assembly=Telerik.Windows.Controls.Input"

This is all that is needed to allow us to reference this control in XAML.

Let’s go ahead now and replace the existing Grid with the following code snippet.

   1: <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">

   2: <telerikInput:RadDataForm

   3: EditorCreationMode="CreateByDefault"

   4: x:Name="radDataForm"/>

   5: </Grid>

The EditorCreationMode property is used to define how RadDataForm creates editors for the public properties of the business object assigned as CurrentItem (which we will set in our code-behind momentarily). You have two options to choose from:

• The CreateByDefault option implies that editors for each public property will be created unless the property is merged with the IgnoreAttribute.
• The IgnoreByDefault option implies that editors for each public property are created as long as the property is marked with the FormFieldAttribute.

We are obviously going to the “CreateByDefault” option to generate our UI.

Switching back to our MainPage.xaml.cs File.

We will need to add in the following code to set the CurrentItem property of the DataForm.

   1: Contact _contact = new Contact();

   2:  

   3: public MainPage()

   4: {

   5:     InitializeComponent();

   6: this.radDataForm.CurrentItem = _contact;

   7: }

Now that that is complete, we can see our new UI when the application launches.

As you can see, it automatically generated our UI based off of the class we instantiated. But, you may want to edit the field names as right now the “FirstName” needs a space between it or maybe you want to reorder the layout and put Company under the Last Name. This could be easy accomplished by adding the “FieldInfo” attribute to the class and subscribing to the DataFieldCreated event on the DataForm. An example of each is shown below:

FieldInfo Attribute

   1: [FieldInfo(FieldHeader = "First Name")]

   2: public string FirstName

   3: {

   4:     get

   5:     {

   6: return this.firstName;

   7:     }

   8:     set

   9:     {

  10: this.firstName = value;

  11:     }

  12: }

DataFieldCreated Event

   1: private void radDataForm_DataFieldCreated_1(object sender, Telerik.Windows.Controls.DataFieldCreatedEventArgs e)

   2:         {

   3: switch (e.AssociatedField.PropertyKey)

   4:             {

   5: case "Email":

   6:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 0);

   7: break;

   8: case "FirstName":

   9:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 1);

  10: break;

  11: case "LastName":

  12:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 2);

  13: break;

  14: case "Title":

  15:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 4);

  16: break;

  17: case "Company":

  18:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 3);

  19: break;

  20: case "PhoneNumber":

  21:                     Grid.SetRow(e.AssociatedField.AssociatedDataField, 5);

  22: break;

  23:             }

  24: }

As you can see, I switched the Company and Title around with the associated PropertyKey.

As they say in the infomercials, but that’s not all! You can also create the data fields in XAML to build more complex UIs (for example a First and Last Name on the same line), and a slew of other Attributes exist such as the following:

• IgnoreAttribute - omits the creation of an editor for the property on which it is defined in case the EditorCreationMode property of the form is set to CreateByDefault.
• FormFieldAttribute - instructs RadDataForm to create an editor for the property on which it is defined in case the EditorCreationMode property of the form is set to IgnoreByDefault.
• PasswordAttribute - used for string properties only. Instructs RadDataForm to create a RadPasswordBox based editor for the property.
• ValidatorAttribute - used to define a validator for the property.
• BooleanEditorTypeAttribute - used to define the type of the editor for a boolean property. There are two supported types currently - RadToggleSwitch or a CheckBox.
• DateTimeEditorTypeAttribute - used to define the editor type for a DateTime property.
• ValueRangeAttribute - used to define a value range for the editor for the corresponding property. Not all property types support this. Supported types are DateTime, TimeSpan, and Numeric.

After you are ready to save the data you simply call:

   1: radDataForm.Commit();

You could then access these properties by calling _user.{Property Name} as shown below:

   1: MessageBox.Show("First Name : " + _contact.FirstName + Environment.NewLine + "Last Name : " + _contact.LastName);

Conclusion

We have seen just how easy it is to use Telerik’s RadControls for Windows 8 to make Data Forms a piece of cake. With all of the additional attributes and features of this control, this will make laying out input forms a thing of the past. You may go ahead and grab the source code to this project to take a look at it for yourself. I know I’ve said it in my last 2 blog posts but, the Nokia premium developer program allows you to get RadControls for Windows Phone for free. They also have a vast variety of resources available to help you get your next app into the marketplace. So, what are you waiting for! Grab the bits and get started.

Thanks for reading!

-Michael Crump (@mbcrump)