Export (0) Print
Expand All

Validating Data Entry Input

October 21, 2011

Your application should perform validation on all user-entered data to help prevent errors.

You Will Learn

  • How to perform validation on Windows Phone.
  • How to check for unsaved changes when the user presses the Back button.

Applies To

  • Silverlight for Windows Phone OS 7.1

    Gg680269.59b49e8a-1449-4d20-88e9-55ea566911a9(en-us,PandP.11).png

Performing Validation

In general, it is useful to constrain the data that users can enter. The following are approaches that can be used to constrain input from the user.

  • Set TextBox properties that constrain input such as the TextBox.MaxLength property.
  • Bind to properties and validate before saving.
  • Use the INotifyDataErrorInfo interface to perform custom validation for your objects.

The INotifyDataErrorInfo interface could be used to implement custom validation of business rules. However, in Fuel Tracker, the first two options were used. First, you

  • Set the TextBox.MaxLength property so that users can enter only the expected amount of text.
  • Set the TextBox.InputScope property so that users can enter only the expected type of data (such as numerical data). For more information, see Using Controls.

Even with these constraints, it is usually still possible to enter values that are incorrectly formatted or invalid for some other reason. Validation requirements often vary, but typically you want to validate data to prevent incorrect values from being saved. In this case, bindings are set directly to the appropriate data classes, which have float properties. On save, the entered values persist only if they can be parsed as floats.

The following code shows the SaveButton_Click event handler in the FillupPage class.

private void SaveButton_Click(object sender, EventArgs e)
{
    CommitTextBoxWithFocus();

    if (string.IsNullOrWhiteSpace(OdometerTextBox.Text))
    {
        MessageBox.Show("The odometer reading is required.");
        return;
    }

    if (string.IsNullOrWhiteSpace(FuelQuantityTextBox.Text))
    {
        MessageBox.Show("The gallons value is required.");
        return;
    }

    if (string.IsNullOrWhiteSpace(PricePerUnitTextBox.Text))
    {
        MessageBox.Show("The price per gallon value is required.");
        return;
    }

    float val;
    if (!float.TryParse(OdometerTextBox.Text, out val))
    {
        MessageBox.Show("The odometer reading could not be converted to a number.");
        return;
    };

    if (!float.TryParse(FuelQuantityTextBox.Text, out val))
    {
        MessageBox.Show("The gallons value could not be converted to a number.");
        return;
    };

    if (!float.TryParse(PricePerUnitTextBox.Text, out val))
    {
        MessageBox.Show("The price per gallon value could not be converted to " +
            "a number.");
        return;
    };
      
    SaveResult result = CarDataStore.SaveFillup(_currentFillup,
        delegate
        {
            MessageBox.Show("There is not enough space on your phone to " +
            "save your fill-up data. Free some space and try again.");
        });

    if (result.SaveSuccessful)
    {
        Microsoft.Phone.Shell.PhoneApplicationService.Current
            .State[Constants.FILLUP_SAVED_KEY] = true;
        NavigationService.GoBack();
    }
    else
    {
        string errorMessages = String.Join(
            Environment.NewLine + Environment.NewLine,
            result.ErrorMessages.ToArray());
        if (!String.IsNullOrEmpty(errorMessages))
        {
            MessageBox.Show(errorMessages,
                "Warning: Invalid Values", MessageBoxButton.OK);
        }
    }
}

If values have been entered into each TextBox, an attempt is made to parse the values into values of type float. If parsing fails, a MessageBox is displayed indicating the failure to the user. If parsing succeeds, the code calls the SaveFillup method, passing it an error callback. This delegate simply displays the error condition in a message box.

If the save is successful, the SaveButton_Click method uses the application-level state dictionary to store a value indicating that a new fill-up has just been saved. Next, the method navigates backward. After the navigation, if the SummaryPage finds the value stored in the state dictionary, it shows the first pivot item so that the user can immediately see the results of the fill-up. Otherwise, the SummaryPage will automatically display whichever pivot item was showing before the navigation to the FillupPage.

In addition, business rule validation is also implemented. For example, new fill-up data is not added to the FillupHistory collection until the user taps the Save button. Before it is saved, however, the user can review the data to make sure it is accurate. When the user taps the Save button, a validation routine performs one last check for mistakes and alerts the user to any issues.

The following code shows a simple validation method used in the Fillup class.

public IList<string> Validate()
{
    var validationErrors = new List<string>();

    if (OdometerReading <= 0)
    {
        validationErrors.Add(
            "The odometer value must be a number greater than zero.");
    }

    if (DistanceDriven <= 0)
    { 
        validationErrors.Add(
            "The odometer value must be greater than the previous value.");
    }

    if (FuelQuantity <= 0) 
    {
        validationErrors.Add("The fuel quantity must be greater than zero.");
    }

    if (PricePerFuelUnit <= 0) 
    {
        validationErrors.Add("The fuel price must be greater than zero.");
    }
            
    return validationErrors;
}

The following illustration shows an example of the message that is displayed when the Save button is tapped and the specified odometer reading is less than the previous value.

Gg680269.28f7f8f1-0f59-45d5-a846-f0e6839ff4c0(en-us,PandP.11).png

This code simply checks the values of the Fillup properties and returns error strings for any invalid values. However, not all of the values being checked are supplied by the user, so some initialization must occur beforehand. Specifically, the distance driven must be calculated by comparing the Fillup.OdometerReading value to the previous odometer reading. However, the current Fillup object does not have access to the previous reading, so this is performed by the CarDataStore.SaveFillup method instead, as shown in the following code.

public static SaveResult SaveFillup(Fillup fillup, Action errorCallback)
{
    var lastReading =
        Car.FillupHistory.Count > 0 ?
        Car.FillupHistory.First().OdometerReading :
        Car.InitialOdometerReading;
    fillup.DistanceDriven = fillup.OdometerReading - lastReading;

    var saveResult = new SaveResult();
    var validationResults = fillup.Validate();
    if (validationResults.Count() > 0)
    {
        saveResult.SaveSuccessful = false;
        saveResult.ErrorMessages = validationResults;
    }
    else
    {
        Car.FillupHistory.Insert(0, fillup);
        saveResult.SaveSuccessful = true;
        SaveCar(delegate { 
            saveResult.SaveSuccessful = false; 
            errorCallback(); });
    }
    return saveResult;
}

The CarDataStore.SaveFillup method accepts a Fillup object to save and an Action delegate for error handling. This method starts by subtracting the previous odometer reading from the current odometer reading and stores the results in the Fillup.DistanceDriven property so that validation can occur in the class. Next, the SaveFillup method calls the Fillup.Validate method and stores the results in a special SaveResult object, which it returns to the caller. If there are no validation errors, the SaveFillup method saves the fill-up and car data. Finally, the SaveFillup method returns the SaveResult object.

Gg680269.note(en-us,PandP.11).gifNote:
Silverlight for Windows Phone provides basic, built-in binding validation through the Binding.ValidatesOnExceptions property, as documented in the Silverlight Data Binding topic. However, the phone versions of the controls do not provide validation templates. To support validation, one option is to re-template the controls to provide your own validation template. For example, you can customize the desktop version of the template provided in the TextBox Styles and Templates topic.

This section describes one approach to validating data entry input, but there are numerous ways to perform validation. For example, Silverlight provides support for complex validation scenarios. For more information, see Data Binding.

Checking for Unsaved Changes When Navigating Backward

By default, pressing the Back button causes backward navigation. If you have a data entry page with unsaved changes and the user presses the Back button, you should inform the user that he is about to lose unsaved data. To handle this scenario, you can override the PhoneApplicationPage.OnBackKeyPress method and check for unsaved changes. If there are unsaved changes, you can inform the user and potentially cancel the backward navigation.

Gg680269.note(en-us,PandP.11).gifTip:
Do not use an OnBackKeyPress override to cancel all backward navigation and entirely replace the Back button behavior. The option to cancel backward navigation is provided in order to perform necessary navigation-related operations such as seeking user confirmation before discarding data. The back button must be used correctly to pass certification. See section 5.2 in the Technical Certification Requirements.

The Fuel Tracker application has two data entry pages: CarDetailsPage and FillupPage. If there are unsaved changes on these pages and the user press Back, a confirmation message is displayed that allows them to cancel the navigation backward. The following illustration shows an example of the confirmation message.

Gg680269.660dc954-1d56-4ea4-a5ce-460a3db7ec99(en-us,PandP.11).png

Gg680269.note(en-us,PandP.11).gifDesign Guideline:
Supply a Cancel button for actions that overwrite or delete data or are irreversible.

The following code shows how Fuel Tracker overrides the PhoneApplicationPage.OnBackKeyPress method to display a confirmation message if there is unsaved data.

protected override void OnBackKeyPress(
    System.ComponentModel.CancelEventArgs e)
{
    base.OnBackKeyPress(e);

    // If there are no changes, do nothing. 
    if (!_hasUnsavedChanges) return;

    var result = MessageBox.Show("You are about to discard your " +
        "changes. Continue?", "Warning", MessageBoxButton.OKCancel);
    e.Cancel = (result == MessageBoxResult.Cancel);
}

First, this method checks whether there are any unsaved changes. If there are none, then the method does nothing and backward navigation occurs automatically. Otherwise, the method displays a confirmation message. If the user taps Cancel, then the backward navigation is canceled. Otherwise, the navigation proceeds normally.


Show:
© 2014 Microsoft