diff --git a/.Rbuildignore b/.Rbuildignore index a32bacb46f8972e28df68f94556fe9596be2f74f..3a7293427c24865953a69e693106df3f5554cdde 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,4 +1,7 @@ ^.*\.Rproj$ ^\.Rproj\.user$ +^\.ci$ +^\.gitlab-ci.yml +^README\.md ^doc$ ^Meta$ diff --git a/.ci/requirements.txt b/.ci/requirements.txt index 135ff738686a33bac60a251915976e8a838ecd3e..9c717358d40e1bfa65a49b66e4f4b8e23c435b50 100644 --- a/.ci/requirements.txt +++ b/.ci/requirements.txt @@ -1,10 +1,15 @@ r-assertive.sets +r-assertive.types r-base bioconductor-biocstyle r-htmltools r-flexdashboard +r-glue r-knitr r-magrittr +r-stringi +r-stringr r-yaml r-ymlthis +qpdf zip \ No newline at end of file diff --git a/DESCRIPTION b/DESCRIPTION index 8955d02f2e261fc6e2780d68abe4893ae82fc475..1a2ecd231cbc33ff95f4b7ddf5d9182f6c699b72 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -21,29 +21,24 @@ Imports: assertive.types, rmarkdown, stringr, + stringi, glue, - ymlthis + ymlthis, + methods, + stats, + utils Suggests: switchr, - highcharter, plotly, - crosstalk, - gt, - ggplot2, - DT, - leaflet, - dygraphs, - rbokeh, - visNetwork, - d3heatmap, - metricsgraphics, - BiocStyle + BiocStyle, + xfun, + htmltools Collate: 'i2dashboard.R' 'AllGenerics.R' 'assemble.R' - 'colormap.R' 'components.R' + 'colormap.R' 'get_set.R' 'pages.R' 'reexports.R' diff --git a/NAMESPACE b/NAMESPACE index dd06e168c73b8b625542b808d340c65d29ed9848..fde6235f7da46d3bede4baf5a234bddd217b1054 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -26,11 +26,4 @@ export(source) export(theme) export(title) exportClasses(i2dashboard) -exportMethods(add_colormap) -exportMethods(add_component) -exportMethods(add_link) -exportMethods(add_page) -exportMethods(add_to_sidebar) -exportMethods(assemble) -exportMethods(remove_page) importFrom(magrittr,"%>%") diff --git a/R/AllGenerics.R b/R/AllGenerics.R index 853951fc273f6e38fd0890fa6797c5b5613dad47..cd62efc8766ca6014c61b91ca15de1cb77a2b310 100644 --- a/R/AllGenerics.R +++ b/R/AllGenerics.R @@ -1,66 +1,88 @@ #' @include i2dashboard.R #' @export +#' @rdname assemble setGeneric("assemble", function(dashboard, ...) standardGeneric("assemble")) #' @export +#' @rdname i2dashboard-pages setGeneric("add_page", function(dashboard, ...) standardGeneric("add_page")) #' @export -setGeneric("remove_page", function(dashboard, ...) standardGeneric("remove_page")) +#' @rdname i2dashboard-pages +setGeneric("remove_page", function(dashboard, page) standardGeneric("remove_page")) #' @export +#' @rdname i2dashboard-content setGeneric("add_component", function(dashboard, component, ...) standardGeneric("add_component")) #' @export +#' @rdname i2dashboard-content setGeneric("add_to_sidebar", function(dashboard, component, ...) standardGeneric("add_to_sidebar")) #' @export +#' @rdname i2dashboard-content setGeneric("add_colormap", function(dashboard, ...) standardGeneric("add_colormap")) #' @export +#' @rdname i2dashboard-methods setGeneric("interactivity", function(dashboard) standardGeneric("interactivity")) #' @export +#' @rdname i2dashboard-methods setGeneric("interactivity<-", function(dashboard, value) standardGeneric("interactivity<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("title", function(dashboard) standardGeneric("title")) #' @export +#' @rdname i2dashboard-methods setGeneric("title<-", function(dashboard, value) standardGeneric("title<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("author", function(dashboard) standardGeneric("author")) #' @export +#' @rdname i2dashboard-methods setGeneric("author<-", function(dashboard, value) standardGeneric("author<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("theme", function(dashboard) standardGeneric("theme")) #' @export +#' @rdname i2dashboard-methods setGeneric("theme<-", function(dashboard, value) standardGeneric("theme<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("datadir", function(dashboard) standardGeneric("datadir")) #' @export +#' @rdname i2dashboard-methods setGeneric("datadir<-", function(dashboard, value) standardGeneric("datadir<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("social_links", function(dashboard) standardGeneric("social_links")) #' @export +#' @rdname i2dashboard-methods setGeneric("social_links<-", function(dashboard, value) standardGeneric("social_links<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("embed_source<-", function(dashboard, value) standardGeneric("embed_source<-")) #' @export +#' @rdname i2dashboard-methods setGeneric("source", function(dashboard) standardGeneric("source")) #' @export +#' @rdname i2dashboard-methods setGeneric("source<-", function(dashboard, value) standardGeneric("source<-")) #' @export +#' @rdname i2dashboard-content setGeneric("add_link", function(dashboard, ...) standardGeneric("add_link")) \ No newline at end of file diff --git a/R/assemble.R b/R/assemble.R index dff109599126e813c7f1683d16b73960c96edf80..9320b3ebc1cb4e456dfce6da54f875e3756ea632 100644 --- a/R/assemble.R +++ b/R/assemble.R @@ -1,15 +1,17 @@ -#' Method to assemble a dashboard to a Rmd file. +#' Generate an RMarkdown file from an i2dashboard object. #' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param pages A string or vector with the names of pages, which should be assembled to a dashboard. -#' @param file The output filename (recommend that the suffix should be '.Rmd'). This file will be saved in the working directory. +#' @param dashboard A \linkS4class{i2dashboard}. +#' @param pages A string or vector with the names of pages, which should be assembled into the resulting Rmd file. +#' @param file The filename of the resulting Rmd file (recommend that the suffix should be '.Rmd'). #' @param exclude A string or vector with the names of pages, which should be excluded from dashboard assembly. #' @param render A logical indicating whether the assembled dashboard should immediately be rendered with \code{rmarkdown::render} or run with \code{rmarkdown::run}. #' @param ... Additional arguments passed on to \code{rmarkdown::render}. #' -#' @rdname i2dashboard-methods -#' @export +#' @return Invisibly returns the dashboard. +#' +#' @rdname assemble setMethod("assemble", "i2dashboard", function(dashboard, pages = names(dashboard@pages), file = dashboard@file, exclude = NULL, render = FALSE, ...) { + . = NULL # workaround for R CMD check note: no visible binding for global variable '.' tmp_document <- tempfile() # Handle colormap @@ -49,7 +51,7 @@ setMethod("assemble", "i2dashboard", function(dashboard, pages = names(dashboard # Handle exclusion of pages if(!is.null(exclude)) { - pages <- pages[-na.omit(match(exclude, pages))] + pages <- pages[-stats::na.omit(match(exclude, pages))] } # Handle global sidebar if it has content diff --git a/R/colormap.R b/R/colormap.R index 64ad2d0cae481c0dd044cb76643f20b066d57f6e..32f582eb91ef40a85b3447b963196181c18a6799 100644 --- a/R/colormap.R +++ b/R/colormap.R @@ -1,11 +1,11 @@ -#' Add a color mapping to the dashboards colormaps. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. +#' @include components.R +NULL + +#' @param dashboard A \linkS4class{i2dashboard}. #' @param map A character vector containing colors and possible the levels they map to (as names). #' @param name A name for the color mapping. #' -#' @rdname i2dashboard-methods -#' @export +#' @rdname i2dashboard-content setMethod("add_colormap", "i2dashboard", function(dashboard, map, name) { dashboard@colormaps[[make.names(name)]] <- map return(dashboard) diff --git a/R/components.R b/R/components.R index dc726f3e737a2717348f9b4ca370399e9546a5cb..32967821a8effc5cb1123d9aefc8f89a324e5395 100644 --- a/R/components.R +++ b/R/components.R @@ -1,30 +1,36 @@ -#' Method to add a component to a page of an i2dashboard. +#' Add content to an i2dashboard object. #' -#' Components can be created by evaluating a function, or by including an object, a text or image file. +#' Content can be added to the dashboards pages, the sidebar or the navigation bar. #' -#' @section Adding content by evaluating a function: -#' If the argument \code{component} is a function, the function will be called and its return value is used as content. +#' The options to add content in detail: +#' \itemize{ +#' \item \strong{\code{add_component}} adds content to a page of the dashboard by evaluating a function, or by including an object, a text or image file. +#' \item \strong{\code{add_to_sidebar}} adds content to the dashboards global sidebar or to a pages local sidebar. +#' \item \strong{\code{add_link}} adds a link to the navigation bar. +#' \item \strong{\code{add_colormap}} adds a global color mapping to the dashboards colormaps. +#' } #' -#' @section Adding plain text as content: -#' If the argument \code{component} is a character and ends with \code{.md} or \code{.txt}, the function will try to open a file and use its content. +#' The mechanism to add different types of content to a dashboards page or sidebar depends on the class of the object passed to the function \code{add_component} or \code{add_to_sidebar}: #' -#' @section Adding images as content: -#' If the argument \code{component} is a character and its end matches \code{\\.[png|jpg|jpeg|gif]}, the function will try to include an image as the content. +#' \itemize{ +#' \item A function will be evaluated and its return value is used as content. +#' \item A string that ends with \code{.md} or \code{.txt} will be used to open a file and use its content. +#' \item A string that ends with \code{\\.[png|jpg|jpeg|gif]} will be used to include an image as content. +#' \item An R object (e.g. a htmlwidget) will be included if a suitable signature method is implemented. +#' } #' -#' @section Adding a R object as content: -#' If the argument \code{component} is a supported R object (e.g. a htmlwidget), the function will include its representation as content. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param page The name of the page to add the component to. -#' @param component A R object, function, or character. +#' @param dashboard A \linkS4class{i2dashboard}. +#' @param page The name of the page to add the component or sidebar to. +#' @param component An R object, function, or string. #' @param copy Whether or not to copy images to \code{dashboard@datadir}. #' @param ... Additional parameters passed to the components render function. #' -#' @rdname add-component -#' @export +#' @return The (modified) \linkS4class{i2dashboard} object. +#' +#' @rdname i2dashboard-content setMethod("add_component", signature = signature(dashboard = "i2dashboard", component = "character"), - function(dashboard, component, page = "default", copy = FALSE, ...) { + function(dashboard, page = "default", component, copy = FALSE, ...) { # Logic to guess intended usage mode <- NULL if(stringr::str_detect(tolower(component), "\\.[md|txt]+$")) { @@ -58,8 +64,9 @@ setMethod("add_component", return(.add_component(dashboard, name, component)) }) +#' @rdname i2dashboard-content setMethod("add_component", signature(dashboard = "i2dashboard", component = "function"), - function(dashboard, component, page = "default", ...) { + function(dashboard, page = "default", component, ...) { # validate "page" input name <- .create_page_name(page) if (!(name %in% names(dashboard@pages))) { @@ -76,6 +83,81 @@ setMethod("add_component", signature(dashboard = "i2dashboard", component = "fun return(.add_component(dashboard, name, content)) }) +#' @rdname i2dashboard-content +setMethod("add_component", + signature = signature(dashboard = "i2dashboard", component = "gg"), + definition = function(dashboard, component, page = "default", ...) { + add_vis_object(dashboard, component, "ggplot2", page, ...) }) + +#' @rdname i2dashboard-content +setMethod("add_component", + signature = signature(dashboard = "i2dashboard", component = "gt_tbl"), + definition = function(dashboard, component, page = "default", ...) { + add_vis_object(dashboard, component,"gt", page, ...) }) + +#' @rdname i2dashboard-content +setMethod("add_component", + signature = signature(dashboard = "i2dashboard", component = "knitr_kable"), + definition = function(dashboard, component, page = "default", ...) { + add_vis_object(dashboard, component, "kableExtra", page, ...) }) + +#' @rdname i2dashboard-content +setMethod("add_component", + signature = signature(dashboard = "i2dashboard", component = "Heatmap"), + definition = function(dashboard, component, page = "default", ...) { + add_vis_object(dashboard, component, "ComplexHeatmap", page, ...) }) + +#' @rdname i2dashboard-content +setMethod("add_component", + signature = signature(dashboard = "i2dashboard", component = "ANY"), + definition = function(dashboard, component, page = "default", ...) { + + # HTMLWIDGETS + if(inherits(component, "htmlwidget")) { + package <- methods::packageSlot(component) + + if(is.null(package)) { + warning("No component added, since the package name of the HTML widget could not be determined.") + return(dashboard) + } + + return(add_vis_object(dashboard, component, package, page, ...)) + } + + # OTHER + warning("The component did not inherit from any of the currently supported classes ('htmlwidget').") + return(dashboard) + }) + +#' @param href The target of the link. +#' @param title The link title. +#' @param icon An optional link icon (see https://rmarkdown.rstudio.com/flexdashboard/using.html#icon-sets) +#' @param align Optional argument that can be “left†or “right†(defaults = “rightâ€) defining the alignment of the links in the navigation bar +#' @param target An optional target (e.g. "_blank") +#' +#' @rdname i2dashboard-content +setMethod("add_link", "i2dashboard", function(dashboard, href, title = NULL, icon = NULL, align = c("right","left"), target = NULL) { + align <- match.arg(align) + if(is.null(title) & is.null(icon)) { + warning("Both, title and icon, cannot be NULL when adding a link.") + return(dashboard) + } + + # Workaround for NULL values + if(is.null(icon)) { + icon <- "" + } + if(is.null(title)) { + title = "" + } + if(is.null(target)) { + target = "" + } + + dashboard@navbar <- append(dashboard@navbar, list(list("href" = href, "title" = title, "icon" = icon, "align" = align, "target" = target))) + dashboard +}) + #' Method to download embed files into an Rmd-file #' #' @param x Data, which will be written to the embedded file. @@ -84,7 +166,7 @@ setMethod("add_component", signature(dashboard = "i2dashboard", component = "fun #' @export embed_var <- function(x, ...) { f = tempfile(fileext = '.csv') - write.csv(x, f) + utils::write.csv(x, f) xfun::embed_file(f, text = 'Download data', ...) } @@ -129,7 +211,7 @@ render_image <- function(image, image_alt_text = NULL, title = NULL, raw = FALSE #' Helper function to add components to the dashboard #' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. +#' @param dashboard A \linkS4class{i2dashboard}. #' @param page The name of the page to add the component to. #' @param component A string or list. #' diff --git a/R/get_set.R b/R/get_set.R index 70aeea16b878839907f8b3a261820202fd3dc40e..685f655185bcba960347cf7c44b2958a5cc5b6ce 100644 --- a/R/get_set.R +++ b/R/get_set.R @@ -1,94 +1,59 @@ -#' Get/set the interactivity of the i2dashboard. +#' Accessor methods for slots of an \linkS4class{i2dashboard} object. #' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. +#' Getter and Setter methods can be used to directly manipulate properties (slots) of an \linkS4class{i2dashboard} object. See \linkS4class{i2dashboard} for details. #' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @param dashboard A \linkS4class{i2dashboard}. +#' @param value The value of the desired property. See \linkS4class{i2dashboard} for details. +#' +#' @rdname i2dashboard-methods setMethod("interactivity", "i2dashboard", function(dashboard) dashboard@interactive) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("interactivity<-", "i2dashboard", function(dashboard, value) { dashboard@interactive <- value dashboard }) -#' Get/set the title of the i2dashboard. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("title", "i2dashboard", function(dashboard) dashboard@title) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("title<-", "i2dashboard", function(dashboard, value) { dashboard@title <- value dashboard }) -#' Get/set the author of the i2dashboard. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("author", "i2dashboard", function(dashboard) dashboard@author) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("author<-", "i2dashboard", function(dashboard, value) { dashboard@author <- value dashboard }) -#' Get/set the theme of the i2dashboard. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("theme", "i2dashboard", function(dashboard) dashboard@theme) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("theme<-", "i2dashboard", function(dashboard, value) { dashboard@theme <- value dashboard }) -#' Get/set the datadir of the i2dashboard. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("datadir", "i2dashboard", function(dashboard) dashboard@datadir) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("datadir<-", "i2dashboard", function(dashboard, value) { dashboard@datadir <- value dashboard }) -#' Get/set the links to be shown for sharing on social media. Any of the following services are allowed: “facebookâ€, “twitterâ€, “google-plusâ€, “linkedinâ€, and “pinterestâ€. You can also specify “menu†to provide a generic sharing drop-down menu that includes all of the services. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("social_links", "i2dashboard", function(dashboard) dashboard@social_links) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("social_links<-", "i2dashboard", function(dashboard, value) { i <- intersect(tolower(value), c("facebook", "twitter", "google-plus", "linkedin", "pinterest", "menu")) if (length(i) > 0) { @@ -97,24 +62,16 @@ setMethod("social_links<-", "i2dashboard", function(dashboard, value) { dashboard }) -#' Get/set the embedding of the source code of the i2dashboard. Can either be a URL pointing to where the source code can be found online or whether or not to embed the source code into the document. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param value The value of the desired property. A URL pointing to where the source code can be found online. -#' -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("source", "i2dashboard", function(dashboard) dashboard@source) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("source<-", "i2dashboard", function(dashboard, value) { dashboard@source <- tolower(as.character(value)) dashboard }) -#' @name i2dashboard-class -#' @rdname i2dashboard-class +#' @rdname i2dashboard-methods setMethod("embed_source<-", "i2dashboard", function(dashboard, value) { if(value) { dashboard@source <- "embed" @@ -124,36 +81,3 @@ setMethod("embed_source<-", "i2dashboard", function(dashboard, value) { dashboard }) -#' Add a link to the navigation bar. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param href The target of the link. -#' @param title The link title. -#' @param icon An optional link icon (see https://rmarkdown.rstudio.com/flexdashboard/using.html#icon-sets) -#' @param align Optional argument that can be “left†or “right†(defaults = “rightâ€) defining the alignment of the links in the navigation bar -#' @param target An optional target (e.g. "_blank") -#' -#' @rdname i2dashboard-methods -#' @export -setMethod("add_link", "i2dashboard", function(dashboard, href, title = NULL, icon = NULL, align = c("right","left"), target = NULL) { - align <- match.arg(align) - if(is.null(title) & is.null(icon)) { - warning("Both, title and icon, cannot be NULL when adding a link.") - return(dashboard) - } - - # Workaround for NULL values - if(is.null(icon)) { - icon <- "" - } - if(is.null(title)) { - title = "" - } - if(is.null(target)) { - target = "" - } - - dashboard@navbar <- append(dashboard@navbar, list(list("href" = href, "title" = title, "icon" = icon, "align" = align, "target" = target))) - dashboard -}) - diff --git a/R/i2dashboard.R b/R/i2dashboard.R index 8af9444465c2ddd3aac4b15acdf6181f5f827e70..1c8734fb10c02a5e6e97bdcaa8cc810f6d87682e 100644 --- a/R/i2dashboard.R +++ b/R/i2dashboard.R @@ -1,9 +1,27 @@ -#' The idashboard S4 class. +#' i2dash: A package for programmatic creation of interactive, web-based dashboards +#' +#' i2dash relies on the widely used R packages flexdashboard, knitr and rmarkdown. i2dash introduces a new class from R's S4 object system named \linkS4class{i2dashboard}, which by design provides the main functionality of the package. Besides global properties such as the dashboard title, author and theme, an instance of the \linkS4class{i2dashboard} class also stores individual dashboard pages and the navigation menu, as well as all components that make up the content of individual pages. +#' +#' @section Citation: +#' +#' When using the package in your work, please cite: tba. +#' +#' @docType package +#' @name i2dash +NULL + +#' The \linkS4class{i2dashboard} S4 class. +#' +#' The \linkS4class{i2dashboard} S4 class provides main functionality of the package. Besides global properties such as the dashboard title, author and theme, an instance of the i2dashboard class also stores individual dashboard pages and the navigation menu, as well as all components that make up the content of individual pages. A new instance can be created using the \code{i2dashboard} function. +#' +#' @param object An object of class \linkS4class{i2dashboard}. +#' @param .Object An object of class \linkS4class{i2dashboard}. +#' @param ... Named slots of the \linkS4class{i2dashboard} object. #' #' @slot title The dashboards title #' @slot author The author of the dashboard #' @slot interactive If a shiny-based report should be created -#' @slot theme The theme of the dashboard +#' @slot theme The theme of the dashboard (see the \href{https://rmarkdown.rstudio.com/flexdashboard/using.html#appearance}{documentation of flexdashboard} for available themes) #' @slot datadir Path to the directory, where report data is stored. #' @slot file The output filename (recommend that the suffix should be '.Rmd'). #' @slot pages A list of dashboard pages @@ -11,12 +29,11 @@ #' @slot colormaps A named list with color mappings. #' @slot source Either a logical value describing whether the source code should be embeded through an item in the navigation bar or a link to a URL where the source code can be found online. #' @slot social A vector with any number of the following services: “facebookâ€, “twitterâ€, “google-plusâ€, “linkedinâ€, and “pinterestâ€. You can also specify “menu†to provide a generic sharing drop-down menu that includes all of the services. -#' @slot navbar A list of links in the navigation bar (see https://rmarkdown.rstudio.com/flexdashboard/using.html#navigation_bar). +#' @slot navbar A list of links in the navigation bar (see the \href{https://rmarkdown.rstudio.com/flexdashboard/using.html#navigation_bar}{documentation of flexdashboard}). #' -#' @return An i2dashboard object. +#' @return An \linkS4class{i2dashboard} object. #' -#' @name idashboard-class -#' @rdname idashboard-class +#' @rdname i2dashboard-class #' @exportClass i2dashboard setClass("i2dashboard", slots = c( @@ -44,13 +61,11 @@ setClass("i2dashboard", ) ) -#' Constructor method of the i2dashboard class. #' -#' @name idashboard-class -#' @rdname idashboard-class +#' @rdname i2dashboard-class setMethod("initialize", "i2dashboard", function(.Object, ...) { # Do prototyping - .Object <- callNextMethod() + .Object <- methods::callNextMethod() # Create nice filename from title if(length(.Object@file) == 0 & length(.Object@title) > 0) { @@ -64,46 +79,23 @@ setMethod("initialize", "i2dashboard", function(.Object, ...) { return(.Object) }) -#' Show method of the i2dashboard class. +#' Show method of the \linkS4class{i2dashboard} class. +#' +#' @param object An \linkS4class{i2dashboard} class object. #' -#' @name idashboard-class -#' @rdname idashboard-class -setMethod("show", "i2dashboard", function(.Object) { - cat("A flexdashboard with the title: ", .Object@title, "\n", sep = "") - if(length(.Object@pages) > 0) { - cat("... containing ", length(.Object@pages), "pages:\n") - for (pagename in names(.Object@pages)){ - cat(sprintf(" ... the page '%s' with the title '%s' contains %i components.\n", pagename, .Object@pages[[pagename]]$title, length(.Object@pages[[pagename]]$components))) +#' @rdname i2dashboard-class +setMethod("show", "i2dashboard", function(object) { + cat("A flexdashboard with the title: ", object@title, "\n", sep = "") + if(length(object@pages) > 0) { + cat("... containing ", length(object@pages), "pages:\n") + for (pagename in names(object@pages)){ + cat(sprintf(" ... the page '%s' with the title '%s' contains %i components.\n", pagename, object@pages[[pagename]]$title, length(object@pages[[pagename]]$components))) } } else { cat("... containing 0 pages.") } }) -#' Create a new i2dashboard object. -#' -#' @name idashboard-class -#' @rdname idashboard-class +#' @rdname i2dashboard-class #' @export -i2dashboard <- function(...) new("i2dashboard", ...) - - -### - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -### Validity. -### - -# .valid.RmdReport <- function(object){ -# msg <- NULL -# # Checking header -# if (!is.character(object@header)){ -# msg <- c(msg, "'header' must be a character-like object") -# } -# # Checking pages -# if (!is.list(object@pages)){ -# msg <- c(msg, "'pages' must be a list-like object") -# } -# if (length(msg)) { return(msg) } -# return(TRUE) -# } -# -# setValidity("RmdReport", .valid.RmdReport) +i2dashboard <- function(...) methods::new("i2dashboard", ...) diff --git a/R/pages.R b/R/pages.R index d88c0999a4f8331695ba55f0e6cd993546a02472..5e8e5c82ef9e7030d21a16037fbef3da88225a5d 100644 --- a/R/pages.R +++ b/R/pages.R @@ -1,24 +1,19 @@ -#' Sanitize component names -#' -#' This function takes a character string, replaces spaces by underscores and runs make.names. +#' Methods to add and remove pages of an i2dashboard. #' -#' @param x A character string. +#' \code{add_page} creates a page and adds it to the \linkS4class{i2dashboard} object. +#' \code{remove_page} removes a page from the \linkS4class{i2dashboard} object. #' -#' @return A sanitized string. -.create_page_name <- function(x) { - x %>% tolower %>% gsub(x = ., pattern = " ", replacement = "_") %>% make.names %>% return -} - -#' Method to add a page to an i2dashboard -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param page The name of the page to be added. +#' @param dashboard A \linkS4class{i2dashboard}. +#' @param page The name of the page to be added or removed. #' @param title The title of the page to be added. #' @param layout The page layout (see below). #' @param menu The name of the menu, under which the page should appear. +#' @param sidebar A Markdown string. Preferably, use the function add_to_sidebar. +#' @param ... Additional arguments. #' -#' @rdname i2dashboard-methods -#' @export +#' @return The \linkS4class{i2dashboard} object. +#' +#' @rdname i2dashboard-pages setMethod("add_page", "i2dashboard", function(dashboard, page, title, layout = "default", menu = NULL, sidebar = NULL, ...) { name <- .create_page_name(page) @@ -44,15 +39,21 @@ setMethod("add_page", "i2dashboard", function(dashboard, page, title, layout = " return(dashboard) }) -#' Method to remove a page to an i2dashboard -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param page The name of the page to be removed. -#' -#' @rdname i2dashboard-methods -#' @export +#' @rdname i2dashboard-pages setMethod("remove_page", "i2dashboard", function(dashboard, page) { name <- .create_page_name(page) dashboard@pages[[name]] <- NULL return(dashboard) }) + +#' Sanitize component names +#' +#' This function takes a character string, replaces spaces by underscores and runs make.names. +#' +#' @param x A character string. +#' +#' @return A sanitized string. +.create_page_name <- function(x) { + . = NULL # workaround for R CMD check note: no visible binding for global variable '.' + x %>% tolower %>% gsub(x = ., pattern = " ", replacement = "_") %>% make.names %>% return +} \ No newline at end of file diff --git a/R/sidebar.R b/R/sidebar.R index e6219f76967bfd68e605feeaaae43fb8c088fe84..a9a8933267400a974244f99fa440df23d50538f4 100644 --- a/R/sidebar.R +++ b/R/sidebar.R @@ -1,33 +1,24 @@ -#' Add content to a sidebar -#' -#' This method allows to add content either to the global sidebar, or to a sidebar of an existing page. -#' -#' @param dashboard A \linkS4class{i2dash::i2dashboard}. -#' @param content The name of a function of a path to a file. -#' @param page The name of the page to which add the sidebar. +#' @include components.R #' @param global Whether or not to add the content to the global sidebar. -#' @param copy Whether or not to copy images to \code{dashboard@datadir}. -#' @param ... Additional parameters passed to the components render function. #' -#' @rdname i2dashboard-methods -#' @export -setMethod("add_to_sidebar", "i2dashboard", function(dashboard, content, page = "default", global = FALSE, copy = FALSE, ...) { +#' @rdname i2dashboard-content +setMethod("add_to_sidebar", "i2dashboard", function(dashboard, component, page = "default", global = FALSE, copy = FALSE, ...) { # Logic to guess intended usage mode <- "function" - if(stringr::str_detect(tolower(content), "\\.[md|txt]+$")) { + if(stringr::str_detect(tolower(component), "\\.[md|txt]+$")) { mode <- "text" } - if(stringr::str_detect(tolower(content), "\\.[png|jpg|jpeg|gif]+$")) { + if(stringr::str_detect(tolower(component), "\\.[png|jpg|jpeg|gif]+$")) { if(copy) { - location <- file.path(dashboard@datadir, basename(content)) - file.copy(content, location) - content <- location + location <- file.path(dashboard@datadir, basename(component)) + file.copy(component, location) + component <- location } mode <- "image" } if(mode == "function") { - pn <- strsplit(content, "::")[[1]] + pn <- strsplit(component, "::")[[1]] eval_function <- if(length(pn) == 1) { get(pn[[1]], envir = asNamespace("i2dash"), mode = "function") } else { @@ -35,26 +26,26 @@ setMethod("add_to_sidebar", "i2dashboard", function(dashboard, content, page = " } } - content <- switch(mode, + component <- switch(mode, "function" = do.call(eval_function, args = list(dashboard, ...)), - "text" = do.call("render_text", args = list(content, raw = TRUE)), - "image" = do.call("render_image", args = list(content, raw = TRUE))) + "text" = do.call("render_text", args = list(component, raw = TRUE)), + "image" = do.call("render_image", args = list(component, raw = TRUE))) - if(is.list(content)) { + if(is.list(component)) { warning(sprintf("Component function returned unsupported content for sidebar.")) return(dashboard) } if(global) { - dashboard@sidebar <- paste0(dashboard@sidebar, content) + dashboard@sidebar <- paste0(dashboard@sidebar, component) } else { name <- .create_page_name(page) if (!(name %in% names(dashboard@pages))) { warning(sprintf("i2dashboard dashboard does not contain a page named '%s'", name)) return(dashboard) } - dashboard@pages[[name]]$sidebar <- paste0(dashboard@pages[[name]]$sidebar, content) + dashboard@pages[[name]]$sidebar <- paste0(dashboard@pages[[name]]$sidebar, component) } return(dashboard) }) diff --git a/R/vis_objects.R b/R/vis_objects.R index 3f2c2449f7c0ecf6c30ddf19a6e8522e8a71b2e1..d5de012dfde3f616e839156588b917773e74e6fd 100644 --- a/R/vis_objects.R +++ b/R/vis_objects.R @@ -1,12 +1,15 @@ +#' @include components.R +NULL + #' General method to add an object as component to a page of an i2dashboard. #' -#' @param dashboard The \linkS4class{i2dash::i2dashboard}. +#' @param dashboard The \linkS4class{i2dashboard}. #' @param object The R visualization object to be addedd. #' @param package The name of the R package that defines the class(object). #' @param page The name of the page to add the object to. #' @param title An optional component title. -add_vis_object <- function(dashboard, object, package, page = "default", title = NULL, ...){ - sanitised_page <- i2dash:::.create_page_name(page) +add_vis_object <- function(dashboard, object, package, page = "default", title = NULL){ + sanitised_page <- .create_page_name(page) if (!(sanitised_page %in% names(dashboard@pages))) { warning(sprintf("i2dashboard does not contain a page named '%s'", sanitised_page)) return(dashboard) @@ -29,7 +32,7 @@ add_vis_object <- function(dashboard, object, package, page = "default", title = delim = c("<%", "%>"), title = title, package = package, - class = is(object), + class = methods::is(object), component_id = component_id, timestamp = timestamp) @@ -38,46 +41,3 @@ add_vis_object <- function(dashboard, object, package, page = "default", title = return(dashboard) } -# -# Methods to add common visualization objects -# -setMethod("add_component", - signature = signature(dashboard = "i2dashboard", component = "gg"), - definition = function(dashboard, component, page = "default", title = NULL, ...) { - add_vis_object(dashboard, component, "ggplot2", page, title, ...) }) - -setMethod("add_component", - signature = signature(dashboard = "i2dashboard", component = "gt_tbl"), - definition = function(dashboard, component, page = "default", title = NULL, ...) { - add_vis_object(dashboard, component,"gt", page, title, ...) }) - -setMethod("add_component", - signature = signature(dashboard = "i2dashboard", component = "knitr_kable"), - definition = function(dashboard, component, page = "default", title = NULL, ...) { - add_vis_object(dashboard, component, "kableExtra", page, title, ...) }) - -setMethod("add_component", - signature = signature(dashboard = "i2dashboard", component = "Heatmap"), - definition = function(dashboard, component, page = "default", title = NULL, ...) { - add_vis_object(dashboard, component, "ComplexHeatmap", page, title, ...) }) - -setMethod("add_component", - signature = signature(dashboard = "i2dashboard", component = "ANY"), - definition = function(dashboard, component, page = "default", title = NULL, ...) { - - # HTMLWIDGETS - if(inherits(component, "htmlwidget")) { - package <- packageSlot(component) - - if(is.null(package)) { - warning("No component added, since the package name of the HTML widget could not be determined.") - return(dashboard) - } - - return(add_vis_object(dashboard, component, package, page, title, ...)) - } - - # OTHER - warning("The component did not inherit from any of the currently supported classes ('htmlwidget').") - return(dashboard) - }) diff --git a/man/add-component.Rd b/man/add-component.Rd deleted file mode 100644 index b102e6fa399f12f8616d24097783cb81da39b360..0000000000000000000000000000000000000000 --- a/man/add-component.Rd +++ /dev/null @@ -1,42 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/components.R -\name{add_component,i2dashboard,character-method} -\alias{add_component,i2dashboard,character-method} -\title{Method to add a component to a page of an i2dashboard.} -\usage{ -\S4method{add_component}{i2dashboard,character}(dashboard, component, page = "default", copy = FALSE, ...) -} -\arguments{ -\item{dashboard}{A \linkS4class{i2dash::i2dashboard}.} - -\item{component}{A R object, function, or character.} - -\item{page}{The name of the page to add the component to.} - -\item{copy}{Whether or not to copy images to \code{dashboard@datadir}.} - -\item{...}{Additional parameters passed to the components render function.} -} -\description{ -Components can be created by evaluating a function, or by including an object, a text or image file. -} -\section{Adding content by evaluating a function}{ - -If the argument \code{component} is a function, the function will be called and its return value is used as content. -} - -\section{Adding plain text as content}{ - -If the argument \code{component} is a character and ends with \code{.md} or \code{.txt}, the function will try to open a file and use its content. -} - -\section{Adding images as content}{ - -If the argument \code{component} is a character and its end matches \code{\\.[png|jpg|jpeg|gif]}, the function will try to include an image as the content. -} - -\section{Adding a R object as content}{ - -If the argument \code{component} is a supported R object (e.g. a htmlwidget), the function will include its representation as content. -} - diff --git a/man/add_vis_object.Rd b/man/add_vis_object.Rd index d14e05559056f6afa13ffe99921a666e7f397d21..8698680e29837e73eccd00318adb3580ec6b2be6 100644 --- a/man/add_vis_object.Rd +++ b/man/add_vis_object.Rd @@ -4,10 +4,10 @@ \alias{add_vis_object} \title{General method to add an object as component to a page of an i2dashboard.} \usage{ -add_vis_object(dashboard, object, package, page = "default", title = NULL, ...) +add_vis_object(dashboard, object, package, page = "default", title = NULL) } \arguments{ -\item{dashboard}{The \linkS4class{i2dash::i2dashboard}.} +\item{dashboard}{The \linkS4class{i2dashboard}.} \item{object}{The R visualization object to be addedd.} diff --git a/man/assemble.Rd b/man/assemble.Rd new file mode 100644 index 0000000000000000000000000000000000000000..7c05afcc04623d2745bb23701fa1b2746387ed58 --- /dev/null +++ b/man/assemble.Rd @@ -0,0 +1,37 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AllGenerics.R, R/assemble.R +\name{assemble} +\alias{assemble} +\alias{assemble,i2dashboard-method} +\title{Generate an RMarkdown file from an i2dashboard object.} +\usage{ +assemble(dashboard, ...) + +\S4method{assemble}{i2dashboard}( + dashboard, + pages = names(dashboard@pages), + file = dashboard@file, + exclude = NULL, + render = FALSE, + ... +) +} +\arguments{ +\item{dashboard}{A \linkS4class{i2dashboard}.} + +\item{...}{Additional arguments passed on to \code{rmarkdown::render}.} + +\item{pages}{A string or vector with the names of pages, which should be assembled into the resulting Rmd file.} + +\item{file}{The filename of the resulting Rmd file (recommend that the suffix should be '.Rmd').} + +\item{exclude}{A string or vector with the names of pages, which should be excluded from dashboard assembly.} + +\item{render}{A logical indicating whether the assembled dashboard should immediately be rendered with \code{rmarkdown::render} or run with \code{rmarkdown::run}.} +} +\value{ +Invisibly returns the dashboard. +} +\description{ +Generate an RMarkdown file from an i2dashboard object. +} diff --git a/man/dot-add_component.Rd b/man/dot-add_component.Rd index 7ece2fa6564d9cfd55d201bbc776b719a1205fca..aa78398b66572bca803742b2a779c569d82b9b7c 100644 --- a/man/dot-add_component.Rd +++ b/man/dot-add_component.Rd @@ -7,7 +7,7 @@ .add_component(dashboard, page, component) } \arguments{ -\item{dashboard}{A \linkS4class{i2dash::i2dashboard}.} +\item{dashboard}{A \linkS4class{i2dashboard}.} \item{page}{The name of the page to add the component to.} diff --git a/man/i2dash.Rd b/man/i2dash.Rd new file mode 100644 index 0000000000000000000000000000000000000000..48d52eb616c6970a2bfb957632021a2b1ae42e63 --- /dev/null +++ b/man/i2dash.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/i2dashboard.R +\docType{package} +\name{i2dash} +\alias{i2dash} +\title{i2dash: A package for programmatic creation of interactive, web-based dashboards} +\description{ +i2dash relies on the widely used R packages flexdashboard, knitr and rmarkdown. i2dash introduces a new class from R's S4 object system named \linkS4class{i2dashboard}, which by design provides the main functionality of the package. Besides global properties such as the dashboard title, author and theme, an instance of the \linkS4class{i2dashboard} class also stores individual dashboard pages and the navigation menu, as well as all components that make up the content of individual pages. +} +\section{Citation}{ + + +When using the package in your work, please cite: tba. +} + diff --git a/man/i2dashboard-class.Rd b/man/i2dashboard-class.Rd index 61b7ee558f8e9d39bd003e3583c17765671d3dd2..320c35ed9772c5535ee5e63094a685a8931b2789 100644 --- a/man/i2dashboard-class.Rd +++ b/man/i2dashboard-class.Rd @@ -1,56 +1,57 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/get_set.R +% Please edit documentation in R/i2dashboard.R +\docType{class} \name{i2dashboard-class} \alias{i2dashboard-class} -\title{Get/set the interactivity of the i2dashboard.} +\alias{initialize,i2dashboard-method} +\alias{show,i2dashboard-method} +\alias{i2dashboard} +\title{The \linkS4class{i2dashboard} S4 class.} \usage{ -\S4method{interactivity}{i2dashboard}(dashboard) +\S4method{initialize}{i2dashboard}(.Object, ...) -\S4method{interactivity}{i2dashboard}(dashboard) <- value +\S4method{show}{i2dashboard}(object) -\S4method{title}{i2dashboard}(dashboard) - -\S4method{title}{i2dashboard}(dashboard) <- value - -\S4method{author}{i2dashboard}(dashboard) - -\S4method{author}{i2dashboard}(dashboard) <- value - -\S4method{theme}{i2dashboard}(dashboard) +i2dashboard(...) +} +\arguments{ +\item{.Object}{An object of class \linkS4class{i2dashboard}.} -\S4method{theme}{i2dashboard}(dashboard) <- value +\item{...}{Named slots of the \linkS4class{i2dashboard} object.} -\S4method{datadir}{i2dashboard}(dashboard) +\item{object}{An \linkS4class{i2dashboard} class object.} +} +\value{ +An \linkS4class{i2dashboard} object. +} +\description{ +The \linkS4class{i2dashboard} S4 class provides main functionality of the package. Besides global properties such as the dashboard title, author and theme, an instance of the i2dashboard class also stores individual dashboard pages and the navigation menu, as well as all components that make up the content of individual pages. A new instance can be created using the \code{i2dashboard} function. +} +\section{Slots}{ -\S4method{datadir}{i2dashboard}(dashboard) <- value +\describe{ +\item{\code{title}}{The dashboards title} -\S4method{social_links}{i2dashboard}(dashboard) +\item{\code{author}}{The author of the dashboard} -\S4method{social_links}{i2dashboard}(dashboard) <- value +\item{\code{interactive}}{If a shiny-based report should be created} -\S4method{source}{i2dashboard}(dashboard) +\item{\code{theme}}{The theme of the dashboard (see the \href{https://rmarkdown.rstudio.com/flexdashboard/using.html#appearance}{documentation of flexdashboard} for available themes)} -\S4method{source}{i2dashboard}(dashboard) <- value +\item{\code{datadir}}{Path to the directory, where report data is stored.} -\S4method{embed_source}{i2dashboard}(dashboard) <- value -} -\arguments{ -\item{dashboard}{A \linkS4class{i2dash::i2dashboard}.} +\item{\code{file}}{The output filename (recommend that the suffix should be '.Rmd').} -\item{value}{The value of the desired property. A URL pointing to where the source code can be found online.} -} -\description{ -Get/set the interactivity of the i2dashboard. +\item{\code{pages}}{A list of dashboard pages} -Get/set the title of the i2dashboard. +\item{\code{sidebar}}{Content of the global sidebar} -Get/set the author of the i2dashboard. +\item{\code{colormaps}}{A named list with color mappings.} -Get/set the theme of the i2dashboard. +\item{\code{source}}{Either a logical value describing whether the source code should be embeded through an item in the navigation bar or a link to a URL where the source code can be found online.} -Get/set the datadir of the i2dashboard. +\item{\code{social}}{A vector with any number of the following services: “facebookâ€, “twitterâ€, “google-plusâ€, “linkedinâ€, and “pinterestâ€. You can also specify “menu†to provide a generic sharing drop-down menu that includes all of the services.} -Get/set the links to be shown for sharing on social media. Any of the following services are allowed: “facebookâ€, “twitterâ€, “google-plusâ€, “linkedinâ€, and “pinterestâ€. You can also specify “menu†to provide a generic sharing drop-down menu that includes all of the services. +\item{\code{navbar}}{A list of links in the navigation bar (see the \href{https://rmarkdown.rstudio.com/flexdashboard/using.html#navigation_bar}{documentation of flexdashboard}).} +}} -Get/set the embedding of the source code of the i2dashboard. Can either be a URL pointing to where the source code can be found online or whether or not to embed the source code into the document. -} diff --git a/man/i2dashboard-content.Rd b/man/i2dashboard-content.Rd new file mode 100644 index 0000000000000000000000000000000000000000..02543abefdb48e9f0507fa216402dbb90ecae000 --- /dev/null +++ b/man/i2dashboard-content.Rd @@ -0,0 +1,113 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AllGenerics.R, R/components.R, R/colormap.R, +% R/sidebar.R +\name{add_component} +\alias{add_component} +\alias{add_to_sidebar} +\alias{add_colormap} +\alias{add_link} +\alias{add_component,i2dashboard,character-method} +\alias{add_component,i2dashboard,function-method} +\alias{add_component,i2dashboard,gg-method} +\alias{add_component,i2dashboard,gt_tbl-method} +\alias{add_component,i2dashboard,knitr_kable-method} +\alias{add_component,i2dashboard,Heatmap-method} +\alias{add_component,i2dashboard,ANY-method} +\alias{add_link,i2dashboard-method} +\alias{add_colormap,i2dashboard-method} +\alias{add_to_sidebar,i2dashboard-method} +\title{Add content to an i2dashboard object.} +\usage{ +add_component(dashboard, component, ...) + +add_to_sidebar(dashboard, component, ...) + +add_colormap(dashboard, ...) + +add_link(dashboard, ...) + +\S4method{add_component}{i2dashboard,character}(dashboard, page = "default", component, copy = FALSE, ...) + +\S4method{add_component}{i2dashboard,`function`}(dashboard, page = "default", component, ...) + +\S4method{add_component}{i2dashboard,gg}(dashboard, component, page = "default", ...) + +\S4method{add_component}{i2dashboard,gt_tbl}(dashboard, component, page = "default", ...) + +\S4method{add_component}{i2dashboard,knitr_kable}(dashboard, component, page = "default", ...) + +\S4method{add_component}{i2dashboard,Heatmap}(dashboard, component, page = "default", ...) + +\S4method{add_component}{i2dashboard,ANY}(dashboard, component, page = "default", ...) + +\S4method{add_link}{i2dashboard}( + dashboard, + href, + title = NULL, + icon = NULL, + align = c("right", "left"), + target = NULL +) + +\S4method{add_colormap}{i2dashboard}(dashboard, map, name) + +\S4method{add_to_sidebar}{i2dashboard}( + dashboard, + component, + page = "default", + global = FALSE, + copy = FALSE, + ... +) +} +\arguments{ +\item{dashboard}{A \linkS4class{i2dashboard}.} + +\item{component}{An R object, function, or string.} + +\item{...}{Additional parameters passed to the components render function.} + +\item{page}{The name of the page to add the component or sidebar to.} + +\item{copy}{Whether or not to copy images to \code{dashboard@datadir}.} + +\item{href}{The target of the link.} + +\item{title}{The link title.} + +\item{icon}{An optional link icon (see https://rmarkdown.rstudio.com/flexdashboard/using.html#icon-sets)} + +\item{align}{Optional argument that can be “left†or “right†(defaults = “rightâ€) defining the alignment of the links in the navigation bar} + +\item{target}{An optional target (e.g. "_blank")} + +\item{map}{A character vector containing colors and possible the levels they map to (as names).} + +\item{name}{A name for the color mapping.} + +\item{global}{Whether or not to add the content to the global sidebar.} +} +\value{ +The (modified) \linkS4class{i2dashboard} object. +} +\description{ +Content can be added to the dashboards pages, the sidebar or the navigation bar. +} +\details{ +The options to add content in detail: +\itemize{ + \item \strong{\code{add_component}} adds content to a page of the dashboard by evaluating a function, or by including an object, a text or image file. + \item \strong{\code{add_to_sidebar}} adds content to the dashboards global sidebar or to a pages local sidebar. + \item \strong{\code{add_link}} adds a link to the navigation bar. + \item \strong{\code{add_colormap}} adds a global color mapping to the dashboards colormaps. +} + +The mechanism to add different types of content to a dashboards page or sidebar depends on the class of the object passed to the function \code{add_component} or \code{add_to_sidebar}: + +\itemize{ + \item A function will be evaluated and its return value is used as content. + \item A string that ends with \code{.md} or \code{.txt} will be used to open a file and use its content. + \item A string that ends with \code{\\.[png|jpg|jpeg|gif]} will be used to include an image as content. + \item An R object (e.g. a htmlwidget) will be included if a suitable signature method is implemented. +} +} diff --git a/man/i2dashboard-methods.Rd b/man/i2dashboard-methods.Rd index 7abd8b385a90db6fa67094359fbbb4ea596d7ed9..5867ac466122185c269f035703f49e8ce375206c 100644 --- a/man/i2dashboard-methods.Rd +++ b/man/i2dashboard-methods.Rd @@ -1,95 +1,103 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/assemble.R, R/colormap.R, R/get_set.R, -% R/pages.R, R/sidebar.R -\name{assemble,i2dashboard-method} -\alias{assemble,i2dashboard-method} -\alias{add_colormap,i2dashboard-method} -\alias{add_link,i2dashboard-method} -\alias{add_page,i2dashboard-method} -\alias{remove_page,i2dashboard-method} -\alias{add_to_sidebar,i2dashboard-method} -\title{Method to assemble a dashboard to a Rmd file.} +% Please edit documentation in R/AllGenerics.R, R/get_set.R +\name{interactivity} +\alias{interactivity} +\alias{interactivity<-} +\alias{title} +\alias{title<-} +\alias{author} +\alias{author<-} +\alias{theme} +\alias{theme<-} +\alias{datadir} +\alias{datadir<-} +\alias{social_links} +\alias{social_links<-} +\alias{embed_source<-} +\alias{source} +\alias{source<-} +\alias{interactivity,i2dashboard-method} +\alias{interactivity<-,i2dashboard-method} +\alias{title,i2dashboard-method} +\alias{title<-,i2dashboard-method} +\alias{author,i2dashboard-method} +\alias{author<-,i2dashboard-method} +\alias{theme,i2dashboard-method} +\alias{theme<-,i2dashboard-method} +\alias{datadir,i2dashboard-method} +\alias{datadir<-,i2dashboard-method} +\alias{social_links,i2dashboard-method} +\alias{social_links<-,i2dashboard-method} +\alias{source,i2dashboard-method} +\alias{source<-,i2dashboard-method} +\alias{embed_source<-,i2dashboard-method} +\title{Accessor methods for slots of an \linkS4class{i2dashboard} object.} \usage{ -\S4method{assemble}{i2dashboard}( - dashboard, - pages = names(dashboard@pages), - file = dashboard@file, - exclude = NULL, - render = FALSE, - ... -) - -\S4method{add_colormap}{i2dashboard}(dashboard, map, name) - -\S4method{add_link}{i2dashboard}( - dashboard, - href, - title = NULL, - icon = NULL, - align = c("right", "left"), - target = NULL -) - -\S4method{add_page}{i2dashboard}( - dashboard, - page, - title, - layout = "default", - menu = NULL, - sidebar = NULL, - ... -) - -\S4method{remove_page}{i2dashboard}(dashboard, page) - -\S4method{add_to_sidebar}{i2dashboard}( - dashboard, - content, - page = "default", - global = FALSE, - copy = FALSE, - ... -) -} -\arguments{ -\item{dashboard}{A \linkS4class{i2dash::i2dashboard}.} +interactivity(dashboard) + +interactivity(dashboard) <- value + +title(dashboard) + +title(dashboard) <- value + +author(dashboard) + +author(dashboard) <- value + +theme(dashboard) -\item{pages}{A string or vector with the names of pages, which should be assembled to a dashboard.} +theme(dashboard) <- value -\item{file}{The output filename (recommend that the suffix should be '.Rmd'). This file will be saved in the working directory.} +datadir(dashboard) -\item{exclude}{A string or vector with the names of pages, which should be excluded from dashboard assembly.} +datadir(dashboard) <- value -\item{render}{A logical indicating whether the assembled dashboard should immediately be rendered with \code{rmarkdown::render} or run with \code{rmarkdown::run}.} +social_links(dashboard) -\item{...}{Additional parameters passed to the components render function.} +social_links(dashboard) <- value -\item{map}{A character vector containing colors and possible the levels they map to (as names).} +embed_source(dashboard) <- value -\item{name}{A name for the color mapping.} +source(dashboard) -\item{href}{The target of the link.} +source(dashboard) <- value -\item{title}{The title of the page to be added.} +\S4method{interactivity}{i2dashboard}(dashboard) -\item{icon}{An optional link icon (see https://rmarkdown.rstudio.com/flexdashboard/using.html#icon-sets)} +\S4method{interactivity}{i2dashboard}(dashboard) <- value -\item{align}{Optional argument that can be “left†or “right†(defaults = “rightâ€) defining the alignment of the links in the navigation bar} +\S4method{title}{i2dashboard}(dashboard) -\item{target}{An optional target (e.g. "_blank")} +\S4method{title}{i2dashboard}(dashboard) <- value -\item{page}{The name of the page to which add the sidebar.} +\S4method{author}{i2dashboard}(dashboard) -\item{layout}{The page layout (see below).} +\S4method{author}{i2dashboard}(dashboard) <- value -\item{menu}{The name of the menu, under which the page should appear.} +\S4method{theme}{i2dashboard}(dashboard) -\item{content}{The name of a function of a path to a file.} +\S4method{theme}{i2dashboard}(dashboard) <- value -\item{global}{Whether or not to add the content to the global sidebar.} +\S4method{datadir}{i2dashboard}(dashboard) + +\S4method{datadir}{i2dashboard}(dashboard) <- value + +\S4method{social_links}{i2dashboard}(dashboard) + +\S4method{social_links}{i2dashboard}(dashboard) <- value + +\S4method{source}{i2dashboard}(dashboard) + +\S4method{source}{i2dashboard}(dashboard) <- value + +\S4method{embed_source}{i2dashboard}(dashboard) <- value +} +\arguments{ +\item{dashboard}{A \linkS4class{i2dashboard}.} -\item{copy}{Whether or not to copy images to \code{dashboard@datadir}.} +\item{value}{The value of the desired property. See \linkS4class{i2dashboard} for details.} } \description{ -This method allows to add content either to the global sidebar, or to a sidebar of an existing page. +Getter and Setter methods can be used to directly manipulate properties (slots) of an \linkS4class{i2dashboard} object. See \linkS4class{i2dashboard} for details. } diff --git a/man/i2dashboard-pages.Rd b/man/i2dashboard-pages.Rd new file mode 100644 index 0000000000000000000000000000000000000000..35819a5da69076033666c8141a224d3dcf36d2d6 --- /dev/null +++ b/man/i2dashboard-pages.Rd @@ -0,0 +1,47 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/AllGenerics.R, R/pages.R +\name{add_page} +\alias{add_page} +\alias{remove_page} +\alias{add_page,i2dashboard-method} +\alias{remove_page,i2dashboard-method} +\title{Methods to add and remove pages of an i2dashboard.} +\usage{ +add_page(dashboard, ...) + +remove_page(dashboard, page) + +\S4method{add_page}{i2dashboard}( + dashboard, + page, + title, + layout = "default", + menu = NULL, + sidebar = NULL, + ... +) + +\S4method{remove_page}{i2dashboard}(dashboard, page) +} +\arguments{ +\item{dashboard}{A \linkS4class{i2dashboard}.} + +\item{...}{Additional arguments.} + +\item{page}{The name of the page to be added or removed.} + +\item{title}{The title of the page to be added.} + +\item{layout}{The page layout (see below).} + +\item{menu}{The name of the menu, under which the page should appear.} + +\item{sidebar}{A Markdown string. Preferably, use the function add_to_sidebar.} +} +\value{ +The \linkS4class{i2dashboard} object. +} +\description{ +\code{add_page} creates a page and adds it to the \linkS4class{i2dashboard} object. +\code{remove_page} removes a page from the \linkS4class{i2dashboard} object. +} diff --git a/man/idashboard-class.Rd b/man/idashboard-class.Rd deleted file mode 100644 index 05f1f66ce1ea1c49c984eaef36f870cd14415976..0000000000000000000000000000000000000000 --- a/man/idashboard-class.Rd +++ /dev/null @@ -1,54 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/i2dashboard.R -\docType{class} -\name{idashboard-class} -\alias{idashboard-class} -\alias{i2dashboard} -\title{The idashboard S4 class.} -\usage{ -\S4method{initialize}{i2dashboard}(.Object, ...) - -\S4method{show}{i2dashboard}(object) - -i2dashboard(...) -} -\value{ -An i2dashboard object. -} -\description{ -The idashboard S4 class. - -Constructor method of the i2dashboard class. - -Show method of the i2dashboard class. - -Create a new i2dashboard object. -} -\section{Slots}{ - -\describe{ -\item{\code{title}}{The dashboards title} - -\item{\code{author}}{The author of the dashboard} - -\item{\code{interactive}}{If a shiny-based report should be created} - -\item{\code{theme}}{The theme of the dashboard} - -\item{\code{datadir}}{Path to the directory, where report data is stored.} - -\item{\code{file}}{The output filename (recommend that the suffix should be '.Rmd').} - -\item{\code{pages}}{A list of dashboard pages} - -\item{\code{sidebar}}{Content of the global sidebar} - -\item{\code{colormaps}}{A named list with color mappings.} - -\item{\code{source}}{Either a logical value describing whether the source code should be embeded through an item in the navigation bar or a link to a URL where the source code can be found online.} - -\item{\code{social}}{A vector with any number of the following services: “facebookâ€, “twitterâ€, “google-plusâ€, “linkedinâ€, and “pinterestâ€. You can also specify “menu†to provide a generic sharing drop-down menu that includes all of the services.} - -\item{\code{navbar}}{A list of links in the navigation bar (see https://rmarkdown.rstudio.com/flexdashboard/using.html#navigation_bar).} -}} - diff --git a/vignettes/i2dash-intro.Rmd b/vignettes/i2dash-intro.Rmd index 66febadd3bc7450b633796a5525118569513662a..e0a6754301fee975ee0d51a04a7f1705ecccf817 100644 --- a/vignettes/i2dash-intro.Rmd +++ b/vignettes/i2dash-intro.Rmd @@ -222,7 +222,6 @@ The function `text_generator` from above can generate `n` paragraphs of Lorem Ip dashboard %<>% add_component(text_generator, page = "page4", - title = NULL, n = 4) ``` diff --git a/vignettes/images/example_page1.png b/vignettes/images/example_page1.png index 5192ca363542bcf28a8a170f770ae95c2ca8b189..94ffff95730dcf7003cfa8c8e2ec580d02edde13 100644 Binary files a/vignettes/images/example_page1.png and b/vignettes/images/example_page1.png differ diff --git a/vignettes/images/example_page3.png b/vignettes/images/example_page3.png index 8c4cce722e80ba9489f915949e7a46cc3045dae9..43a0c7a1204d23d26bb151f17bbaf800db66d856 100644 Binary files a/vignettes/images/example_page3.png and b/vignettes/images/example_page3.png differ diff --git a/vignettes/images/example_page4.png b/vignettes/images/example_page4.png index c3ac0403237cce6f6b2a6ebff33ae4abeafdfcc1..4748da8443e44c01efdfb3b4aa5d149691d4290b 100644 Binary files a/vignettes/images/example_page4.png and b/vignettes/images/example_page4.png differ diff --git a/vignettes/images/i2dash_logo.png b/vignettes/images/i2dash_logo.png index 1b491fd7f913da2f9b7a7453ca00475c9acaecd4..2bd805dcee9e71197eda888eb8a2e117f249808f 100644 Binary files a/vignettes/images/i2dash_logo.png and b/vignettes/images/i2dash_logo.png differ diff --git a/vignettes/images/lemur.jpg b/vignettes/images/lemur.jpg index 195f82cbe825c2f4ef977b152f5dcccb280cb515..f5f1055f0e24bfbabb7582ee947777cecd015a5f 100644 Binary files a/vignettes/images/lemur.jpg and b/vignettes/images/lemur.jpg differ diff --git a/vignettes/images/navigation.png b/vignettes/images/navigation.png index 3ca83a17e706845f917874cdfda055e08333bf26..1aae49f838efd041308cf8b42db43c3b96aaa49d 100644 Binary files a/vignettes/images/navigation.png and b/vignettes/images/navigation.png differ