About periscope2

periscope2 is a scalable and UI-standardized 'shiny' framework including a variety of developer convenience functions with the goal of both streamlining robust application development and assisting in creating a consistent user experience regardless of application or developer.

Features
  • Predefined but flexible template for new Shiny applications with a default dashboard layout
  • Separation by file of functionality that exists in one of the three shiny scopes: global, server-global, and server-local.
  • Off-the-shelf and ready to be used modules ('Table Downloader', 'Plot Downloader', 'File Downloader' and 'Reset Application'
  • Different methods and tools to alert users and add useful information about application UI and server operations
  • Application logger with different levels and a UI tool to display and review recorded application logs
  • Application look and feel can be customized easily via 'www/periscope_style.yaml' or more advanced via 'www/css/custom.cs'
  • Application can make use of JS power by customizing 'www/js/custom.js'

Announcements

Features
  • 'Announcement' feature is a user friendly method to announce a recently added feature, initiate a shutdown warning, or broadcast any news to your users at once
  • Announcements feature aim to alert app user with customized admin messages upon application start for a predefined time
  • Announcement can be either a simple text or a fully rich HTML text.
  • Announcement location is on the application header
  • Announcement status (body color) can be: 'primary', 'success', 'warning', 'danger' or 'info'
  • Application admin can control when an 'Announcement' should start to be seen and when it should be expire
  • Application admin can control how long an 'Announcement' stay visible for users or let each user close it manually
    • Setup
  • No development is needed to launch or control 'Announcements' feature, only configurations
  • Default feature generated configuration file is called announce.yaml
  • Default configuration file path is: 'program/config/announce.yaml'
  • Configuration file path can be changed based on admin preference. Only update 'announcements_file' parameter in 'set_app_parameters' method in 'program/global.R' file with the new config file path
  • Check generated configuration file self-documentation for each config variable usage details
  • Review current application example configuration for more details on how to configure/disable announcements`

    • Logger

    Features
  • Logger feature presents a developer and an admin friendly method to record different user or internal actions in their recoded time and using different logging levels
  • There are 4 different available log levels: 'logdebug', 'loginfo', 'logwarn' and 'logerror' in that order
  • Each log level is displayed in different text color in R console
  • User can control which log levels to be excluded from being displayed or recorded
    • The log rolls over for each session
    • The log files are kept in the /log directory and named 'actions.log'
    • ONE old copy of the log is kept as 'actions.log.last'
  • Beside reviewing the log files directly, admins can review logs in application via logViewer UI module
    • Setup
    • To create actions to the framework call one of the logging functions like: 

      • S: logXXXX('Your Log Message with %s, %s parameters', parm1, parm2, logger = ss_userAction.Log)

    • The XXXX should be replaced by an actual log level like 'debug' , 'info' , 'warn' , or 'error' The framework will handle updating LogViewer UI module every time the log is added to.

    • 'ss_userAction.Log' is a periscope framework logger that is defined automatically under server.R and should not be altered
    • Log level can be changed based on admin preference. Only update 'log_level' parameter in 'set_app_parameters' method in 'program/global.R' file with the required log level 'DEBUG' , 'INFO' , 'WARN' or 'ERROR'
    • To display application logs like below portlet add the following logViewer table to any of 'ui_body.R' boxes 

      U: logViewerOutput('logViewerId')

    Example

    Click different button in the example application and compare console with below output



    Files Organization

    File Downloader

    Features
    • File downloader module provides the user with the ability to download any server generated data
    • Data can be downloaded in any format available for both 'Table Downloader' and 'Plot Downloader' modules
    • Data can be downloaded in single format or in multiple formats, based on module configurations
    Setup
    • Module should be configured in both UI and Server code 

      U: downloadFileButton('uiID', list(extensions))
      S: downloadFile('uiID', logger, 'filenameroot', list(datafxns)

    • Review ?downloadFileButton and ?downloadFile for more information
    • Review below file downloaders for detailed example code
    Example
    Single Download: Multiple-choice Download:

    Reset Application

    Features
    • appReset module provides the ability to:
      • Resets a user's session
      • Rolls over their log.
    • It creates a toggle button to reset application session
    • Upon pressing on the button, its state is flipped to 'cancel application reload' with application and console warning messages indicating that the application will be reloaded
    • User can either resume reloading application session or cancel reloading process, which will also generate application and console messages to indicate reloading status and result.
    • Waiting time before actual session reset is configurable in milliseconds
    • Generated module alerts location can be customized to be displayed in any place, default is application body
    Setup
    • Functionality can be added with the following code: 

      U: appResetButton('appResetId')
      S: appReset(id = 'appResetId', reset_wait = 5000, logger = logger)

    • Run '?periscope2::appResetButton' and '?periscope2::appReset' for more info
    • Review example below for detailed code
    Example

    Table Downloader

    Features
    • Table downloader module display tabular data in rich formatted tables using `DT` package
    • Selected rows in the table are returned as a reactive variable that can be used in application different areas
    • Table data can be downloaded in different formats such as: 'csv' , 'tsv' , 'txt' and/or 'xlsx'
    • User can customize downloadableTable modules using DT options such as:
      • labels:   i.e. 'colnames', 'caption', ...
      • layout and columns styles:   i.e. 'container', 'formatStyle', ...
      • other addons:   i.e. 'filter', 'callback', ...
    • For more information about table options please visit the DT documentation site
    Setup
  • Module should be configured in both UI and Server code
  • In your 'body_ui.R', place module UI part as follow:
    downloadableTableUI('exampleDT1', list('csv', 'tsv'), 'Download table data'))
  • In your 'server_local.R', place module server part, with the same id used with UI part , as follow:
    downloadableTable('exampleDT1', ss_userAction.Log, 'exampletable', list(csv = load_data3, tsv = load_data3))
  • Review ?downloadableTableUI and ?downloadableTable for more information
  • Review below table for detailed example code

    • Plot Downloader - ggplot2 & lattice

    Features
    • This module creates a custom plot output that provide download capability to plot tools that have no internal download ability like ggplot2 & lattice.
    • Plot can be downloaded in different formats such as: 'png' , 'jpeg' , 'tiff' and/or 'bmp'
    • Plot data itself can be downloaded in different formats such as: 'csv' , 'tsv' , 'txt' and/or 'xlsx'
    • To enrich user experience, plot downloader module also can take advanced shiny parameters as 'clickOpts', 'hoverOpts' or 'brushOpts'
    • Plot dimensions can be easily adapted
    • plot download button location can be easily controlled
    Setup
    • Module should be configured in both the UI and Server code
    • In your 'body_ui.R', place module UI part as follow:
      downloadablePlotUI('myplotID', c('png', 'csv'), 'Download Plot or Data', '300px'))
    • In your 'server_local.R', place module server part, with the same id used with UI part , as follow:
      downloadablePlot('myplotID', ss_userAction.Log, filenameroot = 'mydownload1', downloadfxns = list(png = myplotfxn, tsv = mydatafxn))
    • Run '?periscope2::downloadablePlot' for more info
    • Review below table for detailed example code

    Example


    Busy Indicators

    Periscope2 has two application busy indicators

    Application Loading
  • Any 'waiter' package loading screen indicator that displayed upon application start up or reload.
  • Loading screen can be changed by updating 'loading_indicator' parameter in 'set_app_parameters' method in 'program/global.R' 'waiter' package loading screen
  • For more information about loadnig screens options please visit the waiter documentation site
  • Check example below:


    • Busy Session
  • An automatic wait indicator in the navbar when the shiny server session is busy.

    • Alerts

    Alerts can be added with the following code in the server:

    S:periscope2::createPSAlert(id = 'alert place',
                         options  = list(title    = 'alert title',
                         status   = 'alert status'',
                         closable = TRUE,
                         content  = alert contents))
    Examples

    LOCATION can be: 'sidebarRightAlert', 'sidebarBasicAlert', 'bodyAlert', 'footerAlert' and 'headerAlert'

    Tooltips

    Tooltips can be added with the following code in the UI:

    U: ui_tooltip('tooltipID', 'label text (optional)', 'text content', 'placement' (optional))
    Examples
    Top Tooltips Left Tooltips Bottom Tooltips Right Tooltips

    Style Guide

    periscope2 App Theme and CSS
  • periscope2 depends on fresh package for styling application theme
  • There are many theme variables are available for customization. Review this article for more info
  • Fortunately, periscope2 provides a user-friendly method to update fresh theme variables via configurations, rather than by updating them programatically.
    • The theme can be updated by editing 'www/periscope_style.yaml' and relaunching the app
  • 'periscope_style.yaml' contains the most important variables with documentation explaining what each variable affects and possible values for it
  • Another method to update application themes or any controls in CSS is by updating 'www/css/custom.css' file
  • The below widget explains some of the variables and how they affect the application


    • ** Note: Updating app theme might take a few seconds

    Status Colors
  • Sets the status (used by bootstrap 4) colors that affects the color of the header, valueBox, infoBox and box
  • Valid values are names of the color or hex-decimal value of the color (i.e,: 'blue', '#086A87')
  • Blank, empty or invalid values will use the default values

    • Sidebars Width
  • Width or padding is to be specified as a numeric value in pixels. Must be greater than 0 and include numbers only
  • Valid possible value are 200, 350, 425, ...
  • Blank, empty or invalid values will use the default values

    • Layout Parts Colors
  • Sets application different layout parts (sidebars, background, ...) colors
  • Valid values are names of the color or hex-decimal value of the color (i.e,: 'blue', '#086A87')
  • Blank, empty or invalid values will the use the default values