FormFields for ASP.net Documentation

Table of Contents



1 Setup

Table of Contents

1.1 Requirements

  • .Net Framework 3.5
  • AjaxControlToolkit
Table of Contents

1.2 Download

  • Go to CodePlex and download the latest dll; then place it in your project's bin folder and reference it
  • Download the latest AjaxControlToolkit and place it in your bin folder
Table of Contents

1.3 web.config

Go into your web.config file and set up these variables: 
<appSettings>
    <add key="InitialValue" value="please select"/>
    <add key="DataTextField" value=""/>
    <add key="DataValueField" value=""/>
    <add key="DataContext" value="yourDataContext"/>
    <add key="OrderBy" value=""/>
    <add key="ValueSuffix" value=""/>
    <add key="TextSuffix" value=""/>
    <add key="OrderSuffix" value=""/>
    <add key="RequiredErrorMessage" value="required"/>
    <add key="FieldCssClass" value="formField"/>
    <add key="ValidatorCssClass" value="validate"/>
    <add key="FormElementCssClass" value=""/>
    <add key="WatermarkCssClass" value=""/>
</appSettings>
Don't worry if you do not understand a lot of these, more on this later.

Then go to the pages section and add in this reference: 
<controls>
    <add tagPrefix="formField" namespace="Naspinski.Controls.FormFields" assembly="FormFields" />
</controls>

2 Styling

Table of Contents

2.1 Layout

The markup of the controls is as follows: 
<div class="[FieldCssClass]">
    <h3>
        <span class="[ValidatorCssClass]">[Validators]</span>
        <label for="[Input Field]">[Title]</label>
    </h3>
    [Input Field]
</div>

As you can see, it is pretty simple. I prefer to have the Validators come prior to the Title as I float them to the right for a very nice effect. Also, notice that the validators are contained within the h3 element. If you want a different layout, this is all set in the FormField.cs file.

FieldCssClass and ValidatorCssClass are pulled from your web.config.
Table of Contents

2.2 CSS

To get an idea, here is the css I use in the examples: 
body, input { font-family:Arial Black; }
body { color:#444; background:#eee; }
input, textarea, select { color:#333; width:100%; }
input[type='submit'] { width:200px; color:#444; }
input[type='checkbox'],input[type='radio'] { width:auto; }
input[type='radio'] { margin-left:.5em; }
.validate { float:right; }
.formField { width:400px; float:left; padding:.5em; background:#ddd; border:solid transparent; 
    border-width:0 1px 1px 0; border-left:0; }
Table of Contents

2.3 Setting Styles

You can also set css classes when you declare your FormFields:
  • FieldCssClass - the containing div of the whole control - this can be set in the web.config
  • FormElementCssClass - the actual input field (TextBox, CheckBox, etc.)
  • ValidatorCssClass - span wrappers arounf validation - this can be set in the web.config
Also, since the Title is wrapped in an h3, a class was not specified as you can target it with css selectors.

3 DataBinding

Table of Contents

3.1 General

There are some general rules about DataBinding with FormFields that are true throughout the controls, these carry down through using regular DataSources (LinqDataSource, SqlDataSource, etc.) as well as Linq-to-SQL.
3.1.1 Defaults
Most of the variables in the web.config section above have to do with databinding. These are not required, but they will make you markup a lot easier as there will be less redundancy. For example, I structure my tables very similarly: if I have a table named 'category', it will have and INT PRIMARY KEY of 'category_id' and the column I will display is called 'display'. I use this same structure for all of my related child tables, so a table named 'abc' would have the INT PRIMARY KEY of 'abc_id' and display column named 'display'. Let me explain what the variables are that relate to DataBinding (*only used with Linq-to-SQL):
  • InitialValue - the 'empty' value of your DropDownLists
  • DataTextField - what the users see; just like normal ASP.net controls
  • DataValueField - the actual value; just like normal ASP.net controls
  • DataContext* - the name of your DataContext(.dbml)
  • OrderBy* - what column to order your results by
  • ValueSuffix* - suffix to append to the table name to get the value; more on this later, it can be confusing
Now for my examples above, I would set DataTextField to 'display' because that is what I want the user to see, and I set ValueSuffix to '_id' as that is what is appended to the name of the table itself to get the value. Since I set ValueSuffix, I did not need to set DataValueField, but if I would, it would default to that column for values like 'display' did for text. DataValueSuffix can be hard to understand, but if your tables are built in a uniform style, it can save a ton of markup. Now keep in mind that none of these are required and can be over-ridden in the markup itself.

OrderSuffix and TextSuffix work the same way. The *Suffix will only be used if there is not a default set in the web.config and there is nothing set in-line. L2SOrderByColumn has a little different bahavior: if the L2SOrderByColumn is blank it will inherit the default value from the web.config, if that is empty, it will inherit the L2STableName + OrderSuffix, if that is blank, it inherits the DataTextField.
Table of Contents

3.2 Linq-to-SQL

If you look in any of the examples, you can see that this is customized to work with Linq-to-SQL. Once you have the basics down, Linq-to-SQL integration is one of the best features of FormFields - you don't have to bind anything in code-behind or make a single DataSource manually! I have also done some testing with Linq-to-Entities, and it is very simple to port over, I just don't think Linq-to-Entities is as usable a framework yet.

Syntax
The syntax tries to mimic regular ASP.net syntax as closely as possible. If you have the defaults set, this is the very minimum you can get away with: 
<formField:dropDownList ID="ddl" runat="server" L2STableName="category" />

That is very basic, that is assuming I have my DataContext, DataTextField and DataValueField -or- DataValueSuffix filled out in my web.config.

Alternatively, if I want to set everything on the fly and spell everything out, I can do something like this: 
<formField:dropDownList ID="ddl" runat="server" L2SDataContext="myDataContext" L2STableName="category" 
    L2SOrderByColumn="some_other_column" DataTextField="display" DataValueField="category_id" />

Now that will pull the same data as above, but now it will order by the values in the 'some_other_column' column. This should be relatively straight-forward.
Table of Contents

3.2 Regular DataSources

The DataSources you are used to using can also be used as easily as they were before, even easier if you employ the defaults explained above.

Syntax
This should all be very familiar, just make the DataSources like you have in the past - here are some examples: 
<formField:dropDownList ID="ddl" runat="server" DataSourceID="sds" />

This is the absolute minimum you can do if you have the defaults set. You can also specify everything inline: 
<formField:dropDownList ID="ddl" runat="server" DataSourceID="sds" DataTextField="display" 
    DataValueField="category_id" />

4 Controls

Table of Contents

4.1 General

All of the controls have basic properties inherited from the FormFields class which has some basic properties can be set inline in your markup. Specific properties to the specific controls will be covered in their respective sections. None of these are required.

Properties
  • Title - the title that appears inside the h3 tags
  • Required - whether or not this form element is required; ignored for controls such as CheckBox, RadioButton, etc.
  • InitialValue - the 'empty' value for a DropDownList; triggers the RequiredFieldValidator if active
  • RequiredErrorMessage - new error message if you want something other than the default set (or 'required' if nothing is set)
  • FieldCssClass - CSS class assigned to the containing div; has a default setting option in the web.config
  • FormElementCssClass - CSS class assigned to the input field; has a default setting option in the web.config
  • ValidatorCssClass - CSS class assigned to the validators; has a default setting option in the web.config
Table of Contents

4.2 Regular Controls

4.2.1 textBox
TextBox is the most versatile control in the FormFields arsenal. It has all sorts of preset usages and can accomplish almost anything with the simplest of markup. That said, it also has a lot more properties than most.

Properties
  • Text - sets the text but does not get it; you have to access the text through controlName.TextBox.Text
  • TextMode - SingleLine or MultiLine
  • RegEx - putting a RegEx here will automatically insert a RegularExpressionValidator
  • ErrorMessage - Error message to assign to additional validator (no the RequiredFieldValidator)
  • Mask - using this property will automatically mask the TextBox with specified mask; mask documentation
  • MaskType - type of mask; only matters if a Mask is set
  • Input Direction - only matters if a Mask is set
  • DisplayMoney - only matters if a Mask is set
  • WatermarkText - text for a mask; mask is automatically inserted if this property is filled out
  • WatermarkCssClass - CSS class used for the watermark (if there is one)
  • Type - preset usages of Mask and/or RegEx
    • Text - default, nothing special here
    • Integer - only allows integer
    • Money - masks allowing $ amount
    • Email - uses RegEx to validate an email address
    • PhoneNumber - uses RegEx to validate a phone number
    • ZipCode - uses RegEx to validate a zip code
    • Date - validates the date, inserts a calendar popup, and masks a date (defaulted to 'mm/dd/yyyy')
    • SocialSecurityNumber - validates and masks a social security number
For examples of usage, see the textBox page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • TextBox
  • MaskedEditExtender
  • CalendarExtender
  • Comparevalidator
  • CompareValidator
  • RegularExpressionValidator
  • TextBoxWatermarkExtender
Keep in mind that these will not always be initialized if they are not used; for example, if you are using Type="PhoneNumber", the CalendarExtender will not be initialized.
Table of Contents
4.2.2 checkBox
Properties
  • Checked - sets the checked status but does not get it; you have to access value through controlName.CheckBox.Checked
  • AutoPostBack - whether or not the control will post back
For examples of usage, see the checkBox page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • CheckBox
Table of Contents

4.3 DataBindableControls

All of the controls that can be databound also have all the basic properties inherited from the FormFields class , but there are also more that inherit from the DataFormFields class. Specific properties to the specific controls will be covered in their respective sections.

Properties
  • DataTextField - name of column to be shown in the control; may be specified in the defaults
  • DataValueField - name of column to be used as data in the control; may be specified in the defaults
  • DataSourceID - name of DataSource to use
  • L2SDataContextName - the name of your LinqToSQL DataContext (.dbml); may be specified in the defaults
  • L2STableName - name of table to query from; required for Linq-to-SQL usage
  • L2SOrderByColumn - name of SQL column to order by; may be specified in the defaults
More information in the Databinding section. Table of Contents
4.3.1 dropDownList
Properties
  • SelectedValue - sets the SelectedValue of the DropDownList but does not get it; you have to access the value through controlName.DropDownList.SelectedValue; not this will not error out if you feed it a non-existant value
For examples of usage, see the dropDownList page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • ListBox
Table of Contents
4.3.2 listBox
CheckBox is about as simple as it gets, only a couple properties and no validation.

Properties
  • SelectedValue - sets the SelectedValue(s) of the ListBox but does not get them; you have to access them by looping through the controlName.ListBox.Items; not this will not error out if you feed it a non-existant value(s); multiple values are seperated by a semicolon
  • Rows - number of rows, defaults to 4
  • SelectionMode - Multiple or Single, defaults to Single
For examples of usage, see the listBox page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • ListBox
Table of Contents
4.3.3 checkBoxList
Properties
  • SelectedValue - sets the SelectedValue(s) of the CheckBoxList but does not get them; you have to access them by looping through the controlName.CheckBoxList.Items; not this will not error out if you feed it a non-existant value(s); multiple values are seperated by a semicolon
  • RepeatDirection - Vertical or Horizontal, defaults to Horizontal
  • RepeatLayout - Table or Flow, defaults to Table
  • AutoPostBack - whether or not the control will post back
For examples of usage, see the checkBoxList page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • CheckBoxList
Table of Contents
4.3.4 radioButtonList
Properties
  • SelectedValue - sets the SelectedValue(s) of the RadioButtonList but does not get them; you have to access them by looping through the controlName.RadioButtonList.Items; not this will not error out if you feed it a non-existant value
  • RepeatDirection - Vertical or Horizontal, defaults to Horizontal
  • RepeatLayout - Table or Flow, defaults to Table
  • AutoPostBack - whether or not the control will post back
For examples of usage, see the radioButtonList page. There are also controls that you can grab in the code-behind if you need to do further manipulation.

Accessible Controls
  • RadioButtonList
© 2010 Stan Naspinski