phdcc.Data DNN modules
  search
Powered by FindinSite-MS
phdcc.Data.Form: Questions
phdcc.Data: Overview Examples Getting Started Security Database Versions
phdcc.Data.Form: Form Profile/Register forms Form editing Languages Layout Questions Form hooks Admin
phdcc.Data.View: View  phdcc.Data.List: List phdcc.Data.Search: Search
Last updated: CC 25/4/09
Question types
int
text
email
multilinetext
radiobuttons
checkboxes
country
currency
file image
captcha
button
hiddenfield
control

Overview

This page describes how to create a form question, ie specify:

Result values

For all question types, the result is stored as a string. All results have whitespace characters trimmed from both ends of the string before validation and storing.

Validation

Each question performs validation according to its type, eg an email is checked against a (hard-coded) regular expression. If a question is not Required and the user enters no text, then no validation occurs. Each question has various (optional) options that concern validation, eg the RangeMax option for an int question determines the maximum integer number value that is accepted.

For the text and multilinetext question types (and the specify options of radiobuttons/checkboxes) any HTML in angle brackets will not be allowed unless the HTML_OK special option is set to true. For all other question types that use a text box, any HTML will silently be stripped out.

Special Default Values

The following special question Default values pick up defaults from the user's DNN profile (if a user is logged in):

=UserInfo.Email
=UserInfo.DisplayName
=UserInfo.Profile.FirstName
=UserInfo.Profile.LastName
=UserInfo.Profile.Unit
=UserInfo.Profile.Street
=UserInfo.Profile.City
=UserInfo.Profile.PostalCode
=UserInfo.Profile.Region
=UserInfo.Profile.Country

Ordinary question options

For radiobuttons, checkboxes etc, one or more question options must be provided, eg to provide the radio button options. You can just supply one option if you wish.

Forms with radiobuttons and checkboxes questions often require an "Other" option, eg "Mr", "Ms/Mrs" or "Other". For these question types, if you tick the Specified by user parameter for an option, then a text box for the user to fill in is shown beside this option.

Special question options

For various question types, one or more special options can be provided, eg the columns option specifies the display size of text boxes. The special options available are listed for each question type below.


Question dependencies

In some cases, you may want to make a question required only if another question has been answer true. For example, if the question "Do you charge?" is answered 'yes', then the following question "How much?" is required. This effect is achieved using dependencies.

The following dependency parameters are all required:

As an example, suppose the radiobuttons question "Do you charge?" with id 'idCharge' has two options with ids 'idYes' and 'idNo'. To make the following currency question required if 'idCharge' has answer 'idYes', make a dependency for this question as follows:

If a dependency depends on a radiobuttons or checkboxes question, and the selected option is Specified by user, then the Comparison value is the Option id, not the actual value entered by the user.


Question Types

int

The int question type lets the user enter an integer number. The control is rendered as a text box.

Name Values Default Description
Special options: columns <integer> column count
RangeMin <integer> Minimum acceptable value
RangeMax <integer> Maximum acceptable value
CssClass <string> CSS class

The int question type is rendered as a text area with CSS class phdcc_Form_Question_Int. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerNotAnInteger The answer could not be converted into an Int32 "Answer not a number or number too big"
idAnswerOutOfRange Value not between RangeMin and RangeMax "Answer not in range {0:d} to {1:d}"

text

The text question type lets the user enter a single line of text. The control is rendered as a text box.

Name Values Default Description
Special options: columns <integer> column count
RangeMin <integer> Minimum field length
RangeMax <integer> Maximum field length
HTML_OK <bool> Text box accepts HTML
CssClass <string> CSS class

The text question type is rendered as a text area with CSS class phdcc_Form_Question_Text. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerBadLength Length not between RangeMin and RangeMax "Answer should have length between {0:d} and {1:d}"
idAnswerBadUsername If the question is linked to the DNN property Username, then check the characters are suitable "Answer is not a valid Username: use alphanumeric, underscore and hyphen characters."
idAnswerHTMLFail Answer contains script code or text with < angle brackets > "Answer cannot contain any HTML or script code"

email

The email question type lets the user enter an email address. The control is rendered as a text box. The result is checked against this regular expression: \b[a-zA-Z0-9._%-+']+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,4}\b

Name Values Default Description
Special options: columns <integer> column count
RangeMin <integer> Minimum field length
RangeMax <integer> Maximum field length
CssClass <string> CSS class

The email question type is rendered as a text area with CSS class phdcc_Form_Question_Email. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerBadLength Length not between RangeMin and RangeMax "Answer should have length between {0:d} and {1:d}"
idAnswerBadEmail Answer does not look like an email address "Answer is not an email"

multilinetext

The multilinetext question type lets the user enter several lines of text. The control is rendered as a multi-line text box.

Name Values Default Description
Special options: columns <integer> column count
rows <integer> Row count
RangeMin <integer> Minimum field length
RangeMax <integer> Maximum field length
HTML_OK <bool> Text box accepts HTML
CssClass <string> CSS class

The multilinetext question type is rendered as a text area with CSS class phdcc_Form_Question_MultiLineText. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerBadLength Length not between RangeMin and RangeMax "Answer should have length between {0:d} and {1:d}"
idAnswerHTMLFail Answer contains script code or text with < angle brackets > "Answer cannot contain any HTML or script code"

radiobuttons, checkboxes

The radiobuttons and checkboxes question types let the user make selections from a radio button or checkbox list.

The actual list is obtained from the supplied options. Each option must have a unique Option id. The options are ordered in ascending Option order sequence. If Checked is ticked, then this option is selected by default. If Specified by user is ticked, then a text box is provided for a user-provided answer.

Name Values Default Description
Special options: HTML_OK <bool> Specify text box accepts HTML
CssClass <string> CSS class

The radiobuttons/checkboxes question type is rendered as RadioButtons/CheckBoxes elements with CSS class phdcc_Form_Question_Selector; any user-specified options are rendered as a text box with CSS class phdcc_Form_Question_Selector_Specify. If special option CssClass is specified then all these elements instead use the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerHTMLFail Answer contains script code or text with < angle brackets > "Answer cannot contain any HTML or script code"

country

The country question type lets the user choose a country or countries. If single selection and rows==1 then the control is rendered as a DropDownList; otherwise it is rendered as a ListBox. The country list is built from DNN's standard list of countries, prefixed by the special string idCountryNotSpecified which defaults to "Not specified".

Name Values Default Description
Special options: rows <integer> row count
SelectionMode single | multiple single selection mode
CssClass <string> CSS class

The country question type is rendered as a DropDownList or ListBox with CSS class phdcc_Form_Question_Country. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"

currency

The currency question type lets the user enter a currency value in a text box. The following rules describe the validation process:

Name Values Default Description
Special options: columns <integer> column count
RangeMin <integer> Minimum acceptable value (integer)
RangeMax <integer> Maximum acceptable value (integer)
CurrencyDigits <integer> 2 maximum number of digits after decimal point
CurrencySymbols <string> £,€,$,EUR,USD,GBP Comma-separated list of currency symbols
CurrencyPeriodChar <string> . Character(s) for decimal point
CurrencyThousandsChar <string> , Character(s) for thousands separator
CssClass <string> CSS class

The currency question type is rendered as a text box with CSS class phdcc_Form_Question_Currency. If special option CssClass is specified then this element instead uses the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerCurrencyNotValid Not formatted as a currency "Answer not a valid currency value"
idAnswerOutOfRange Value not between RangeMin and RangeMax "Answer not in range {0:d} to {1:d}"
idAnswerRequired If required and no value given "required"

file

The file question type lets the user choose a file or image to upload. A standard file upload box and Browse button is shown. For an existing non-image result, the store-filename is shown as a label above the upload box.

If the uploaded file is an image then:

Only files with an extension that matches one of the FileExtensions are saved. The original filename is not used; instead the file is named as described below.

For 'Recordset' forms:

For 'Profile' forms:

The above file naming scheme lets display modules find files easily. Note that the above scheme makes uploaded files immediately accessible to people who know the correct URL. Should we protect access to these files?

Currently, any errors saving files are not reported.

phdcc.Data does *not* force the DNN File Manager to synchronize all files recursively after a file has been uploaded, so new files may not be visible immediately in [Admin][File Manager]. There is an option in there to [Synchronize files] option there - make sure you select [Recursive] first.

Note that the maximum file upload size is set by the web.config file 'httpRuntime+maxRequestLength' attribute. DNN currently sets this to "8192" which means that a maximum of 8192kB (8MB) can be uploaded. You can increase this setting simply by changing the value and saving web.config.

Name Values Default Description
Special options: FileExtensions <string> gif,png,jpg,jpeg,tif,tiff,bmp Accepted file extensions, comma-separated
ConvertToJPEG <bool> true Convert file to JPEG format
ImageJPEGQuality <integer> 75 JPEG save quality percentage, in range 1 to 100
ImageMaxWidth <integer> Maximum image width in pixels, must be greater than 0
ImageMaxHeight <integer> Maximum image height in pixels, must be greater than 0
ImageUseAspectRatio <bool> true If resizing, keep aspect ratio
ImageGenerateThumbnail <bool> false Generate a thumbnail
ImageThumbnailMaxWidth <integer> 150 Thumbnail maximum image width in pixels, must be greater than 0
ImageThumbnailMaxHeight <integer> 150 Thumbnail maximum image height in pixels, must be greater than 0
ImageStoreOriginal <bool> false Save a copy of the user's originally uploaded file
CssClass <string> CSS class

The file question type is rendered as follows:

If special option CssClass is specified then all these elements instead use the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"
idAnswerBadImage If uploaded file cannot be loaded as an image "Uploaded file is not recognised as an image"
idAnswerBadFileExtension If file extension does not match FileExtensions "File type is not accepted: bad file extension"

captcha

The captcha question type shows a simple CAPTCHA field to deter automated form generators. The user is not logged in, they are prompted to type in a random 4 digit integer into a text box. This CAPTCHA question is accessible, ie it will work for visually-impaired users because it does not use a distorted image of characters.

If the CAPTCHA 'response' does not match the supplied 'challenge' value, then the form does not validate - in addition, interim form results are not stored.

If a user is logged in and is not an admin/host, then the CAPTCHA question is not shown at all; if this is the only question in a group, then the group is not shown as well.

Name Values Default Description
Special options: columns <integer> 4 Column count
CssClass <string> CSS class

The captcha question type is rendered as a (challenge) span with CSS class phdcc_Form_Captcha_Label followed by a (response) text box with CSS class phdcc_Form_Captcha. If special option CssClass is specified then both these elements instead use the CSS class name that you have specified.

Special String Id Reason Default
Validation fail messages: idAnswerCaptchaFail User's response did not match the challenge value "Answer did not match the challenge value"

button

The button question type shows a button that the user can press to submit the form. The button text is taken from the "Default value" given for a question. If the user is amending an existing profile form, then the button is prefixed by a label "YES" if it was pressed previously or "NO" if not. When the form is being moderated, the button is replaced by a checkbox; this is checked if the user pressed the button.

If the user pressed the button, then "True" is stored in the database against the question id name. Otherwise, no value is stored. No special action is taken when the button is pressed; pressing the button is equivalent to pressing the standard Submit button. On your "Thank you page" you could the check whether the button was pressed and act accordingly.

The ordinary Submit button is still shown; this is shown with CSS class phdcc_Form_Click so Submit could be made not visible by overriding this class in your own CSS file.

Name Values Default Description
Special options: CssClass <string> CSS class

The button question type is rendered as a button, possibly prefixed by a span label. If moderating a profile form, then it is rendered as a checkbox followed by a span label. If special option CssClass is specified then all these elements use the CSS class name that you have specified. Otherwise, CSS class phdcc_Form_Question_Button is used.

Special String Id Reason Default
Validation fail messages: idAnswerRequired If required and no value given "required"

hiddenfield

The hiddenfield question type shows an invisible hidden field. The question control name is automatically changed to Question_Hidden.ascx so that the question is not visible on screeen, unless you are an administrator.

The Required option is ignored, ie the hidden field does not need to have a value in order to validate.

Note: you can also hide complete questions, using a Session variable control.

Special String Id Reason Default
Special options: HTML_OK <bool> Value may contain HTML

control

The control question type shows a user control that you have programmed as described here. Your user control must be in the DesktopModules/phdcc.Data.Form directory - the full filename must be specified in the ControlFilename question option.

The question presentation is determined entirely by your user control code. If any exceptions occur, then the exception message and a stack trace are shown.

Name Values Default Description
Special options: ControlFilename <string> The filename of your user control, eg mycontrol.ascx