R/Documentation_templates.R

In mjhelf/Metaboseek: Metaboseek platform

#' @title values
#' 
#' @description \code{values} is a reactivevalues object with a defined structure
#' 
#' @section Object structure:
#' The \code{values} object is a \code{\link[shiny]{reactiveValues}} object,
#' containing three other \code{reactiveValues} objects, each 
#' \subsection{values$featureTables}{
#' contains objects related to feature tables
#' }
#' \subsection{values$MSData}{
#' contains object related to MS data
#'\describe{
#'  \item{values$MSData$MS2.selectTable}{data.frame listing metadata for all 
#'  MS2 spectra matching criteria}
#'  \item{values$MSData$MS2.selected}{list with three items:
#'  \itemize{
#'  \item{spectra:} list of selected MS2 spectra as matrices
#'  \item{mergedSpectrum:} result of merging all selected spectra as a matrix
#'  \item{specInfo:} data.frame listing metadata for all selected MS2 spectra
#' }}
#' }
#' 
#' }
#' \subsection{values$GlobalOpts}{
#' GlobalOpts loads the current MseekOptions into the current session as
#' \code{reactiveValues}, and is also used by many modules to make values
#'  accessible app-wide.
#' }
#' @name values
#' @importFrom grDevices as.raster colorRampPalette dev.off pdf recordPlot replayPlot topo.colors
#' @importFrom graphics abline axis layout lcm legend lines mtext par plot points polygon rasterImage segments strheight strwidth text title
#' @importFrom stats df median na.omit sd
#' @importFrom utils installed.packages packageVersion read.csv read.delim relist type.convert unzip write.csv zip
#' 
NULL


#' @title MseekWidgets
#'
#' @description \code{MseekWidgets} should work in a "vanilla" shiny 
#' environment, i.e. any shiny app, making it easy to use them in other 
#' shiny projects without significant overhead. The only expected argument 
#'  they need is a list supplied as reactives, and potentially additional 
#'  arguments for which default values exist. Widgets are typically wrappers
#'   for plotting functions with some additional functionality. 
#'   
#' @param input,output,session arguments necessary for use with 
#' \code{\link[shiny]{callModule}()}
#' @param reactives a list, wrapped in a \code{\link[shiny]{reactive}()} 
#' expression with settings for this module. See \code{details}.
#' @param static a list of arguments that are not in a reactive context 
#' and hence do not change while the app is running.
#' @param keys \code{reactive({})} that reports the current key press. 
#' @param id id to be used to define a namespace via  \code{\link[shiny]{NS}()}
#'  (must match \code{id} in \code{\link[shiny]{callModule}} 
#'  for the server Module)
#' @param ... additional arguments, as defined for the individual module. 
#' For example: constant layout options depending on the context that this
#'  module is used in
#' 
#' @describeIn MseekWidgets generic server logic example for MseekWidgets
MseekWidgets <- function(input,output, session, reactives, static, keys, ...){
    
    #creating the namespacing function to be used for UI elements that are prepared inside the server logic
    ns <- NS(session$ns(NULL))
    
    #optional: a local reactiveValues() object to be used to exchange information within this module
    internalValues <- reactiveValues()
    
    #optional: expose the internalValues to the outside. Makes it possible to change them from outside the module!
    return(internalValues)
    
}

#' @describeIn MseekWidgets generic UI example for MseekWidgets
MseekWidgetsUI <- function(id){
    
    #basic wrapper for UI elements that will embed the contained UI elements directly into the surrounding UI without placing them inside another div.
    shiny::tagList(
        #place UI elements here
        )
    #Other options include shiny::fluidPage(), shiny::div() or shiny::box()

}

#' @title MseekModules
#'
#' @description Regular modules in Metaboseek take a 
#' \code{shiny::reactiveValues} object called \code{values} as their 
#' first argument.
#'  \code{values} is the primary interface allowing communication between 
#'  modules and is generated by \code{\link{MseekMinimalServer}()}.
#'   Modules expect this input to work properly, and will only work in shiny 
#'   apps that provide the proper environment set up by 
#'   \code{\link{MseekMinimalServer}()}.
#'   
#' @return If the server module for this Module returns something,
#'  it is described in \code{Details}.
#'   
#' @param input,output,session arguments necessary for use with 
#' \code{\link[shiny]{callModule}()}
#' @param values a \code{\link[shiny]{reactiveValues}} object that in effect 
#' gives read and write access to external objects
#' @param reactives a list, wrapped in a \code{\link[shiny]{reactive}()} 
#' expression with settings for this module. See \code{details}.
#' @param id id to be used to define a namespace via  \code{\link[shiny]{NS}()} 
#' (must match \code{id} in \code{\link[shiny]{callModule}} 
#' for the server Module)
#' @param keys \code{reactive({})} that reports the current key press. 
#' This argument is deprecated and will be removed from all modules.
#' @param static a list of arguments that are not in a reactive context 
#' and hence do not change while the app is running.
#' @param ... additional arguments, as defined for the individual module. 
#' For example: constant layout options depending on the context that this 
#' module is used in
#' 
#' @seealso 
#' \code{\link{values}} for a description of the \code{values} object
#' 
#' @describeIn MseekModules generic server logic example for MseekModules
MseekModules <- function(input,output, session, values, reactives,
                         static, keys, ...){
    
    #creating the namespacing function to be used for UI elements that are prepared inside the server logic
    ns <- NS(session$ns(NULL))
    
    #optional: a local reactiveValues() object to be used to exchange information within this module
    internalValues <- reactiveValues()
    
    #optional: expose the internalValues to the outside. Makes it possible to change them from outside the module!
    return(internalValues)

}

#' @describeIn MseekModules generic UI example for MseekModules
MseekModulesUI <- function(id){
    
    #basic wrapper for UI elements that will embed the contained UI elements directly into the surrounding UI without placing them inside another div.
    shiny::tagList(
        #place UI elements here
    )
    #Other options include shiny::fluidPage(), shiny::div() or shiny::box()
    
}

#' @title MseekContainers
#'
#' @description This is the MseekContainer template
#'    
#' @section MseekContainers:
#' Containers are used to keep the code organised and can be characterized
#'  as Modules which contain other Modules, but do not contain add any functionality themselves.
#'   They should not contain any observers and are only here to pass \code{values} into modules,
#'    or provide ways for individual Modules to interact with each other.
#'    
#' @return The server module for this container returns nothing
#' 
#' @examples
#' \dontrun{
#' ui <- function(request){
#' MseekContainerUI("Mseek")
#' }
#' server <- function(input, output, session) {
#'    callModule(MseekContainer, "Mseek")
#' }
#' Create Shiny app ----
#' shinyApp(ui, server)
#' }
#' 
#' @seealso 
#' \code{\link{values}} for a description of the \code{values} object
#' \itemize{
#' \item{General Information:} \code{\link{MseekContainers}}
#' \item{Specific containers:} \code{\link{MseekContainer}}, \code{\link{MainPageContainer}} 
#' \item{More on Shiny modules:} \url{http://shiny.rstudio.com/articles/modules.html}
#' }
#' 
#' @param input,output,session arguments necessary for use with \code{\link[shiny]{callModule}()}
#' @param values a \code{\link[shiny]{reactiveValues}} object that in effect gives read and write access to external objects
#' @param id id to be used to define a namespace via  \code{\link[shiny]{NS}()} (must match \code{id} in \code{\link[shiny]{callModule}()} for the server Module)
#' 
#' @describeIn MseekContainers generic server logic example for MseekContainers
MseekContainers <- function(input,output, session, values){
    
    #creating the namespacing function to be used for UI elements that are prepared inside the server logic
    ns <- NS(session$ns(NULL))
    
    #optional: a local reactiveValues() object to be used to exchange information within this module
    internalValues <- reactiveValues()
    
    #optional: expose the internalValues to the outside. Makes it possible to change them from outside the module!
    return(internalValues)
    
}

#' @describeIn MseekContainers generic UI example for MseekContainers
MseekContainersUI <- function(id){
    
    #basic wrapper for UI elements that will embed the contained UI elements directly into the surrounding UI without placing them inside another div.
    shiny::tagList(
        #place UI elements here
    )
    #Other options include shiny::fluidPage(), shiny::div() or shiny::box()
    
}