Skip to content

Shockbrowse Widget

Jump to bottom
Tobias Paczian edited this page Mar 28, 2018 · 10 revisions

image

overview

The Shockbrowser is a Retina widget that allows a finder / explorer like view and access to a SHOCK data store. It is highly configurable to support multiple views on the data, like node information, permissions and previews of attached files. It allows for upload, download and deletion of files as well as editing of node attributes and permissions.

You can add custom views and preset filters, virtual directories, custom buttons and more. The next section provides a short tutorial on Shockbrowser customization. The final section lists all options with descriptions and defaults.

shockbrowser basic setup

To add a shockbrowser to your page you only need a very minimal setup. All that is required is the base URL of a SHOCK data server and a target div on the web page. Lets assume you have the setup from the basic tutorial with some slight modifications.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">

    <title>Retina Turorial</title>
    <link rel="icon" href="images/favicon.ico" type="image/x-icon">
    
    <!-- bootstrap style-->
    <link rel="stylesheet" href="Retina/css/bootstrap.min.css">
    
    <!-- json-editor style-->
    <link rel="stylesheet" href="Retina/css/jsoneditor.mins.css">

    <!-- custom style-->
    <link rel="stylesheet" href="css/tutorial.css">
    
    <!-- javascript files-->
    <script type="text/javascript" src="Retina/js/stm.js"></script>
    <script type="text/javascript" src="Retina/js/retina.js"></script>
    <script type="text/javascript" src="Retina/js/jquery.min.js"></script>
    <script type="text/javascript" src="Retina/js/bootstrap.min.js"></script>

    <!-- config file-->
    <script type="text/javascript" src="js/config.js"></script>
    
    <!--initialization-->
    <script type="text/javascript">
    jQuery(document).ready(function() {
	stm.init({});
        Retina.init({ widget_resource: "widgets" });
        Retina.load_widget("shockbrowse").then( function () {
            Retina.Widget.create("shockbrowse", { "target": document.getElementById("content")});
        });
    });
    </script>
    
  </head>
  <body>
    <div class="container">
        <h2>Shockbrowser Demo</h2>    

        <div id="content"></div>
    </div>
  </body>
</html>

A few things are modified from the basic setup. One additional stylesheet is loaded, jsoneditor.min.css. It contains the styles for the JSON editor that is used to view and edit node attributes. The HTML content is wrapped in a class container div from bootstrap, which makes it look a little nicer. Finally we obviously do not want to load and create the tutorial widget, but the shockbrowse widget. Please note that it is entirely possible to load multiple different widgets onto the same page.

The final configuration you have to make is providing the URL of the SHOCK data server. Per default, the shockbrowse widget looks at the RetinaConfig.shock_url variable. So we make our config.js look like this (exchange http://my.shock.url with the base URL of you shock server).

RetinaConfig = {
  "shock_url": "http://my.shock.url"
}

views

In the default setup the Shockbrowser main window is separated into three parts. From left to right it has a filter section, a file list and a detail view. Above the main window is a toolbar, below is a status bar. Per default the bar between the file list and detail view can be dragged. The bottom left corner of the status bar allows resizing of the entire widget.

The filter section shows a customizable list of default filter attributes and a filter text box. Adding a filter displays a button to remove the filter, there is also a remove all filters option. Filters of the same key will replace the existing filter. The filter section can optionally show folder filters, which are an implementation of virtual directories.

The file list section shows a tabular view of all files that meet the current filter criteria. A defined number of these are loaded at a time. If more than 100 (this number can be customized) files match the current filter, scrolling to the bottom of the list will trigger loading of an additional 100 entries, which are appended to the list. There is a default set of columns in the list, but these can be changed. There is also a setting for the with of these columns. Clicking one or multiple files triggers a detail view.

The detail section shows one of a set of detail views of the currently selected file(s). There are four different views, one of which can be customized. The info view shows basic information of the current node. The attributes view shows all attributes of the node and optionally allows to edit them. The acl view shows the permissions of the node and allows deletion and creation of them. The preview view shows a preview of the file associated with the node. There are some default previews, but the file types for the preview can be extended. This view can be customized to provide a programmer specified view of the node or the associated file.

The toolbar at the top has buttons for upload, download and refresh, as well as select buttons for the current view. There is an option to add custom buttons here.

The status bar shows status information, e.g. how many nodes are shown out of how many match the filter criteria. A lock symbol indicates whether authentication is currently active or not. The very right features the resize corner.

features

The Shockbrowser features chunking of uploads. The chunk-size can be selected at configuration and at run-time. If chunking is enabled, resuming of file upload is supported after the last completed chunk.

After a completed file upload the Shockbrowser can automatically calculate an MD5 sum of the file on the client side and compare it with the MD5 sum reported by the SHOCK server to make sure the data has not been corrupted during upload.

For a complete list of features, please take a look at the options in the following section.

options

  • shockBase - URL of the SHOCK server to interact with, default is RetinaConfig.shock_url

  • width - width of the browser in pixel, default is 1550

  • height - height of the browser in pixel, default is 800

  • initialFileDetailRatio - initial size ratio between file and info section, default is 0.5 (both equal size)

  • title - text displayed in the title bar, default is SHOCK browser

  • autoSizeAtStartup - boolean to set the initial size to fit into the current browser window, default is false

  • showFilter - boolean whether the filter section is visible, default is true

  • showTitleBar - boolean whether the title bar is visible, default is true

  • showResizer - boolean whether the rezise buttons and corner are visible, default is true

  • middleResize - boolean whether the middle bar should allow resizing, default is true

  • showToolBar - boolean whether to show the toolbar, default is true

  • enableUpload - boolean whether upload is enabled, default is true

  • enableDownload - boolean whether download is enabled, default is true

  • enableCompressedDownload - boolean whether download as zip is enabled, default is true

  • showUploadPreview - boolean whether a preview is shown for files selected for upload, default is true

  • showDetailBar - boolean whether the detail bar is visible, default is true

  • showDetailInfo - boolean whether the detail option 'info' is available, default is true

  • showDetailAttributes - boolean whether the detail option 'attributes' is available, default is true

  • showDetailACL - boolean whether the detail option 'acl' is available, default is true

  • showDetailPreview - boolean whether the detail option 'preview' is available, default is true

  • keepSelectedFileAfterRefresh - boolean whether the selected file should stay selected after a display update, default is true

  • showStatusBar - boolean whether the status bar at the bottom is displayed, default is true

  • showTopSection - boolean whether the top section is visible, default is true

  • customButtons - array of objects that represent buttons in the toolbar. The objects have the properties:

    • title - string to be set as hover over title of the button
    • id - string, optional, will be set as the id attribute of the button
    • image - string, the path to the image the button should show
    • callback - function, the function to be called when the button is clicked

  • detailType - one of [ info, attributes, acl, preview ] indicating the initial display when selecting a file, default is info

  • presetFilters - hash of field name -> field value that is always added to the filter, default is {}

  • querymode - [ full | attributes ] determines which part of the node to search in, default is attributes

  • keylist - array of hashes of items in the filter list. The form of the hash is { "name": "$filter_url_param", "value": "$label_in_filter_list" }, default is {},

  • blacklist - hash of file names pointing to true to not show up, default is {}

  • dropdownFilters - array of string, list of the attributes to be shown as dropdown filters, default is []

  • disableCustomFilter - boolean, set to true to hide custom filter, default is false

  • folderFilters - array of objects of the following format: [ { attribute, title, dropdown }, { ... }, ... ], default is []

  • folderFiltersExclusive - boolean, if true only one of the sets is active at any one time. If false, multiple sets of filters can be combined. Default is true.

  • previewChunkSize - size in bytes that is loaded from the server for the preview of a file, default is 2048 (2 KB)

  • uploadChunkSize - size in bytes uploaded to the server per chunk, default is 10485760 (10 MB)

  • currentLimit - maximum number of files loaded initially and whenever scrolling to the bottom, default is 100

  • authHeader - authentication header used when interacting with the server, default is {}

  • customPreview - optinally provided custom function for node preview, receives an object with the selected node (node), the first previewChunkSize bytes of the file (data) and the error if exists (error), must return the HTML to be displayed in the preview section. Default is false

  • customMultiPreview - optionally provided custom function for preview of multiple file selection, receives the list of selected files, must return the HTML to be displayed in the preview section. Default is false

  • autoDecompress - automatically decompress compressed files after upload without asking the user, default is false

  • autoUnarchive - automatically unpack archives after uploading without asking the user, default is false

  • hasExpiration - set expiration time for uploads, default is off (empty string). in format of \d+[MHD] where M = minute, H = hour, D = day, default is null

  • deleteOriginalArchive - automatically delete the original archive after it has been unpacked successfully, default is true

  • uploadRestrictions - array of objects with the attributes 'expression' which is a regular expression to match a filename and 'text' which will be displayed as an error alert to the user. Filenames that match will not be able to be uploaded. Default is []

  • preUploadCustom - function that gets called when a file is selected for upload. Receives the file as a parameter. This function must return a promise that resolves passing two parameters. The first is the HTML to be displayed before the commence upload button. The second is a boolean indicating whether this file may be uploaded or not. Default is false

  • fileUploadCompletedCallback - function to be called when a file upload has completed. Gets passed the created node. Default is false

  • allFileUploadCompletedCallback - function to be called when a selection of multiple files has completed uploading. Gets passed all created nodes. Default is false

  • fileDeletedCallback - function to be called when a file has been deleted. Gets passed true upon success and false upon error and as the second parameter the node object. Default is false

  • autoUploadRefresh - boolean of whether the file list should be automatically refreshed after an upload or delete has completed. Default is false

  • calculateMD5 - boolean wheather md5 sum should be calculated on the source file and automatically compared with the taget file. Default is false.

  • MD5chunksize - size in bytes of the chunks for incremental MD5sum calculation. Default is 10485760 (10 MB)

  • fileDoneAttributes - object of attributes to set for any uploaded file, default is {}

  • fileSectionColumns - array of objects with the following attributes:

    • path - string of the path within the node (i.e. file.name) to the attribute to list
    • name - string to be displayed as the column header
    • width - HTML width string of the column, percentage values are advised
    • type - type of the column for formatting, supported values are date, size, file and string
    • align - HTML align value of the column
    • sortable - boolean whether this column may be sorted by clicking on the column header Default is [ { "path": "file.name", "name": "filename", "sortable": true } ]

  • enableDrag - boolean whether to allow dragging of file objects. Default is false

  • requireLogin - boolean to determine if updateData can be called without a login (false = get data without login, true = do not get data without login) default is false

  • initialLoadCallback - function to call when the updateData has completed for the first time. Default is false

  • order - stringified object path to order the file list by, default is last_modified

  • direction - string, either 'asc' or 'desc' representing ascending and descending sort order respectively, default is desc

  • allowMultiselect - boolean to indicate whether multiple files may be selected at a time, default is false

  • allowMultiFileUpload - boolean to indicate whether multiple files may be selected for upload at a time, default is false

  • fileList - list of SHOCK node objects that are currently displayed in the file section. This is a a read-only property.

Home

Tutorial

Retina

stm

Resources

Clone this wiki locally