How to Add Smart Previews to Web Pages Outside of SmartHub

Smart Previews for SmartHub can be used within a custom search page without loading the SmartHub UI framework.

To load Smart Previews as a stand-alone component, you must first load a JavaScript file, as described in the topics below.

 

How to Load the SmartHub Smart Previews API

Use the steps below to load the SmartHub Smart Previews API:

  1. Locate the SmartPreviewsAPI.js file.
    1. Find it at <SmartHub_Folder_Install_Dir>/modules/SmartPreviews/SmartPreviewsAPI.js
  2. Load the SmartPreviewsAPI.js file in your custom page.
  3. (Optional) Load the file SmartHubFolderInstallLocation/modules/SmartPreviews/SmartPreviews.css
    1. This is required only if you want to show the document preview in a custom container.
    2. Check the BAI.SmartPreviews.ShowDocumentPreview function definition and the sample integration example below for more details.

SmartHub Smart Previews API Functions and Parameters

  • BAI.SmartPreviewAddress
    • This string represents the Smart Previews Web Resources site address.
  • BAI.SmartPreviews.LoadSmartPreviews
    • This method loads the required SmartPreviews resources.
    • This method must be called on each page load. 
    • Parameters:
      • address:
        • This is the SmartPreviews Web Resources site address.
        • Example: https://smartpreviewswebresources.bainsight.com
      • securityTokenFunction:
        • A function that provides a new token when the requests are failing with the unauthorized exception.
          Note: If after 5 attempts the requests still fail, a warning message will be displayed in the console and the unauthorized error will be displayed in the preview viewer.
      • callback:
        • Callback function that will be called when the resource loading is complete.
          Note: You must wait for the callback function to be called before trying to show previews.
  • BAI.SmartPreviews.SetSecurityToken
    • This function sets the internal authentication token that SmartPreviews uses.
    • It must be called on each page load and every time the token expires. 
    • Parameters:
      • token: OAuth2 compliant JWT token.
        • Token must be valid (not expired) and contain the "upn" claim.
  • BAI.SmartPreviews.CheckForPreviews
    • This function checks the database for the preview generation status for documents.
    • SmartHub uses this function to decide if documents support Smart Previews and adds the binoculars icon.
    • Parameters:
      • documentDefinition 

        • Array of objects which define document definitions.

          • Each object must have the following structure (note that the URL property must be URL encoded):

            Copy
            var itemDefinition = {
                        Url: encodeURIComponent(<document_url>),
                        Title: <document_title>,
                        Extension: <document_extension>,
                        LastModified: <document_lastModifiedDate>,
                        FileSize: <document_size>
                    }
      • callback
        • Callback function that is called when the response is ready.
        • The response is a JSON string so you need to parse it before using it.
        • It contains pairs of document URLs and preview status codes:
          • Previews status codes:
            • 0 - Document preview is generated in the database
            • 1 - Document is not eligible for on-demand preview generation
            • 2 - Document is eligible for on-demand preview generation
            • 3 - Document preview generation is in progress (status will become 0)
  • BAI.SmartPreviews.ShowDocumentPreview
    • This function shows the document preview
    • Parameters 
      • documentUri
        • Document URL which must be encoded.
      • documentOriginalPath
        • The original URL of the document, not the escbasecrawlurl, which must be encoded.
      • documentTitle
        • The document title that will appear at the top of the Document Viewer.
        • Default value: "Preview".
      • keywords
        • String containing the words that should be highlighted in the document preview.
      • options
        • OpenSearchPanelByDefault: Set to true to open the search inside panel, by default, when opening the document viewer.

        • OpenBookmarksPanelByDefault: Set to true to open the bookmarks panel, by default, when opening the document viewer.

          Limitation: You cannot have both OpenSearchPanelByDefault and OpenBookmarksPanelByDefault set to true at the same time.

        • ShowDescriptiveText: Set to true to display a descriptive text to help users understand what they see in the document viewer.

        • WidgetsToLoadForCustomViewer: Specify what widgets to load when the preview is displayed in a custom viewer:

          1. htmlPreview (Required): Displays the preview content.
          2. docNav (Required): Displays the navigation bar for pagination.
          3. zoomControl (Optional): Displays the zoom control.

          4. searchToolbar (Optional): Displays the button that shows/hides the "Search inside" panel.

            If the OpenSearchPanelByDefault setting is set to true, the searchToolbar widget becomes required.

          5. docActions (Optional): Displays the preview actions button.
          6. bookmarksToolbar (Optional): Displays the button that shows/hides the bookmarks panel.
        • UITimeoutSeconds:The number of seconds after which the TimeoutWarningMessage is displayed. 
          • Note: If you do not want to display a message, set it to -1.
        •  TimeoutWarningMessage: The message that will be displayed when the online previews generation takes too long.
          • Default value:"Generating preview for this document is taking longer than %time% seconds. Please check back in a few minutes." 

          • %time%will be replaced with the actual number specified in the UITimeoutSeconds setting.

            Limitation: UITimeoutSecondsUITimeoutSeconds and TimeoutWarningMessage settings work only with SmartPreviews 3.3 or newer versions.

      • parentContainerSelector (Optional) - Use this if you want to show the document preview in a custom page container.
        • If left unspecified then the preview will be shown in the Document Viewer (right side of screen).
        • If you want to use a custom container then you must ensure container CSS plays well with the default SmartPreviews CSS.
        • A good starting point would be to inject the SmartPreviews.css file.
        • Check the "Sample integration in a new HTML page" section below. 
  • BAI.SmartPreviews.RemoveAllViewers
    • Function that closes all the open Document Viewers
  • BAI.SmartPreviews.GetPreviewVersion
    • This function returns the major version of the installed Smart Previews version.

Sample Integration in a New HTML Page

The following HTML page does the following, in order:

  1. Loads the SmartHub SmartPreviews API via the "/modules/SmartPreviews/SmartPreviewsAPI.js" file.
  2. Load the custom SmartPreviews CSS via the "/modules/SmartPreviews/SmartPreviews.css" file.
  3. Loads the SmartPreviews resources by calling the BAI.SmartPreviews.LoadSmartPreviews function.
  4. Sets the security token.
  5. Defines a sample document URL.
  6. Checks the preview status for the document by calling the BAI.SmartPreviews.CheckForPreviews function.
    1. Logs the response in the browser console.
  7. Shows document preview in the Document Viewer via the call to BAI.SmartPreviews.ShowDocumentPreview(encodeURIComponent(itemUrl), encodeURIComponent(originalItemUrl), "Document preview", "query here");
  8. Shows document preview in the <div> with  id="previewContainer" via the call to  BAI.SmartPreviews.ShowDocumentPreview(encodeURIComponent(itemUrl), encodeURIComponent(originalItemUrl), "Document preview", "query here", undefined, "#previewContainer");
Copy 
<!DOCTYPE html>
<html lang="en">
 
<head>
     
    <link rel="stylesheet" href="http://localhost:5598/modules/SmartPreviews/SmartPreviews.css">
    <script type="text/javascript" src="http://localhost:5598/modules/SmartPreviews/SmartPreviewsAPI.js"></script>
     
    <script>
     
    var smartPreviewsAddress = "https://smpwebresources.bainsight.com";
    BAI.SmartPreviews.LoadSmartPreviews(smartPreviewsAddress, function () {
        
        var token = "eyJ0eXAiOiJKV1...";
        BAI.SmartPreviews.SetSecurityToken(token);
         
        var itemUrl = "https://tenant.sharepoint.com/sites/MySite/Documents/sample document.pdf"; //url must be decoded
         
        BAI.SmartPreviews.CheckForPreviews([itemUrl], function (response) {
            console.log(response);
        });
         
        BAI.SmartPreviews.ShowDocumentPreview(encodeURIComponent(itemUrl), encodeURIComponent(originalItemUrl), "Document preview", "query here", { OpenSearchPanelByDefault: true });
         
       // BAI.SmartPreviews.ShowDocumentPreview(encodeURIComponent(itemUrl), encodeURIComponent(originalItemUrl), "Document preview", "query here", { OpenSearchPanelByDefault: true, WidgetsToLoadForCustomViewer: ["htmlPreview", "docNav", "searchToolbar"] }, "#previewContainer");
 
    });
    </script>
     
</head>
 
 
<body>
    <div id="previewContainer" class="bai-document-viewer-container"></div>
</body>
 
</html>