3758 file page preview

doc/sphinx-guides/source/admin/external-tools.rst

@@ -37,6 +37,8 @@ In the curl command below, replace the placeholder "fabulousFileTool.json" place
 
   curl -X POST -H 'Content-type: application/json' http://localhost:8080/api/admin/externalTools --upload-file fabulousFileTool.json 
 
+Note that some tools will provide a preview mode, which provides an embedded, simplified view of the tool on the file pages of your installation. This is controlled by the `hasPreviewMode` parameter. 
+
 Listing All External Tools in Dataverse
 +++++++++++++++++++++++++++++++++++++++
 
@@ -76,10 +78,15 @@ Once you have added an external tool to your installation of Dataverse, you will
 File Level Explore Tools
 ++++++++++++++++++++++++
 
-File level explore tools are specific to the file type (content type or MIME type) of the file. For example, there is a tool for exploring PDF files in the "File Previewers" set of tools.
+File level explore tools are specific to the file type (content type or MIME type) of the file. For example, Data Explorer is tool for exploring tabular data files.
 
 An "Explore" button will appear (on both the dataset page and the file landing page) for files that match the type that the tool has been built for. When there are multiple explore tools for a filetype, the button becomes a dropdown.
 
+File Level Preview Tools
+++++++++++++++++++++++++
+
+File level explore tools can be set up to display in preview mode, which is a simplified view of an explore tool designed specifically for embedding in the file page. 
+
 File Level Configure Tools
 ++++++++++++++++++++++++++
 

doc/sphinx-guides/source/admin/integrations.rst

@@ -90,7 +90,7 @@ Dataverse supports a protocol called OAI-PMH that facilitates harvesting dataset
 SHARE
 +++++
 
-`SHARE <http://www.share-research.org>`_ is building a free, open, data set about research and scholarly activities across their life cycle. It's possible to add and installation of Dataverse as one of the `sources <https://share.osf.io/sources>`_ they include if you contact the SHARE team.
+`SHARE <http://www.share-research.org>`_ is building a free, open, data set about research and scholarly activities across their life cycle. It's possible to add an installation of Dataverse as one of the `sources <https://share.osf.io/sources>`_ they include if you contact the SHARE team.
 
 Research Data Preservation
 --------------------------

doc/sphinx-guides/source/api/external-tools.rst

@@ -29,7 +29,13 @@ Note: This is the same list that appears in the :doc:`/admin/external-tools` sec
 How External Tools Are Presented to Users
 -----------------------------------------
 
-In short, an external tool appears under an "Explore" or "Configure" button either on a dataset landing page or a file landing page. See also the :ref:`testing-external-tools` section of the Admin Guide for some perspective on how installations of Dataverse will expect to test your tool before announcing it to their users.
+An external tool can appear in Dataverse in one of three ways:
+
+- under an "Explore" or "Configure" button either on a dataset landing page
+- under an "Explore" or "Configure" button on a file landing page
+- as an embedded preview on the file landing page
+
+See also the :ref:`testing-external-tools` section of the Admin Guide for some perspective on how installations of Dataverse will expect to test your tool before announcing it to their users.
 
 Creating an External Tool Manifest
 ----------------------------------
@@ -75,6 +81,8 @@ Terminology
     type                         Whether the external tool is an **explore** tool or a **configure** tool. Configure tools require an API token because they make changes to data files (files within datasets). Configure tools are currently not supported at the dataset level (no "Configure" button appears in the GUI for datasets).
 
     toolUrl                      The **base URL** of the tool before query parameters are added.
+
+    hasPreviewMode               A boolean that indicates whether tool has a preview mode which can be embedded in the File Page. Since this view is designed for embedding within Dataverse, the preview mode for a tool will typically be a view without headers or other options that may be included with a tool that is designed to be launched in a new window. Sometimes, a tool will exist solely to preview files in Dataverse and the preview mode will be the same as the regular view. 
 
     contentType                  File level tools operate on a specific **file type** (content type or MIME type such as "application/pdf") and this must be specified. Dataset level tools do not use contentType.
 

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

@@ -69,7 +69,7 @@ If there are multiple upload options available, then you must choose which one t
 
 You can upload files to a dataset while first creating that dataset. You can also upload files after creating a dataset by clicking the "Edit" button at the top of the dataset page and from the dropdown list selecting "Files (Upload)" or clicking the "Upload Files" button above the files table in the Files tab. From either option you will be brought to the Upload Files page for that dataset.
 
-Certain file types in Dataverse are supported by additional functionality, which can include downloading in different formats, file-level metadata preservation, file-level data citation with UNFs, and exploration through data visualization and analysis. See the :ref:`File Handling <file-handling>` section of this page for more information.
+Certain file types in Dataverse are supported by additional functionality, which can include downloading in different formats, previews, file-level metadata preservation, file-level data citation with UNFs, and exploration through data visualization and analysis. See the :ref:`File Handling <file-handling>` section of this page for more information.
 
 
 HTTP Upload
@@ -143,8 +143,12 @@ DVUploader is a community-developed tool, and its creation was primarily support
 File Handling
 =============
 
-Certain file types in Dataverse are supported by additional functionality, which can include downloading in different formats, file-level metadata preservation, file-level data citation; and exploration through data visualization and analysis. See the sections below for information about special functionality for specific file types.
+Certain file types in Dataverse are supported by additional functionality, which can include downloading in different formats, previews, file-level metadata preservation, file-level data citation; and exploration through data visualization and analysis. See the sections below for information about special functionality for specific file types.
 
+File Previews
+-------------
+
+Installations of Dataverse can install previewers for common file types uploaded by their research communities. The previews appear on the file page. If a preview tool for a specific file type is available, the preview will be created and will display automatically. File previews are not available for restricted files.
 
 Tabular Data Files
 ------------------
@@ -296,7 +300,7 @@ Here is an `example of a Data Usage Agreement <https://dataverse.org/best-practi
 Restricted Files + Terms of Access 
 ----------------------------------
 
-If you restrict any files in your dataset, you will be prompted by a pop-up to enter Terms of Access for the data. This can also be edited in the Terms tab or selecting Terms in the "Edit" dropdown button in the dataset. You may also allow users to request access for your restricted files by enabling "Request Access". To add more information about the Terms of Access, we have provided fields like Data Access Place, Availability Status, Contact for Access, etc.
+If you restrict any files in your dataset, you will be prompted by a pop-up to enter Terms of Access for the data. This can also be edited in the Terms tab or selecting Terms in the "Edit" dropdown button in the dataset. You may also allow users to request access for your restricted files by enabling "Request Access". To add more information about the Terms of Access, we have provided fields like Data Access Place, Availability Status, Contact for Access, etc. If you restrict a file, it will not have a preview shown on the file page.
 
 **Note:** Some Dataverse installations do not allow for file restriction.
 

doc/sphinx-guides/source/user/find-use-data.rst

@@ -62,7 +62,11 @@ Once on a dataset page, you will see the title, citation, description, and sever
 View Files
 ----------
 
-Files in Dataverse each have their own page that can be reached through the search results or through the Files table on their parent dataset's page. The dataset page and file page offer much the same functionality in terms of viewing and editing files, with a few small exceptions. The file page includes the file's persistent identifier (DOI or handle), which can be found under the Metadata tab. Also, the file page's Versions tab gives you a version history that is more focused on the individual file rather than the dataset as a whole. 
+Files in Dataverse each have their own landing page that can be reached through the search results or through the Files table on their parent dataset's page. The dataset page and file page offer much the same functionality in terms of viewing and editing files, with a few small exceptions. 
+
+- In installations that have enabled support for persistent identifers (PIDs) at the file level, the file page includes the file's DOI or handle, which can be found in the file citation and also under the Metadata tab.
+- Previewers for several common file types are available and can be added by installation administrators.
+- The file page's Versions tab gives you a version history that is more focused on the individual file rather than the dataset as a whole. 
 
 File Search within Datasets
 ---------------------------
@@ -89,6 +93,8 @@ You can find the citation for the dataset at the top of the dataset page in a bl
 
 .. _download_files:
 
+In installations that have added file-level citations, you can find and download the file's citation on the file page in a similar manner.
+
 Download Files
 --------------
 

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

@@ -9,6 +9,9 @@
 import edu.harvard.iq.dataverse.dataaccess.SwiftAccessIO;
 import edu.harvard.iq.dataverse.authorization.AuthenticationServiceBean;
 import edu.harvard.iq.dataverse.authorization.Permission;
+import edu.harvard.iq.dataverse.authorization.users.ApiToken;
+import edu.harvard.iq.dataverse.authorization.users.AuthenticatedUser;
+import edu.harvard.iq.dataverse.authorization.users.User;
 import edu.harvard.iq.dataverse.dataaccess.StorageIO;
 import edu.harvard.iq.dataverse.datasetutility.WorldMapPermissionHelper;
 import edu.harvard.iq.dataverse.engine.command.Command;
@@ -22,6 +25,7 @@
 import edu.harvard.iq.dataverse.export.ExportService;
 import edu.harvard.iq.dataverse.export.spi.Exporter;
 import edu.harvard.iq.dataverse.externaltools.ExternalTool;
+import edu.harvard.iq.dataverse.externaltools.ExternalToolHandler;
 import edu.harvard.iq.dataverse.externaltools.ExternalToolServiceBean;
 import edu.harvard.iq.dataverse.makedatacount.MakeDataCountLoggingServiceBean;
 import edu.harvard.iq.dataverse.makedatacount.MakeDataCountLoggingServiceBean.MakeDataCountEntry;
@@ -34,6 +38,8 @@
 import edu.harvard.iq.dataverse.util.SystemConfig;
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Comparator;
 import java.util.List;
 import java.util.Set;
 import java.util.logging.Logger;
@@ -71,6 +77,7 @@ public class FilePage implements java.io.Serializable {
     private String persistentId;
     private List<ExternalTool> configureTools;
     private List<ExternalTool> exploreTools;
+    private List<ExternalTool> toolsWithPreviews;
 
     @EJB
     DataFileServiceBean datafileService;
@@ -208,7 +215,11 @@ public String init() {
             }
             configureTools = externalToolService.findFileToolsByTypeAndContentType(ExternalTool.Type.CONFIGURE, contentType);
             exploreTools = externalToolService.findFileToolsByTypeAndContentType(ExternalTool.Type.EXPLORE, contentType);
-
+            Collections.sort(exploreTools, CompareExternalToolName);
+            toolsWithPreviews  = addMapLayerAndSortExternalTools();
+            if(!toolsWithPreviews.isEmpty()){
+                setSelectedTool(toolsWithPreviews.get(0));                
+            }
         } else {
 
             return permissionsWrapper.notFound();
@@ -226,6 +237,30 @@ public FileMetadata getFileMetadata() {
         return fileMetadata;
     }
 
+    private List<ExternalTool> addMapLayerAndSortExternalTools(){
+        List<ExternalTool> retList = externalToolService.findFileToolsByTypeContentTypeAndAvailablePreview(ExternalTool.Type.EXPLORE, file.getContentType());
+        if(!retList.isEmpty()){
+            retList.forEach((et) -> {
+                et.setWorldMapTool(false);
+            });
+        }
+        if (file != null && worldMapPermissionHelper.getMapLayerMetadata(file) != null && worldMapPermissionHelper.getMapLayerMetadata(file).getEmbedMapLink() != null) {
+            ExternalTool wpTool = new ExternalTool();
+            wpTool.setDisplayName("World Map"); 
+            wpTool.setToolParameters("{}");
+            wpTool.setToolUrl(worldMapPermissionHelper.getMapLayerMetadata(file).getEmbedMapLink());
+            wpTool.setWorldMapTool(true);
+            retList.add(wpTool);
+        }
+        Collections.sort(retList, CompareExternalToolName);
+
+        return retList;
+    }
+
+    /*
+    worldMapPermissionHelper.getMapLayerMetadata(FilePage.fileMetadata.dataFile).getEmbedMapLink()
+    */
+
 
     public boolean isDownloadPopupRequired() {  
         if(fileMetadata.getId() == null || fileMetadata.getDatasetVersion().getId() == null ){
@@ -888,10 +923,45 @@ public List<ExternalTool> getExploreTools() {
         return exploreTools;
     }
 
+    public List<ExternalTool> getToolsWithPreviews() {
+        return toolsWithPreviews;
+    }
+
+    private ExternalTool selectedTool;
+
+    public ExternalTool getSelectedTool() {
+        return selectedTool;
+    }
+
+    public void setSelectedTool(ExternalTool selectedTool) {
+        this.selectedTool = selectedTool;
+    }
+
+    public String preview(ExternalTool externalTool) {
+        ApiToken apiToken = null;
+        User user = session.getUser();
+        if (user instanceof AuthenticatedUser) {
+            apiToken = authService.findApiTokenByUser((AuthenticatedUser) user);
+        }
+        if(externalTool == null){
+            return "";
+        }
+        ExternalToolHandler externalToolHandler = new ExternalToolHandler(externalTool, file, apiToken, file.getFileMetadata(), session.getLocaleCode());
+        String toolUrl = externalToolHandler.getToolUrlForPreviewMode();
+        return toolUrl;
+    }
+
     //Provenance fragment bean calls this to show error dialogs after popup failure
     //This can probably be replaced by calling JsfHelper from the provpopup bean
     public void showProvError() {
         JH.addMessage(FacesMessage.SEVERITY_ERROR, BundleUtil.getStringFromBundle("file.metadataTab.provenance.error"));
     }
+
+    private static final Comparator<ExternalTool> CompareExternalToolName = new Comparator<ExternalTool>() {
+        @Override
+        public int compare(ExternalTool o1, ExternalTool o2) {
+            return o1.getDisplayName().toUpperCase().compareTo(o2.getDisplayName().toUpperCase());
+        }
+    };
 
 }

src/main/java/edu/harvard/iq/dataverse/externaltools/ExternalTool.java

@@ -11,6 +11,7 @@
 import javax.persistence.GeneratedValue;
 import javax.persistence.GenerationType;
 import javax.persistence.Id;
+import javax.persistence.Transient;
 
 /**
  * A specification or definition for how an external tool is intended to
@@ -27,6 +28,7 @@ public class ExternalTool implements Serializable {
     public static final String TOOL_URL = "toolUrl";
     public static final String TOOL_PARAMETERS = "toolParameters";
     public static final String CONTENT_TYPE = "contentType";
+    public static final String HAS_PREVIEW_MODE = "hasPreviewMode";
 
     @Id
     @GeneratedValue(strategy = GenerationType.IDENTITY)
@@ -76,6 +78,22 @@ public class ExternalTool implements Serializable {
      */
     @Column(nullable = true, columnDefinition = "TEXT")
     private String contentType;
+
+    @Column(nullable = false)
+    private boolean hasPreviewMode;   
+
+
+
+    @Transient
+    private boolean worldMapTool;
+
+    public boolean isWorldMapTool() {
+        return worldMapTool;
+    }
+
+    public void setWorldMapTool(boolean worldMapTool) {
+        this.worldMapTool = worldMapTool;
+    }
 
     /**
      * This default constructor is only here to prevent this error at
@@ -99,6 +117,18 @@ public ExternalTool(String displayName, String description, Type type, Scope sco
         this.toolUrl = toolUrl;
         this.toolParameters = toolParameters;
         this.contentType = contentType;
+        this.hasPreviewMode = false;
+    }
+
+    public ExternalTool(String displayName, String description, Type type, Scope scope, String toolUrl, String toolParameters, String contentType, boolean hasPreviewMode) {
+        this.displayName = displayName;
+        this.description = description;
+        this.type = type;
+        this.scope = scope;
+        this.toolUrl = toolUrl;
+        this.toolParameters = toolParameters;
+        this.contentType = contentType;
+        this.hasPreviewMode = hasPreviewMode;
     }
 
     public enum Type {
@@ -212,7 +242,15 @@ public String getContentType() {
     public void setContentType(String contentType) {
         this.contentType = contentType;
     }
+
+    public boolean getHasPreviewMode() {
+        return hasPreviewMode;
+    }
 
+    public void setHasPreviewMode(boolean hasPreviewMode) {
+        this.hasPreviewMode = hasPreviewMode;
+    }
+
     public JsonObjectBuilder toJson() {
         JsonObjectBuilder jab = Json.createObjectBuilder();
         jab.add("id", getId());
@@ -224,6 +262,11 @@ public JsonObjectBuilder toJson() {
         jab.add(TOOL_PARAMETERS, getToolParameters());
         if (getContentType() != null) {
             jab.add(CONTENT_TYPE, getContentType());
+        }
+        if (getHasPreviewMode()) {
+            jab.add(HAS_PREVIEW_MODE, getHasPreviewMode());
+        } else {
+
         }
         return jab;
     }

src/main/java/edu/harvard/iq/dataverse/externaltools/ExternalToolHandler.java

@@ -101,6 +101,11 @@ public String getLocaleCode() {
 
     // TODO: rename to handleRequest() to someday handle sending headers as well as query parameters.
     public String getQueryParametersForUrl() {
+        return getQueryParametersForUrl(false);
+    }
+
+    // TODO: rename to handleRequest() to someday handle sending headers as well as query parameters.
+    public String getQueryParametersForUrl(boolean preview) {
         String toolParameters = externalTool.getToolParameters();
         JsonReader jsonReader = Json.createReader(new StringReader(toolParameters));
         JsonObject obj = jsonReader.readObject();
@@ -118,7 +123,11 @@ public String getQueryParametersForUrl() {
                 }
             });
         });
-        return "?" + String.join("&", params);
+        if (!preview) {
+            return "?" + String.join("&", params);
+        } else {
+            return "?" + String.join("&", params) + "&preview=true";
+        }
     }
 
     private String getQueryParam(String key, String value) {
@@ -178,6 +187,10 @@ private String getQueryParam(String key, String value) {
     public String getToolUrlWithQueryParams() {
         return externalTool.getToolUrl() + getQueryParametersForUrl();
     }
+
+    public String getToolUrlForPreviewMode() {
+        return externalTool.getToolUrl() + getQueryParametersForUrl(true);
+    }
 
     public ExternalTool getExternalTool() {
         return externalTool;