phdcc.Data.List is a DNN 4 module to display a list of results produced by the phdcc.Data.Form module. It is typically used to show all (authorised) submissions of a form, or show a subset based on some search criteria. Each individual result (summary) will usually contain a link to show the full details that were entered.

phdcc.Data.List contains a wizard that creates a simple template that displays each result in the list. The template is a standard ASP.NET user control in a file - you can edit this to customise the output so that it appears as you wish.

• For a 'Profile' form: The last authorised result for each user is listed
• For a 'Recordset' form: All authorised results are listed
• Alternatively, if set up with a Session variable name, then the contents of this variable determines the items that are shown. This lets you choose the results to show elsewhere, and simply use phdcc.Data.List as a list display tool. See below.

The phdcc.Data.List module currently shows its results using an asp:GridView that shows its results in pages, 20 results at a time, with pager links to move between pages at the top and bottom of the list.

Note carefully that module users with Edit permissions (ie Administrators etc) can enter ASP.NET code that is then run - therefore be very careful to whom you give Edit permissions.

Form results for SuperUser users such as host are not listed (unless provided using the Session variable method).

Most of the results are retrieved in a way that is safe to return as HTML to the user. However some user-provided information needs to be made safe by calling Server.HtmlEncode().

1. Many users fill in a form giving their details, using phdcc.Data.Form
2. Typically, an administrator will moderate new submissions in phdcc.Data.Form
3. Others want to look through this information so they enter a search request, using phdcc.Data.Search
4. Multiple hits are displayed to the user, using phdcc.Data.List
5. Clicking on a single result shows full details, using phdcc.Data.View

So phdcc.Data.List is primarily aimed at showing a list of the answers to the questions posed in one form. For a 'Profile' form, phdcc.Data.List can also show results from other forms that the user has filled in. In addition, any other (per-user) data can be shown, eg from information stored by DNN or other third-party modules.

To use phdcc.Data.List:

1. Beforehand, you will usually want to add an instance of the phdcc.Data.View module to another page.
2. In the DNN Control Panel, add a new instance of the phdcc.Data.List module to a page, entering your desired container name.
3. Now, in the module Settings, specify which form's results you want to list, and a page to display an individual result - see below.
   
4. Then, use the Edit Template option to create a template for each result - again, see below.
   

There are also these further options - selected in Settings:

• A custom CSS file
• A CSS class for the list's asp:GridView
• The name of the QueryString parameter used to filter the list, and which question to look in - see below
• A Session variable can specify which items to list - see below.
• You can also provide custom code to filter and sort the list by writing a VB or C# user control as described below.

Click on the Settings button (or select Settings from the module menu). Expand the phdcc.Data.List section and choose/enter these values:

• The FormId/Page of the form whose results you want to display.
• The page or URL of a page that can be used to display a detailed result.
• Optionally, the QuestionId that is searched using the following Search parameter
• Optionally, the name of the QueryString parameter used to filter the list, eg used by phdcc.Data.Search.
• Optionally, the name of a Session variable that contains the items to list.
• Optionally, the name of your VB or C# control file that filters and sorts the results list.
• Optionally, the CSS file name which you have put in the DesktopModules\phdcc.Data.List directory.
• Optionally, the CSS class name for asp:GridView used to display the list

Click on Update to save your changes.

A template is needed to define what is displayed for each result in the list. An initial template can be set up for you by a phdcc.Data.List wizard. You can then tailor it to fit your precise requirements within Edit Template. Alternatively you can upload your own template using FTP or [Admin][File Manager] into the DesktopModules\phdcc.Data.List directory, and then select it in Edit Template.

A template is a standard ASP.NET user control file that can contain both HTML and code, either VB or C# - see examples below.
Use a separate file for each of your templates, ie for each different instance of the phdcc.Data.List module on your site.

When you first enter Edit Template, click on "Create a new template using a wizard":

(Alternatively, you can click on "Choose an existing template" to pick an existing template or one that you have uploaded to the DesktopModules\phdcc.Data.List directory. Template files must start with precisely the correct text, as described below.)

Enter a filename for your template, then click on "Create template file using a wizard". After this, you will need to confirm that you want the file created.

A template file is created that contains all the questions on your form, together with a 'Go' link to show the full details in a phdcc.Data.View. The template is laid out in a table, with group name on the left, questions and answers in the middle, and 'Go' on the right. You will usually want to reduce the amount of information shown, with full details shown in the View. Note that by default, results for email type questions are replaced with EMAIL SUPPRESSED; you can change the code to show the email if you wish.

The generated template is now shown in an edit box. Edit this as required and then press Update.

This shows one result displayed by phdcc.Data.List using the above template:

The "Create a new template" wizard creates a template user control file with the correct code at the start. When editing within Edit Template, you do not see this initial code. However, if you create your own template user control file from scratch, you must make sure that the correct code appears at the start. For Visual Basic, this is:

<%@ Control Language='VB' ClassName='ControlName' Inherits='phdcc.Data.List.TemplateBaseVB' CodeFile='TemplateBaseVB.ascx.vb' AutoEventWireup='true' %>
<%@ Import Namespace='phdcc.Data.List' %>
<% SetResultSet()%>

where ControlName corresponds to the template filename with ".ascx" removed. For C#, the correct initial code is:

<%@ Control Language='C#' ClassName='ControlName' Inherits='phdcc.Data.List.TemplateBaseCS' CodeFile='TemplateBaseCS.ascx.cs' AutoEventWireup='true' %>
<%@ Import Namespace='phdcc.Data.List' %>
<% SetResultSet(); %>

The template shows each result in the list. (Programmers: the template is the ItemTemplate for the GridView.) Your template code can be in either Visual Basic (VB) or C-Sharp (C#). The template can contain any HTML and use all normal ASP.NET code. However it will typically use various phdcc.Data.List helper functions to access form results. The "Create a new template" wizard uses a simple version of the Form helper function.

• You can use ASP.NET server-side controls such as asp:Label, asp:BulletedList, asp:Image, etc.
• You must set properties for these controls before the control is declared in the code - see the examples below.
• Do not use Response.Write in your code as this ends up at the top of the DNN output.

The following VB code is in a file called ShowProjectItemVB.ascx so that it matches the chosen ClassName property (without the extension). The filename must not start with a number and should not contain periods and spaces. The code starts with the required standard lines.

<%@ Control Language='VB' ClassName='ShowProjectItemVB' Inherits='phdcc.Data.List.TemplateBaseVB' CodeFile='TemplateBaseVB.ascx.vb' AutoEventWireup='true' %>
<%@ Import Namespace='phdcc.Data.List' %>
<% SetResultSet()%>


Project: <b><%=Form("idPP_Name")%></b> <%=Form("idPP_Description")%>
<%
  btnGo.Attributes("onclick") = GetDisplayPageWithUserIdJS()
%>
<asp:Button ID="btnGo" runat="server" Text="Go" />

This code calls the phdcc.Form.List SetResultSet function to tell the module which results set to use.

The code then contains some HTML with a couple of calls to the phdcc.Form.List Form function to return the answers to two questions: those with a QuestionId of "idPP_Name" and "idPP_Description".

Finally, an asp:Button with text "Go" is set up to go to the DNN page that displays the result using the phdcc.Data.View module. The GetDisplayPageWithUserIdJS function returns the "Display details page" chosen in the Settings, with this result's UserId appended as a QueryString URL parameter, all wrapped as JavaScript to make a suitable onclick handler.

The above code is used when listing Profile forms. For Recordset forms, the The GetDisplayPageWithResultSetIdJS function is used instead to get the link to the View page.

See the bottom of the phdcc.Data.View page for an example that uses different techniques to show information.

The C# equivalent code is very similar, in a file with matching filename ShowProjectItemCS.ascx

<%@ Control Language='C#' ClassName='ShowProjectItemCS' Inherits='phdcc.Data.List.TemplateBaseCS' CodeFile='TemplateBaseCS.ascx.cs' AutoEventWireup='true' %>
<%@ Import Namespace='phdcc.Data.List' %>
<% SetResultSet(); %>


Project: <b><%=Form("idPP_Name")%></b> <%=Form("idPP_Description")%>
<%
  btnGo.Attributes["onclick"] = GetDisplayPageWithUserIdJS();
%>
<asp:Button ID="btnGo" runat="server" Text="Go" />

The following phdcc.Data.List properties and functions can be called from your code. All the Form... functions that return strings are HTML safe. For FormValues and FormXValues, make sure that you call Server.HtmlEncode() on any user provided data.
Functions marked *** are only usable on results from 'Profile' forms.

ReadOnly Property ResultSetId() As Integer

Returns the current results set identifier

ReadOnly Property UserId() As Integer

Returns the current UserId

ReadOnly Property UserName() As String

Returns the current UserName

ReadOnly Property ResultTime() As DateTime

Returns the DateTime when the form was submitted or approved

Function Form(ByVal QuestionIdName As String) As String

Returns the user's answer(s) to this question

Function Form(ByVal QuestionIdName As String, ByVal QuestionOptionIdName As String) As String

Returns the user's answer to this question's option, ie use for checkboxes or radiobuttons question types

***Function FormX(ByVal FormIdName As String, ByVal QuestionIdName As String) As String

Returns the user's answer to this question on form 'FormIdName'

***Function FormX(ByVal FormIdName As String, ByVal QuestionIdName As String, ByVal QuestionOptionIdName As String) As String

Returns the user's answer to this question's option on form 'FormIdName'

Function FormDefault(ByVal QuestionIdName As String, ByVal QuestionOptionIdName As String, ByVal DefaultValue As String) As String

Returns the user's answer (to this question's option); returns 'DefaultValue' if no answer was given

***Function FormXDefault(ByVal FormIdName As String, ByVal QuestionIdName As String, ByVal QuestionOptionIdName As String, ByVal DefaultValue As String) As String

Returns the user's answer (to this question's option) on form 'FormIdName'; returns 'DefaultValue' if no answer was given

Function FormValues(ByVal QuestionIdName As String) As IList

Returns a set of phdcc.Data.List.ResultInfo results that the user answered for this question, ie use for checkboxes or radiobuttons question types. The ResultInfo.ResultValue values have not been processed by Server.HtmlEncode()

***Function FormXValues(ByVal FormIdName As String, ByVal QuestionIdName As String) As IList

Returns a set of phdcc.Data.List.ResultInfo results that the user answered for this question on form 'FormIdName', ie use for checkboxes or radiobuttons question types. The ResultInfo.ResultValue values have not been processed by Server.HtmlEncode()

Function SetResultSet() As ResultSetInfo

Sets the current results set identifier, ie specifies which form results the Form functions use

Function GetDisplayPage() As String

Returns the "Display details page" URL chosen in the Settings

Function GetDisplayPageWithUserId() As String

Returns GetDisplayPage with the UserId appended as a QueryString parameter

Function GetDisplayPageWithUserIdJS() As String

Returns GetDisplayPageWithUserId, wrapped in JavaScript

Function GetDisplayPageWithResultSetId() As String

Returns GetDisplayPage with the ResultSetId appended as a QueryString parameter

Function GetDisplayPageWithResultSetIdJS() As String

Returns GetDisplayPageWithResultSetId, wrapped in JavaScript

If the user did not answer a question, then Nothing is returned.

The phdcc.Data.List.ResultInfo class has these properties:

• String QuestionIdName
• String QuestionOptionIDName
• String ResultValue

The phdcc.Data.List.ResultSetInfo class has these properties:

• Integer ResultSetId
• Integer PortalId
• String FormIdName
• Integer UserId
• String UserName
• DateTime ResultTime
• List<ResultInfo> Results

By default, phdcc.Data.List shows the (last authorised) results filled in for the specified form. The most recently submitted or approved results are shown first.

This results list can be filtered by specifying a search string, passed as a QueryString parameter. The name of the QueryString parameter is specified in the module Settings, and defaults to "search". If the QueryString parameter is present, then phdcc.Data.List checks each result to see if one of the answers contains the search string. All answers are considered as text. You will usually set the search QueryString parameter name to match that used by phdcc.Data.Search. Note that you cannot search results in associated profile forms.

You can restrict the search to a particular QuestionId; specify the QuestionId in the module Settings.

You can also filter and sort the results list in code as described below.

If you want to tell phdcc.Data.List precisely which results to show, then you can do this in code using a Session variable. In this scenario, you would use code on another page to create a list of results to show, then redirect to the page that contains phdcc.Data.List. For example, you could use the phdcc.CodeModule DNN module to create the Session list.

Use the module Settings page to specify the Session variable name. The Session variable must be set to an ArrayList of int-s where each int is an ResultSetId.

• Any ArrayList elements that are not int-s are ignored.
• If the Session variable is null/nothing or is not an ArrayList, then an empty list is shown.

You can also filter and sort the results list in code as described below.

You can write VB or C# code to filter out unwanted results from the results list or sort the results list. The code is written as a user control file but it is never displayed; instead, you must provide a FilterSort function that does the filtering and sorting.

You must create your filtering and/or sorting user control by hand - and then upload it to the DesktopModules\phdcc.Data.List directory. Then specify the control filename in the module Settings.

Use the following as the basis of your VB user control. The following code is in a file called ListFilterAndSortVB.ascx so that it matches the chosen ClassName property (without the extension). The filename must not start with a number and should not contain periods and spaces.

The dvForm.Sort property can be set to one of the following column names:

• ResultSetId
• UserId
• UserName
• ResultTime

Specify a filter expression (using the above columns only), as per this Microsoft documentation.

<%@ Control Language="VB" ClassName="ListFilterAndSortVB" Inherits="phdcc.Data.List.FilterSortBase" AutoEventWireup="true" %>
<script runat="server">

Public Overrides Function FilterSort(ByVal dtForm As DataTable) As DataView
  Dim dvForm As DataView = New DataView(dtForm)
  dvForm.Sort = "UserName"
  dvForm.RowFilter = "UserName LIKE 'c*'"
  Return dvForm
End Function
</script>


To filter or sort based on the question answers, you must go through each of the rows in the result. The following code shows how to remove results where the answer to question "idPP_Name" is 'haggis'.

For each row, you must call SetResultSetId(ResultSetId). You can then call Form to retrieve a form answer.

<%@ Control Language="VB" ClassName="ListFilterAndSortVB" Inherits="phdcc.Data.List.FilterSortBase" AutoEventWireup="true" %>
<script runat="server">

Public Overrides Function FilterSort(ByVal dtForm As DataTable) As DataView
  Dim dvForm As DataView = New DataView(dtForm)
  Dim RowNo As Integer = 0
  While RowNo < dtForm.Rows.Count
    Dim row As DataRow = dtForm.Rows(RowNo)
    Dim ResultSetId As Integer = CType(row("ResultSetId"), Integer)
    Dim UserId As Integer = CType(row("UserId"), Integer)
    Dim UserName As String = CType(row("UserName"), String)
    Dim ResultTime As DateTime = CType(row("ResultTime"), DateTime)
    SetResultSetId(ResultSetId)
    Dim PP_Name As String = Form("idPP_Name")
    If PP_Name = "haggis" Then
      dtForm.Rows.RemoveAt(RowNo)
    Else
      RowNo = RowNo + 1
    End If
  End While
  Return dvForm
End Function
</script>