# HTML Forms in Razor Pages
In the following discussion, the samples include both the HTML/Razor and C# portions as used in Razor Pages. Follow the links for more in-depth information on each section.
# HTML Form Basics
- Form element
- GET vs POST
- Buttons
- button vs input button
# Model-Binding Basics
Binding to the page's model property is performed by adding a C# [BindProperty]
decoration on the
the asp-for
attribute.
# Capturing User-Generated Information
Primitive information falls into three categories: Textual, Numeric, and Conceptual.
# Textual Information
Capturing textual input in a form can be done in the following ways.
Kind | Element/Type | Sample |
---|---|---|
Multi-line | <textarea> | |
Single-line | <input type="text" | |
Password | <input type="password" | |
<input type="email" | ||
URL | <input type="url" | |
Telephone | <input type="tel" |
# Multi-Line Text
<textarea>
allows for longer textual input, including new-line characters. You can constrain the length of the input using the maxlength
and minlength
attributes.
<textarea rows="5" cols="120" asp-for="LongerText"></textarea>
[BindProperty]
public string LongerText { get; set; }
# Short Single-Line Text
This is the default type for the
<input />
element.
The most commonly used type of input, type="text"
version of <input>
is intended for short text. Again, you can constrain the length of the input using the maxlength
and minlength
attributes.
<input type="text" asp-for="StringProperty" />
[BindProperty]
public string StringProperty { get; set; }
# Password
If you want to protect the user's input from over-the-shoulder spying, the type="password"
version of <input>
<input type="password" asp-for="NotSoSecret"/>
[BindProperty]
public string NotSoSecret { get; set; }
The type="email"
input type provides automatic validation for properly formatted email addresses using only the most simplistic expectations.
<input type="email" asp-for="Contact"/>
[BindProperty]
public string Contact { get; set; }
# URL
The type="url"
input type provides automatic validation for properly formatted web addresses.
<input type="url" asp-for="CompanyWebsite"/>
[BindProperty]
public string CompanyWebsite { get; set; }
# Telephone
The type="tel"
input type is often useful for mobile browsers because the mobile device can render a numeric keypad for more intuitive input. It does not provide any automatic filtering or validation of input (you can type letters into the textbox), but you can specify a format using the pattern
attribute.
<input type="tel" pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" asp-for="HomePhone"/>
[BindProperty]
public string HomePhone { get; set; }
# Numeric Information
The type="number"
version of the <input>
element is used to constrain user input to numeric values. By default, it only accepts whole numbers, but that can be changed through using the step
attribute, as shown in the following examples. You can also use the min
and max
attributes to define the lower and upper limits (inclusive) for accepted values.
<label>Enter a Whole Number
<input type="number" asp-for="WholeNumber" />
</label>
<label>Enter a Real Number (to three decimal places)
<input type="number" step=".001" asp-for="RealNumber" />
</label>
<label>Enter a cash amount (Canadian)
<input type="number" step=".05" asp-for="Money" />
</label>
[BindProperty]
public int WholeNumber { get; set; }
[BindProperty]
public double RealNumber { get; set; }
[BindProperty]
public decimal Money { get; set; }
The type=range
version of the <input>
element can also be used for numeric input. Browsers typically render these as sliders.
<label>Rate your confidence in understanding numerical inputs
<input type="range" min="0" max="100" step="10" asp-for="PercentConfident" />
</label>
[BindProperty]
public int PercentConfident { get; set; }
# Conceptual Information
HTML 5 offers various controls for capturing what could be considered "conceptual" information. Generally speaking, there are four conceptual types of information the user can enter.
- Temporal - Information that is date and/or time related.
- Selections - Selecting from a set of items; these include drop-downs, checkboxes and radio buttons.
- Colors - Color information can be expressed in a number of different ways.
- Files - Users can upload files of various types to the web server.
# Temporal Information
The date and time input types for HTML are based on the Gregorian Calendar.
Working with date/time information in programming can be … complex. We can easily get them wrong.
Normally when we think of date and time information in C#, we think of the DateTime
data type. There are three HTML 5 data types that translate cleanly to the C# DateTime
: type="date"
, type="datetime-local"
and type="datetime"
(this last one is being deprecated). The type="month"
can also be translated to the C# DateTime
, but the day portion will default to the first of the month.
(Note: There will be new date and time datatypes in .NET 6 that should help.)
A lesser-known type in C# is the TimeSpan
, which nicely handles the type="time"
input from HTML.
One HTML 5 temporal input types that does not cleanly translate into a C# type is the type="week"
. For this, you should use a string
data type in C# and parse it to obtain the week and year portions.
One library to help with using dates and times in C# is NodaTime.
Review the Microsoft documentation for more about the C# DateTime
data type. Here are some additional resources for you to learn more about coding with date/time based data.
# Input type="date"
The `type="date" input type captures a specific day.
<input type="date" asp-for="ProjectDueDate" />
You can bind this type of HTML input to the DateTime
type in C#. Note that when the data is parsed, the time portion will be set to midnight (00:00.000).
[BindProperty]
public DateTime ProjectDueDate { get; set; }
# Input type="datetime-local"
The `type="datetime-local" input type captures a specific date and time.
<input type="datetime-local" asp-for="Appointment" />
You can bind this type of HTML input to the DateTime
type in C#. The HTML captures the time information to the minute (meaning that the milliseconds portion of the C# type will be zero).
[BindProperty]
public DateTime Appointment { get; set; }
# Input type="month"
The `type="month" input type captures only the year and month information.
<input type="month" asp-for="RentalPeriod" />
You can bind this type of HTML input to the DateTime
type in C#. Note that the day portion will default to the first day of the month and the time portion will default to midnight.
[BindProperty]
public DateTime RentalPeriod { get; set; }
# Input type="time"
The `type="time" input type captures time information only.
<input type="time" asp-for="ClassStartTime" />
You can bind this type of HTML input to the TimeSpan
type in C#. The HTML captures the time information to the minute (meaning that the milliseconds portion of the C# type will be zero).
[BindProperty]
public TimeSpan ClassStartTime { get; set; }
# Input type="week"
The `type="week" input type captures the week number of a particular year.
<input type="week" asp-for="FirstWeekOfSchool" />
The best C# data type to capture this is the string
data type. You can parse the string based on the -
delimiter, in which case the first portion will be the year and the second will be the week number (prepended with a W
).
[BindProperty]
public string FirstWeekOfSchool { get; set; }
# Selectable Information
- Selections (select, radio, checkboxes)
# select
/option
Elements
The drop-down control (<select>
) is typically used to choose a single item from the set of offered options. Unless otherwise specified, the selected option is the first <option>
element in the selection.
<select asp-for="EducationLevel">
<option value="">[Select a level]</option>
<option>Doctoral</option>
<option>Post-Graduate</option>
<option>Post-Secondary</option>
<option>High School</option>
<option>None</option>
</select>
Note that in each option, the selected value will be a string. The first option associates an empty string with the "[Select a value]" selection. If no explicit value
attribute is assigned to an <option>
, then the text inside the <option>
element is the value used when selected.
[BindProperty]
public string EducationLevel { get; set; }
If you use numeric values, you can bind the selection to an int
, as in the following example.
<select asp-for="EducationLevel">
<option value="0">[Select a level]</option>
<option value="5">Doctoral</option>
<option value="4">Post-Graduate</option>
<option value="3">Post-Secondary</option>
<option value="2">High School</option>
<option value="1">None</option>
</select>
[BindProperty]
public int EducationLevel { get; set; }
# Input type="radio"
Radio buttons typically appear in sets of two or more, since they represent an exclusive selection between various options.
<label><input type="radio" name="EmploymentStatus" value="FullTime-Permanent" />Full-Time (permanent)</label>
<label><input type="radio" name="EmploymentStatus" value="FullTime-Contract" />Full-Time (contract)</label>
<label><input type="radio" name="EmploymentStatus" value="PartTime-Permanent" />Part-Time (permanent)</label>
<label><input type="radio" name="EmploymentStatus" value="PartTime-Contract" />Part-Time (contract)</label>
[BindProperty]
public string EmploymentStatus{get;set;}
# Input type="checkbox"
The checkbox is a control that exists nicely by itself or as a group of checkboxes. When used by itself, you can simply bind it to a bool
property in the page model.
<input type="checkbox" asp-for="AcceptTerms" /> I accept the terms
The checkbox control can have an attribute of checked
, either with or without a value for the attribute, in order to "check" the box.
<input type="checkbox" asp-for="AcceptTerms" checked /> I accept the terms
The above checkboxes can be bound as follows.
[BindProperty]
public bool AcceptTerms { get; set; }
When working with a group of checkboxes, you cannot use the asp-for
attribute because there is no single variable to associate each checkbox with. Rather, you should explicitly set the name
and value
attributes of each checkbox.
<label><input type="checkbox" name="Course" value="Math 30" />Math 30</label>
<label><input type="checkbox" name="Course" value="Math 31" />Math 31</label>
<label><input type="checkbox" name="Course" value="English 30" />English 30</label>
<label><input type="checkbox" name="Course" value="English 31" />English 31</label>
<label><input type="checkbox" name="Course" value="Physics 30" />Physics 30</label>
<label><input type="checkbox" name="Course" value="Chemistry 30" />Chemistry 30</label>
You can then bind the results to an array of strings.
[BindProperty]
public string[] Course { get; set; }
Alternatively, if you had set the value
attributes to whole numbers, you could bind to an array of integers.
For more information on working with binding to collections, see the following article on Binding Simple Collections.
# Color Information
Color information can be obtained using the color picker supplied by most modern browsers.
<input type="color" asp-for="PrimaryColor" />
The color value will be expressed as a six-digit hex number (e.g. #472dc8
).
[BindProperty]
public string PrimaryColor { get; set; }
# File Uploads
Uploading files requires additional information on the <form>
element.
The input type is file
, and the data type used for binding is the IFormFile
interface in the Microsoft.AspNetCore.Http
namespace.
<input type="file" asp-for="Avatar" />
[BindProperty]
public IFormFile Avatar {get;set;}
For more information on processing file uploads, see the "Uploading Files in Razor Pages" article.