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

• A Question id identifier
• Prompt and help text in the current locale
• The Display Style basic question layout, one of:
  • horiz: flowing horizontally
  • lfhoriz: a line break, then flowing horizontally
  • vert: vertically with line breaks between options
• Whether an answer is Required
• Linked DNN property
• The Default value - various special values are supported, see below.
• The Question Type, eg text, int, etc.
  The list below details the options that are available for each question type.
• The Question Control Name that renders the control
• Some questions types require options to be specified, eg:
  • a list of radio button options
• Various special options can be specifed to change the:
  • appearance
  • validation
• Dependencies can also be specified, eg to make an answer required if another answer is 'yes'.

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.

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

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.

• Option id
• Option text in the current locale
• Option order integer
• Specified by user - see above
• Checked - if ticked or selected by default

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.

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:

• The Dependency type must be set to Question required if comparison true.
• The Depends on id must be set to question id that you want to compare to.
• The Comparison must be set to either Equal to or Not equal to.
• The Comparison value must be value you want to compare to.

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:

• Dependency type: Question required if comparison true
• Depends on id: 'idCharge'
• Comparison: Equal to
• Comparison value: 'idYes'

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.

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

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.

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

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.

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

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.

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

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.

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.

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.

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".

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.

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

• First any CurrencySymbols are repeatedly stripped from the beginning and end of the text.
• Then, if any CurrencyPeriodChar is present then the chars after the last instance are checked against CurrencyDigits.
• For the remaining text, any CurrencyThousandsChar characters are removed regardless of their position.
• The value to the left of the decimal point is then converted into an integer and compared against RangeMin and RangeMax.

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.

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:

• A 150 pixel wide thumbnail of the image is shown after the upload box.
• Image files have one of these extensions: gif,png,jpg,jpeg,tif,tiff,bmp.
• If possible, this text is added to the image Comment property as seen by Windows: <PORTAL>: uploaded on <DATETIME> by <USERNAME> using phdcc.Data.
• If the ConvertToJPEG special option is true (the default) the image is saved in JPEG format with extension .jpg.
• All JPEG files are saved with a quality set to the percentage in the ImageJPEGQuality special option, which is 75% by default.
• If the ImageMaxWidth and/or ImageMaxHeight special options are set (as integer pixel sizes), and the supplied image is bigger than this, then the stored image is reduced in size so as to fit in. If the ImageUseAspectRatio special option is true (the default) then both dimensions are reduced by a similar amount so the image is not distorted.
• If the ImageGenerateThumbnail special option is true then a thumbnail image is generated in a separate file to fit the ImageThumbnailMaxWidth and ImageThumbnailMaxHeight values, which both default to 150 (pixels), honouring ImageUseAspectRatio as above.
• If the ImageStoreOriginal special option is true then the user's originally uploaded file is stored unchanged in a separate file.

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:

• The uploaded file is stored in a portal sub-directory named: /portals/<PortalId>/phdcc.Data/<FormId>/.
• The filename is the QuestionId, an underscore, then a unique GUID, followed by the extension, eg: idSurveyEntry_dfd1e337-5c15-4631-befe-792197fa58eb.jpg.

For 'Profile' forms:

• The uploaded file is stored in a portal sub-directory named: /portals/<PortalId>/phdcc.Data/<userid>/<FormId>/.
• The filename is the QuestionId then an underscore then a sequence number, followed by the extension, eg: idProfilePhoto_1.jpg.
• Each time the profile form is updated with an uploaded file, the sequence number is incremented, eg: idProfilePhoto_2.jpg, etc.
• If a thumbnail has been requested, then its filename includes _Thumbnail eg: idProfilePhoto_2_Thumbnail.jpg.
• If the original is requested, then its filename includes _Original eg: idProfilePhoto_2_Original.png, ie it keeps the uploaded file extension.

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.

The file question type is rendered as follows:

• Non-image: a (store-filename) span with CSS class phdcc_Form_Question_File_Existing
• A (file upload) box/browse button with CSS class phdcc_Form_Question_File_Upload
• Image: a hyperlink with CSS class phdcc_Form_Question_File_ImageLink that contains an image with CSS class phdcc_Form_Question_File_Image

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

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.

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.

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.

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.

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.

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.