Each form instance asks a user for answers to one or more questions. The questions and answers are stored in DNN database tables managed by phdcc.Data. You can optionally link questions to standard DNN Profile Properties.

A profile is persistent information for a user. So 'Profile' forms remember the last values entered for a user. (By definition, a user must be logged in to use a Profile form.)

• When a user first goes to a 'Profile' form they are shown a blank form, can fill it in and press Submit.
• If OK, a "Thank You" message is displayed, or a different URL is shown. An email is sent if appropriate.
• If the user later returns to the form, they see a message that says "You have already filled in this form." and can press the "Amend Form" button if they wish to update their profile.

'Profile/Register' forms work like 'Profile' forms, except that a new user can be registered if they are not logged in. Various questions must have certain linked DNN properties. See below for full details.

• When a user first goes to a 'Profile' form they are shown a blank form, can fill it in and press Submit.
• If OK, a user is created, they are sent a registration email, a "Thank You" message is displayed, or a different URL is shown. An email is sent if appropriate.
• If the user later returns to the form, they see a message that says "You have already filled in this form." and can press the "Amend Form" button if they wish to update their profile.

A 'Recordset' form provides new information each time it is submitted. You do not have to be logged on to use a Recordset form, although you can set "User must be logged on" in the form editor if you want this.

• When someone goes to a 'Recordset' form they are shown a blank form, can fill it in and press Submit.
• If OK, a "Thank You" message is displayed, or a different URL is shown. An email is sent if appropriate.

In the form editor, you can set default values for all form questions. (Various special default values are also supported, such as =UserInfo.Email - see Questions page.)

If question is linked to a DNN Profile Property (see below) and the user is logged in, then the current profile property value for a question is shown pre-filled; the profile property is updated when the form is submitted.

Normally you will want to moderate user submissions before displaying them. To do this, check the "Results must be authorised" checkbox in the form editor. After some forms have been submitted: in the form Admin box, click on the Moderate button - see the Admin page for more details.

A new resultset is stored when a form is moderated or amended by an administrator. The DateTime when the form was originally entered is stored in the "SubmitTime" answer, ie as the answer to a question with QuestionIdName "SubmitTime". In the View or List modules, you can access this value using Form("SubmitTime"). This DateTime is stored in RFC 1123 format, ie ddd, dd MMM yyyy HH':'mm':'ss 'GMT'.

Currently it is only possible to moderate 'Profile' form results.

Form questions can be linked to DNN Profile Properties, ie those that appear in the DNN user profile page. Both standard profile properties and your custom properties can be used.

In the Form Editor, select a value for the Linked DNN property parameter - this is a dropdownlist containing all available properties, together with a default of "None".

For questions which have a Linked DNN property, the question's default value is taken from the DNN property. When the form is submitted and it validates, the user's answer updates the DNN property.

Be careful when you use a Linked DNN property that corresponds to important DNN user information. For example, if a question is linked to 'Display Name' or 'Email' then any changes will update the user's registration details. (There is special protection to make sure that the 'Username' cannot be changed.) As an alternative, you could for example set the question Default parameter to =UserInfo.Email - in this case, the user's registration email is not updated.

Using linked DNN properties lets you pass answers from one form to another.

Here is a partial list of the available DNN properties that you are likely to see:

• None
• Display Name (Text)
• Email (Text)
• Username (Text)
• Password (Text) the password cannot be displayed, only set
• Prefix (Text)
• FirstName (Text)
• MiddleName (Text)
• LastName (Text)
• Suffix (Text)
• Unit (Text)
• Street (Text)
• City (Text)
• Region (Region)
• Country (Country)
• PostalCode (Text)

This is the logic that Register/profile forms use:

• If a user is not logged in then string idForceRegistration is appended to the form header help text. The English default for this string is <br />This form will register you at this site. If you are already registered, please login first.

• For the register form to work, you must have one question with a Linked DNN property of Email. If there no such question, then this error is returned: No email Linked DNN property

• If the entered email is already being used by an existing user, then it is likely that the user has registered before, so string idRegisterEmailExists is shown as an error. The English default for this string is There is already a user with this email. Either login or use a different email address.

• If there is a Linked DNN property of Password then this is used as the user's password. Otherwise, a random password is generated - this will be emailed to the user in their registration email.

• A Username must be provided in one of several ways.

  • If a Username Linked DNN property is provided then this is tried as the Username.
  • Such a user-supplied Username can only contain alphanumeric, underscore or hyphen characters. If not, idAnswerBadUsername is shown as an error. The English default for this string is Answer is not a valid Username: use alphanumeric, underscore and hyphen characters.

  Otherwise, the following rules are used to find an unused Username:

  • If a FirstName or LastName is provided then these are concatenated together as a base Username.
  • Otherwise, if a DisplayName is provided then this is used as a base Username.
  • As a last resort, the Email is used as a base Username.
  • The base Username is stripped of any characters that are not letters, digits, underscore or hyphen.
  • If a user with the base Username does not currently exist, then this is used as the Username.
  • Otherwise, the characters '1' to '9' are added in turn to the base Username until an unused Username is found. If no free Username can be found then an error is returned.
  • For example, if FirstName is 'Sue' and LastName is 'Jones' then the base Username is 'Sue Jones'. If the usernames 'Sue Jones' and 'Sue Jones1' are already taken, then 'Sue Jones2' will be used as the Username.

• If FirstName, LastName and DisplayName are not provided then the DisplayName is set to the Username.

• If it is not possible to create the user for some other reason, then an error such as UsernameAlreadyExists or InvalidEmail is returned.

• After the user has been created and logged in, a registration email is sent to the user with a BCC to the form email address (if present). The email is formatted with the DNN localisation routines. By default, the email subject and body are taken from the EMAIL_USER_REGISTRATION_PUBLIC_SUBJECT and EMAIL_USER_REGISTRATION_PUBLIC_BODY resource names in \App_GlobalResources\GlobalResources.resx. You can use phdcc.Data specific alternatives using the resources in phdcc.Data.Form/App_LocalResources/ViewForm.ascx.resx or the localised equivalent. Specify non-blank values for the email subject and body from the PHDCC_FORM_EMAIL_USER_REGISTRATION_SUBJECT.Text and PHDCC_FORM_EMAIL_USER_REGISTRATION_BODY.Text resource names.

• Once the user has been registered and logged in, any linked DNN properties are updated and the form results stored in the normal way.