Merge pull request IQSS#8402 from IQSS/8244-guestbook

improve guestbook guides and link to them, add download button

doc/release-notes/8244-guestbook.md

@@ -0,0 +1,3 @@
+A download button has been added to the page that lists guestbooks. This saves a click but you can still download from the "View Responses" page, as before.
+
+Links to the guides about guestbooks have been added in additional places.

doc/sphinx-guides/source/api/native-api.rst

@@ -584,9 +584,13 @@ The fully expanded example above (without environment variables) looks like this
 
 You should expect a 200 ("OK") response and JSON output.
 
+.. _download-guestbook-api:
+
 Retrieve Guestbook Responses for a Dataverse Collection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+For more about guestbooks, see :ref:`dataset-guestbooks` in the User Guide.
+
 In order to retrieve the Guestbook Responses for a Dataverse collection, you must know either its "alias" (which the GUI calls an "identifier") or its database ID. If the Dataverse collection has more than one guestbook you may provide the id of a single guestbook as an optional parameter. If no guestbook id is provided the results returned will be the same as pressing the "Download All Responses" button on the Manage Dataset Guestbook page. If the guestbook id is provided then only those responses from that guestbook will be included.  The FILENAME parameter is optional, and if it is not included, the responses will be displayed in the console.
 
 .. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of ``export`` below.

doc/sphinx-guides/source/user/dataverse-management.rst

@@ -176,21 +176,20 @@ How do you create a template?
 Dataset Guestbooks
 -----------------------------
 
-Guestbooks allow you to collect data about who is downloading the files from your datasets. You can decide to collect account information (username, given name & last name, affiliation, etc.) as well as create custom questions (e.g., What do you plan to use this data for?). You are also able to download the data collected from the enabled guestbooks as Excel files to store and use outside of the Dataverse installation.
+Guestbooks allow you to collect data about who is downloading the files from your datasets. You can decide to collect account information (username, given name & last name, affiliation, etc.) as well as create custom questions (e.g., What do you plan to use this data for?). You are also able to download the data collected from the enabled guestbooks as CSV files to store and use outside of the Dataverse installation.
 
 How do you create a guestbook?
 
-#. After creating a Dataverse collection, click on the Edit Dataverse button and select Dataset Guestbook
-#. By default, guestbooks created in the Dataverse collection your Dataverse collection is in, will appear. If you do not want to use or see those guestbooks, uncheck the checkbox that says Include Guestbooks from Root Dataverse.
-#. To create a new guestbook, click the Create Dataset Guestbook button on the right side of the page. 
-#. Name the guestbook, determine the account information that you would like to be required (all account information fields show when someone downloads a file), and then add Custom Questions (can be required or not required). 
-#. Hit the Create Dataset Guestbook button once you have finished.
+#. After creating a Dataverse collection, click on the "Edit Dataverse" button and select "Dataset Guestbooks".
+#. To create a new guestbook, click the "Create Dataset Guestbook" button on the right side of the page. 
+#. Name the guestbook, determine the account information that you would like to be required (all account information fields show when someone downloads a file), and then add custom questions (can be required or not required), if desired.
+#. Click the "Create Dataset Guestbook" button once you have finished.
 
-What can you do with a guestbook? After creating a guestbook, you will notice there are several options for a guestbook and appear in the list of guestbooks. 
+What can you do with a guestbook? After creating a guestbook, you will notice there are several options for a guestbook that appear in the list of guestbooks.
 
-- If you want to use a guestbook you have created, you will first need to click the button in the Action column that says Enable. Once a guestbook has been enabled, you can go to the License + Terms for a dataset and select a guestbook for it.
-- There are also options to view, copy, edit, or delete a guestbook.
-- Once someone has downloaded a file in a dataset where a guestbook has been assigned, an option to download collected data will appear. 
+- From the dataset page, you can select a guestbook by clicking "Terms" and then "Edit Terms Requirements", unless the guestbook is disabled.
+- From the "Manage Dataset Guestbooks" page, there are options to view, copy, edit, disable, or delete a guestbook. There are also options to download or view responses. By default, guestbooks inherited from the parent Dataverse collection will appear. If you do not want to use or see those guestbooks, uncheck the checkbox that says "Include Guestbooks from [Parent]".
+- Note that it is also possible to download guestbook responses via API. See :ref:`download-guestbook-api` for details.
 
 .. _featured-dataverses:
 

src/main/java/edu/harvard/iq/dataverse/ManageGuestbooksPage.java

@@ -338,4 +338,21 @@ public String updateGuestbooksRoot(javax.faces.event.AjaxBehaviorEvent event) th
         }
         return "";
     }
+
+    public void streamResponsesByDataverseAndGuestbook(Long guestbookId) {
+        FacesContext ctx = FacesContext.getCurrentInstance();
+        HttpServletResponse response = (HttpServletResponse) ctx.getExternalContext().getResponse();
+        response.setContentType("text/comma-separated-values");
+        String fileNameString = "attachment;filename=" + getFileName();
+        response.setHeader("Content-Disposition", fileNameString);
+        try {
+            ServletOutputStream out = response.getOutputStream();
+            guestbookResponseService.streamResponsesByDataverseIdAndGuestbookId(out, dataverseId, guestbookId);
+            out.flush();
+            ctx.responseComplete();
+        } catch (Exception e) {
+            logger.warning("Failed to stream collected guestbook responses for guestbook " + guestbookId + ", dataverse " + dataverseId);
+        }
+    }
+
 }

src/main/java/propertyFiles/Bundle.properties

@@ -1222,7 +1222,8 @@ dataset.manageGuestbooks.noGuestbooks.why.reason2=You can download the data coll
 dataset.manageGuestbooks.noGuestbooks.how.header=How To Use Guestbooks
 dataset.manageGuestbooks.noGuestbooks.how.tip1=A guestbook can be used for multiple datasets but only one guestbook can be used for a dataset.
 dataset.manageGuestbooks.noGuestbooks.how.tip2=Custom questions can have free form text answers or have a user select an answer from several options.
-dataset.manageGuestbooks.noGuestbooks.getStarted=To get started, click on the Create Dataset Guestbook button above. To learn more about Guestbooks, visit the <a href="{0}/{1}/user/dataverse-management.html#dataset-guestbooks" title="Dataset Guestbook - Dataverse User Guide" target="_blank">Dataset Guestbook</a> section of the User Guide.
+dataset.manageGuestbooks.noGuestbooks.getStarted=To get started, click on the Create Dataset Guestbook button above.
+dataset.manageGuestbooks.noGuestbooks.learnMore=To learn more about guestbooks, visit the <a href="{0}/{1}/user/dataverse-management.html#dataset-guestbooks" title="Dataset Guestbook - Dataverse User Guide" target="_blank">Dataset Guestbook</a> section of the User Guide.
 dataset.manageGuestbooks.tab.header.name=Guestbook Name
 dataset.manageGuestbooks.tab.header.date=Date Created
 dataset.manageGuestbooks.tab.header.usage=Usage
@@ -1793,7 +1794,7 @@ file.dataFilesTab.terms.list.termsOfAccess.addInfo.studyCompletion=Study Complet
 file.dataFilesTab.terms.list.termsOfAccess.addInfo.studyCompletion.title=Relationship of the data collected to the amount of data coded and stored in the Dataset. Information as to why certain items of collected information were not included in the dataset or a specific data file should be provided.
 file.dataFilesTab.terms.list.guestbook=Guestbook
 file.dataFilesTab.terms.list.guestbook.title=User information (i.e., name, email, institution, and position) will be collected when files are downloaded.
-file.dataFilesTab.terms.list.guestbook.noSelected.tip=No guestbook is assigned to this dataset, you will not be prompted to provide any information on file download.
+file.dataFilesTab.terms.list.guestbook.noSelected.tip=No guestbook is assigned to this dataset so users will not be prompted to provide any information when downloading files.
 file.dataFilesTab.terms.list.guestbook.noSelected.admin.tip=There are no guestbooks available in {0} to assign to this dataset.
 file.dataFilesTab.terms.list.guestbook.inUse.tip=The following guestbook will prompt a user to provide additional information when downloading a file.
 file.dataFilesTab.terms.list.guestbook.viewBtn=Preview Guestbook

src/main/webapp/dataset-license-terms.xhtml

@@ -446,7 +446,8 @@
            </div>
        </div>
 
-        <div class="panel panel-default" jsf:rendered="#{!settingsWrapper.rsyncOnly and (managePage==false or datasetPage == true)}">
+        <div class="panel panel-default" jsf:rendered="#{!settingsWrapper.rsyncOnly and (managePage==false or datasetPage == true)
+                                                         and (!empty DatasetPage.dataset.guestbook or (dataverseSession.user.authenticated and permissionsWrapper.canIssueUpdateDatasetCommand(DatasetPage.dataset)))}">
            <div data-toggle="collapse" data-target="#panelCollapseGuestbook" class="panel-heading text-info">
                #{bundle['file.dataFilesTab.terms.list.guestbook']} &#160;<span class="glyphicon glyphicon-chevron-up"/>
            </div>
@@ -464,7 +465,13 @@
                                                         and ((!dataverseSession.user.authenticated or !permissionsWrapper.canIssueUpdateDatasetCommand(DatasetPage.dataset))
                                                         or ((dataverseSession.user.authenticated and permissionsWrapper.canIssueUpdateDatasetCommand(DatasetPage.dataset) 
                                                            and !empty DatasetPage.dataset.dataverseContext.availableGuestbooks)))}">
-                                   <p>#{bundle['file.dataFilesTab.terms.list.guestbook.noSelected.tip']}</p>
+                                   <p class="help-block">
+                                       #{bundle['file.dataFilesTab.terms.list.guestbook.noSelected.tip']}
+                                       <h:outputFormat value="#{bundle['dataset.manageGuestbooks.noGuestbooks.learnMore']}" escape="false">
+                                           <f:param value="#{systemConfig.guidesBaseUrl}"/>
+                                           <f:param value="#{systemConfig.guidesVersion}"/>
+                                       </h:outputFormat>
+                                   </p>
                                </ui:fragment>
                                <ui:fragment rendered="#{empty DatasetPage.dataset.guestbook 
                                                  and (dataverseSession.user.authenticated and permissionsWrapper.canIssueUpdateDatasetCommand(DatasetPage.dataset))
@@ -490,7 +497,13 @@
                                </ui:fragment>
                            </ui:fragment>
                            <ui:fragment rendered="#{!empty editMode and datasetPage}">
-                               <p class="help-block">#{bundle['file.dataFilesTab.terms.list.guestbook.select.tip']}</p>
+                               <p class="help-block">
+                                   #{bundle['file.dataFilesTab.terms.list.guestbook.select.tip']}
+                                       <h:outputFormat value=" #{bundle['dataset.manageGuestbooks.noGuestbooks.learnMore']}" escape="false">
+                                            <f:param value="#{systemConfig.guidesBaseUrl}"/>
+                                            <f:param value="#{systemConfig.guidesVersion}"/>
+                                        </h:outputFormat>
+                               </p>
 
                                <ui:fragment rendered="#{empty DatasetPage.dataset.dataverseContext.availableGuestbooks}">
                                    <p class="help-block">

src/main/webapp/guestbook.xhtml

@@ -44,6 +44,14 @@
                         </div>
                     </ui:fragment>
 
+                    <div class="alert alert-info">
+                        <span class="glyphicon glyphicon-info-sign"></span>
+                        <h:outputFormat value=" #{bundle['dataset.manageGuestbooks.noGuestbooks.learnMore']}" escape="false">
+                            <f:param value="#{systemConfig.guidesBaseUrl}"/>
+                            <f:param value="#{systemConfig.guidesVersion}"/>
+                        </h:outputFormat>
+                    </div>
+
                     <!-- Tabs -->
                     <div class="form-horizontal" jsf:rendered="#{!empty GuestbookPage.editMode}">
                         <div class="form-group">

src/main/webapp/manage-guestbooks.xhtml

@@ -67,7 +67,8 @@
                                     </li>
                                 </ul>
                                 <p>
-                                    <h:outputFormat value="#{bundle['dataset.manageGuestbooks.noGuestbooks.getStarted']}" escape="false">
+                                    <h:outputText value="#{bundle['dataset.manageGuestbooks.noGuestbooks.getStarted']} "/>
+                                    <h:outputFormat value="#{bundle['dataset.manageGuestbooks.noGuestbooks.learnMore']}" escape="false">
                                         <f:param value="#{systemConfig.guidesBaseUrl}"/>
                                         <f:param value="#{systemConfig.guidesVersion}"/>
                                     </h:outputFormat>
@@ -129,6 +130,10 @@
                                                       title="#{bundle['dataset.manageGuestbooks.tab.action.btn.edit']}">
                                             <span class="glyphicon glyphicon-pencil no-text"></span>
                                         </h:outputLink>
+                                        <button class="btn btn-default" data-toggle="tooltip" title="#{bundle['dataset.manageGuestbooks.download.responses']}"
+                                                jsf:id="downloadResponsesByDvAndGuestbook" jsf:action="#{manageGuestbooksPage.streamResponsesByDataverseAndGuestbook(guestbook.id)}">
+                                            <span class="glyphicon glyphicon-download-alt"/>
+                                        </button>
                                         <p:commandLink styleClass="btn btn-default bootstrap-button-tooltip"
                                                        action="#{manageGuestbooksPage.setSelectedGuestbook(guestbook)}"
                                                        rendered="#{manageGuestbooksPage.dataverse.id eq guestbook.dataverse.id and guestbook.deletable}"