As of version 1.7.3.2, Participants Database allows you to add a CSV download form to your regular frontend list displays. It does require a little configuration and a custom template, but we’ll walk you through the process in this post.
First, the warning: be careful with this, it gives your users direct access to your data. You do have some control over what they can get, but it is up to you to control who has access to the download form. The form itself is as secure as we can reasonably make it, but the final and most important layer of security is up to you. Be careful who you give access to.
How to Set It Up
The CSV download form is generated by a template function that you must add to a custom template. If you’re not sure how custom templates in Participants Database work, read this article before you begin: Using Custom Templates You will be using a template for the list shortcode, it doesn’t matter which one, it will work with any list shortcode template. If you have a custom template for your list already, you can just modify it with these changes.
The reason we made it slightly inconvenient to add the feature is because we want to make sure it is only available if the site administrator really wants to allow it.
The change you need to make is very simple: we add the template function to the template just before the final closing tag of the outer wrapper. Here is the default list template with the download form added:
If you know what you are doing, you can put in in other locations, but it must be in a Participants Database list template.
Configuring the Form
The form has several configuration possibilities:
- ‘title’ – the download form title
- ‘helptext’ – the explanatory text shown under the download button
- ‘button_text’ – the text shown on the download button
- ‘filename’ – the initial filename to use for the downloaded file
- ‘allow_user_filename’ – if set to false, the user cannot set their own filename for the downloaded file
- ‘export_fields’ – defines a list of fields to include in the download
To set any of these different from the default values, you need to put your preferred value into the $config array, for example, like this:
$config = array(
'title' => 'Search Result Download',
'helptext' => 'Click the "download" button to download your search results.',
'button_text' => 'download',
);
Setting Which Fields Are Included in the Download
By default, all the fields that are configured to be exported in a CSV will be included in the frontend CSV download, the same as it works on the backend. This is determined in the field definition on the Manage Database Fields page: all fields with the “CSV” checkbox checked will be downloaded.
If you want to determine which fields are included in the frontend CSV download, use the ‘export_fields’ configuration value. This value must be an array of valid fieldnames. Here is what that could look like:
$config = array(
'export_fields' => array( 'first_name', 'last_name', 'email' )
);
Make sure you are using the ‘name’ of the fields and not the title.
Rolf Müri 
Roland Barker 
Robert Flavin 
Musab Kaya 
Eelco 
Rupy Sidhu 
PeeN 
Roland,
Hi Roland,
I have been working on an amateur radio application to track our emergency communications capabilities.
I added the two lines for exporting the CSV file to the to a custom pdb-list-responsive template right before the top of the list-container. It functions as expected.
Except:
If I run a Search, Sort or push the Clear button the page reloads without the CSV export button. F5 reloads the page and brings the button back back.
The template has been modified after the list-conatiner declaration but except for a style declaration is untouched above there.
Could use some help on this one…..
Correction… the Sort, Search and Clear buttons put the CSV Export button at the bottom of the page, not where it was placed in the custom template, just below the Sort button.
Can this be changed so the template follow the original coding?
Hi Roland,
I built a template “pdb-list-csv.php” using the “table-less” reponsive layout. The webpage with the shortcode shows just the download-button and the checkbox for the field title besides some explanations.
The template therefore contains only the wrapper-, an additional for formatting purpose, the definition of the config-array and the call of “csv_export_form”.
This all works fine, but:
If you push the download-button again without loading the page again (e.g. because you downloaded the file, but you have forgotten to click the checkbox), the second downloaded file contains just the header line (and perhaps the title line), but no data.
Have I deleted something essential from the original template or is this a bug?
How can I prevent that the user may push the button a second time, e.g. by displaying a follow-up page after submitting the download request?
I would be grateful for a suggestion from you.
Rolf
Yes, this is a bug of some kind. The functionality is not well suited to this context, and what is happening is the CSV uses a stored database query to get the list of records to use and when it is done, that is cleared from memory to prevent it getting used again in the incorrect context. Reloading the page stores the query again. It is possible it is not necessary to reset that stored query, but a change like that is very tricky to test.
You can experiment with changing this yourself, the stored query is cleared in participants-database.php on line 2820, you’ll see:
self::$session->clear('csv_export_query');just comment that line out like this
// self::$session->clear('csv_export_query');Hi Roland,
Thanks for the quick reply.
I tried your suggestion: It is now possible, to push the button again and get the fields, but then, the selection of the fields (‘export_fields’) is no more active. that means, all fields are included, even the password and the private ID!
Therefore it is not that easy. And with the next update, I would have to do the modification again.
I will try to hide or disable the button with jQuery after the submission. But as I am not quite familiar with jQuery, I need some time.
If I succeed, I will share the solution here.
Or have you a better solution in mind?
Rolf
You can change that behavior in a similar way. Not far from the line where you commented out the clearing, there is a line:
self::$session->clear('csv_export_fields');You can comment that one out too.
I’m considering making these changes permanent or looking for a better way to handle clearing these stored values, so you may not need to alter the plugin again after updating.
Hi there,
The PDB is one of the best plugins I use and I have the csv download working as I want which is so useful.
One tweak that I would like to apply is to remove the “Include field titles” option next to the download button (or else make it automatically ticked).
Is there a simple way to do this?
Many thanks,
Rob
Hi Robert,
It is possible to not show the field titles checkbox, you can use the ‘field_titles_checkbox’ configuration parameter to switch that off. I updated the gist to show that option since it wasn’t documented in there before. However, the export will not include the titles because these are not included by default. The reason for this is because it is acutally not standard CSV to include this, since it is not record data. It works fine if you’re importing to a spreadsheet, however.
If you want this line included in the CSV by default, there isn’t any particularly easy way to do this. My suggestion is to include the checkbox, but hide it using CSS. To make it default to checked, you can add a simple javascript snippet to set the checkbox.
Something like this will do it:
<script> jQuery(function($) { $('form.csv-export input[name="include_csv_titles"]').prop('checked', true); }); </script>Hi Roland,
Not only is the plugin great, it has the best support as well. That answer is really helpful and solves my problem.
Huge thanks,
Rob
Hello Roland,
I have entered the code and only activated it for administrators. Many thanks. When I export the search results, all fields are exported. But I have many fields that I have divided into groups. That means the value in search_field and field are different on individual pages. It should only export the fields that were defined in search_fields. Can you help me?
If you look at the example script on line 78, you’ll see the configuration array for the export form. You can set which fields are included in the export using the “export_fields” element in that array. It’s going to be looking for an array of field names. One way to do what you’re asking about is to create a special version of this list template for each page.
Hi Roland,
Your plugin is very promising.
I tried the CSV export. It will work for the complete dataset, but not when you select a subset through search and sorting first. The export button just doesn’t fire when clicked upon.
It seems to be caused by the AJAX replacement of the searchform and resultlist after searching or sorting.
BTW I’m using latest version of Chrome on linux.
What I really want to accomplish is adding more export formats. For this would it be best to add an action filter in Participants_DB process_page_request method?
Thanks for your reply.
The CSV download is behaving oddly, there seems to be a missing
tag in the search/sort form at the top of the template. Not sure why (I’m out of town at the moment), but if you add a </form> tag right after thesort_form() ?>on line 66 it will close the search form and the CSV download form will work as expected.Not sure what you mean by more export formats…other than a CSV? Anyway, I suppose that is possible in the way you suggest, but I have not investigated this.
Yes! Great! It works.
Thanks for the quick reply.
Eelco
Hi Roland,
When I download data from the backend, it only downloads 2 fields though there are around 10 fields. Also, is it possible to download data of specific dates (dates are shown as dropdown to select in a field )?
If you are talking about exporting a CSV, you need to tell the plugin which fields you want included in the CSV. Each field has a CSV selection for that. This is on the Manage Database Fields page. You can also use the selectors to add multiple fields to the CSV on that page if you have a lot of them to add.
The CSV export will follow whatever filter you have set up, so on the admin list page, use the filters at the top to get your date range, then do your export.
It’s a very useful feature, thank you! I try to add “Download” button to multisearch template. Unfortunatelly as result I get only one row with fields name header. Original csv template works perfect. Is possible simply add download functionality in multisearch template?
When I check “Add field name” everything is alright. Searched data are included from selected field only.
It is possible to add this to a multisearch template, you just need to use the multisearch template (which is found in the combo multisearch plugin folder) as your starting point to making your custom template.
Thank you for this, it is perfect!
I just can’t figure out the shortcode to count the records. I know I will feel stupid when I find out.
Here is what I have, but when I apply a filter, the count does not change:
[pdb_list template=csv search="true" sort="true"]
[pdb_total] records found
Dave, if you want to count only certain records, you have to put the filter into the [pdb_total] shortcode, but that shortcode does not show the number of search results, that is normally displayed by your [pdb_list] shortcode.
Got it now, I was missing display_count.
Thank you!
This is just so wonderful! Have tried in vain for so long, to integrate a download CSV button into some of my sites, this means quite quite a lot. Thank you so much Mr. Roland for this priceless feature. Can’t thank you enough!!!