This article is considered appropriate for administrators or workspace users with an advanced level of knowledge about submission portals. If you are a beginner, we recommend reading the following article first:
For more information about suggested learning paths, see Introduction to Submission Portals: START HERE.
- The Purpose of a Listing Page
- Where to Find the Listing Page Customization Options
- Standard Portal Experience for a Listing Step
- Customize a Listing Page
In a submission portal, a Listing Step is a type of Step that allows a portal user to complete the same form multiple times; each completion is captured as a separate record on the given form (which is linked to the Primary form of the submission portal).
The Listing Page is the name of the page in the submission portal that shows the entries a portal user has completed for a Listing Step. This article will detail where to find the customization options for a Listing Page, how to change the customization options, and how changing each of these options affects the submission portal experience.
The Purpose of the Listing Page
As one example, a Listing Step may be ideal if, as part of an application process to a scholarship program, an applicant is asked to submit information about other scholarships they have applied for. Because the number of other scholarships will vary from applicant to applicant, estimating the number of fields to collect this information on a single form is difficult; a Listing Step solves this problem by allowing an applicant to complete as many records as they need to, with each completion representing a different scholarship.
After selecting a Listing Step to edit in a submission portal, a portal user will be taken to a Listing Page. The purpose of the Listing Page is to show the listing items/records that have been added and allow portal users to add additional items/records. This Listing Page can be customized by changing the previewable fields used to identify each item, adding or editing text at the top of a Listing Page, and setting the minimum and maximum number of items/records that a portal user can add. (See the section Standard Portal Experience for a Listing Step below for examples of the Listing Page.)
Where to Find the Listing Page Customization Options
In the Submission Portal Settings, the Listing Step configuration options can be found on the Listing Page tab of the Step Settings page for the Listing Step which an administrator wishes to configure. (Note that this tab will not appear for Single Form Steps.)
To locate the customization options for a Listing Page:
- Logged into a program as an administrator, navigate to the Settings & Tools section by selecting the cog wheel icon in the top navigation bar.
- Select the Submission Portal tile from the Plugin Settings section.
- Select the Edit button to the appropriate submission portal.
- In the Portal Sections pane on the left side of the screen, select the Listing Step to be configured. (The Listing Steps vary from program to program and will most likely be different from the screenshot example below.)
- Selecting a Listing Step in the Portal Sections panel will change the contents of the right panel and display the Step Settings. Select the Listing Page tab.
Standard Portal Experience for a Listing Step
Understanding a standard submission portal experience for a Listing Step (without any configuration options enabled) is useful to provide a baseline for how each configuration option affects this experience. (If already familiar with Listing Steps and how they behave in a portal, feel free to skip this section and continue to Customize a Listing Page below.)
Once a portal user accesses their submission card in the submission portal, they will be taken to the Submissions Page, showing the current Stage they are on and any previous Stages they have completed. There is no clear indication of which Steps are Single Form and Listing Step types on this page, but in the image below, the Payments Step is a Listing Step.
The status will update from Action Required to Complete once the minimum number of listing items have been marked complete by a portal user. In addition, the Open button will change to Edit. Portal users will be able to edit their listing items until the Stage is submitted. (For information on how to hide the completion status for a Listing Step, see the article Configure Listing Steps.)
Selecting Open or Edit on a Single Form Step will take the user directly to the Form Page where they can enter information. However, doing so with a Listing Step will take a portal user to a Listing Page, where they will see a list of the items that have been added. Up to three fields from the form used in the Listing Step can be previewed as a column on this listing table. (For more information on configuring these columns, see the section Customize a Listing Page → Configure the Field Columns below.)
In the image below showing a sample Listing Page, three listing items have been added, and the portal user can identify each by previewing the Payment number, the Amount of the Payment, and the payment Status. The third item is marked as a Draft, indicating that it is in progress and not all required fields have been completed.
A portal user can view important information and perform actions on the Listing Page:
A. Listing Page Messaging Text.
This text can be edited. For more information on editing the text that appears at the top of a Listing Page, see the section Customize a Listing Page → Change the Text on a Listing Page below.
B. The number of minimum items required to complete this Step, the maximum allowed, and total completed.
For more information on configuring the minimum and maximum number of listing items that can be added, see the section Customize a Listing Page → Change the Allowable Number of Listing Items below.
C. Portal users can select the blue arrow buttons next to each column to order the items in ascending or descending order based on that column.
D. Portal users can select the green + New Item button to add a new item, which will create a new record on the associated form in Zengine. Selecting + New Item will take the user to the Form Page, where they can fill in the fields and complete a new item/record.
For information on how to hide the + New Item button, see the article Configure Listing Steps.
Selecting + New Item, or Edit / Open for an existing item on the Listing Page, will take portal users to the Form Page to complete fields for a new record. A portal user can view information and perform actions on the Form Page:
A. Step Form Messaging. This text can be edited.
Changing the text that appears at the top of the Form Page is not covered in this article; for more information on changing the Step Form Messaging text, see the article Step Page Text.
B. Portal users can select Delete to delete this item. After doing so, it will no longer appear on the Listing Page.
Preventing portal users from deleting listing items is not covered in this article; for more information on disabling the Delete button, see the article Prevent Portal Users from Deleting Listing Items.
C. Portal users can select Save Draft to save their progress before all required fields are filled in.
D. Portal users can select Mark Complete to save the item as complete once all required fields are filled in.
E. Portal users can select Close to return to the previous Listing Page.
Customize a Listing Page
The Listing Page can be configured on the Listing Page tab of the Step Settings page for a Listing Step.
Remember to select the blue Save all settings button in the lower right corner of the screen to save all changes to the Step when the customization is complete.
Configure the Field Columns
On the Listing Page from a portal user’s perspective (as shown in the screenshot below), the listing items that have been added are presented in the form of a basic table: each row is a listing item that has been added as a record to this Step’s associated form in the workspace, while each column, displays the data drawn from a designated field on the form.
The columns that display on this table (shown above) can be configured and labeled by an administrator.
The configuration options for these columns are within the Submission Portal settings at the top of the Listing Page tab of the Step, labeled Configure the Step field columns and messaging.
Up to three columns can be set to appear on the Listing Page table, each drawn from a field that appears on the Listing Step form.
To change these columns:
- Select the box representing the column to customize.
- Selecting a box will open the customization options for that column.
A. Field dropdown:
- Select the top box to open a dropdown menu with a list of the available fields on the form associated with this Step.
- Choose which field should display in this column for each listing item.
B. Column Label:
- If left alone, the column heading will display the same name as the field selected.
- To edit, select within the box and update as needed.
- The Listing Page column will display what is entered into the Column Label text box.
C. Select the X button to collapse these options and return to the previous view.
D. Delete Column (see image below):
- Select this button to remove the column from the Listing Page table.
- Note that this button will not appear for the first column field option, as the table must include at least one; it will only appear for the second and third column field options.
Change the Text on a Listing Page
The Listing Page Messaging Text appears at the top of the Listing Page. Default text appears in this text editor when a submission portal is first created (see image below), but this can be edited to provide clearer instructions or additional information to a portal user.
This text can be edited in the text box labeled Step Listing Page Messaging on the Listing Page tab.
Select inside the text formatting area to create, edit, and format the Listing Page Messaging text for this Listing Step.
There are several standard formatting options that can be used to customize the appearance of the text, including changing the font and text size; displaying text as bold, italicized, or underlined; changing font highlights or text colors; changing text alignment; adding bulleted or numbered lists; and creating hyperlinks.
Change the Allowable Number of Listing Items
An administrator can also configure the minimum and maximum number of listing items that can be added as part of this Step. These settings can be found on the bottom of the Listing Page tab.
The Minimum Number of Listings per Listing Page setting determines the minimum number of listing items that must be marked complete by a portal user before the Step is considered complete and the Stage can be submitted.
The Maximum Number of Listings per Listing Page setting determines the maximum number of listing items that can be added by a portal user for this Step. The portal user will be prevented from adding more items once that number is reached.
To change either number select the corresponding box and enter in the appropriate number.
Once the changes are saved, this information will be updated at the top of the Listing Page in the submission portal.
- Configure Listing Steps: change the configuration options for how a Listing Step behaves, and what options a portal user will see when interacting with a Listing Step
- Submission Portal Key Concepts: Intermediate: Describes Listing Steps and form relationships at a conceptual level
- Make a Step View Only: if a portal user should not be able to add OR edit items/records on a Listing Page
- Prevent Portal Users from Deleting Listing Items: if a portal user should not be able to delete items/records on a Listing Page
- Making a Step Optional in the Submission Portal: if a Listing Step should be optional for a portal user to complete before they are able to Submit a Stage