phdcc.Data DNN modules
  search
Powered by FindinSite-MS
phdcc.Data.List: Overview
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 3/2/09

phdcc.Data.List Overview

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.

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.

Important security notes

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().

Usage scenario

  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.

Using phdcc.Data.List

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.
    First specify a form and display page in the Settings for phdcc.Data.List
  4. Then, use the Edit Template option to create a template for each result - again, see below.
    Then create a template for each result using the Edit Template option of phdcc.Data.List

There are also these further options - selected in Settings:

phdcc.Data.List module settings

phdcc.Data.List Settings

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

Click on Update to save your changes.

Edit Template

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":
Choose 'Create a new template using a wizard' to make an initial template
(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.
Enter a filename for your template, then click on 'Create template file using a wizard'

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.
Edit the generated template as required and then press Update

This shows one result displayed by phdcc.Data.List using the above template:
Sample output for a simple test form

phdcc.Data.List result templates

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.

VB template simple example

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.

C# template simple example

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

phdcc.Data.List functions, VB

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:

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


Simple list searches

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.


Using a Session variable to specify the list items

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.

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


Results list filtering and sorting in code

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:

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>