From 4f4142211b620a4185b5eca0a2383c72c26ac350 Mon Sep 17 00:00:00 2001 From: pvictor Date: Mon, 29 Nov 2021 18:58:47 +0100 Subject: [PATCH] updated docs --- R/apex.R | 29 ++++++++--------- R/apexcharter.R | 69 ++++++++++++++++++++++------------------ man/apex.Rd | 4 +-- man/apexchart.Rd | 15 +++++---- man/apexcharter-shiny.Rd | 16 ++++++---- 5 files changed, 71 insertions(+), 62 deletions(-) diff --git a/R/apex.R b/R/apex.R index b9ae6e1..7eb3391 100644 --- a/R/apex.R +++ b/R/apex.R @@ -5,28 +5,23 @@ #' data, mapping and type of chart. #' #' @param data Default dataset to use for chart. If not already -#' a \code{data.frame}, it will be coerced to with \code{as.data.frame}. +#' a `data.frame`, it will be coerced to with `as.data.frame`. #' @param mapping Default list of aesthetic mappings to use for chart #' @param type Specify the chart type. Available options: -#' \code{"column"}, \code{"bar"}, -#' \code{"line"}, \code{"step"}, \code{"spline"}, -#' \code{"area"}, \code{"area-step"}, \code{"area-spline"}, -#' \code{"pie"}, \code{"donut"}, -#' \code{"radialBar"}, \code{"radar"}, \code{"scatter"}, -#' \code{"heatmap"}, \code{"treemap"}, -#' \code{"timeline"}. +#' `"column"`, `"bar"`, +#' `"line"`, `"step"`, `"spline"`, +#' `"area"`, `"area-step"`, `"area-spline"`, +#' `"pie"`, `"donut"`, +#' `"radialBar"`, `"radar"`, `"scatter"`, +#' `"heatmap"`, `"treemap"`, +#' `"timeline"`. #' @param ... Other arguments passed on to methods. Not currently used. -#' @param auto_update In Shiny application, update existing chart -#' rather than generating new one. Can be \code{TRUE}/\code{FALSE} or -#' use \code{\link{config_update}} for more control. #' @param synchronize Give a common id to charts to synchronize them (tooltip and zoom). #' @param serie_name Name for the serie displayed in tooltip, #' only used for single serie. -#' @param width A numeric input in pixels. -#' @param height A numeric input in pixels. -#' @param elementId Use an explicit element ID for the widget. +#' @inheritParams apexchart #' -#' @return A \code{apexcharts} \code{htmlwidget} object. +#' @return An [apexchart()] `htmlwidget` object. #' #' @export #' @@ -35,7 +30,9 @@ #' @importFrom stats complete.cases #' #' @example examples/apex.R -apex <- function(data, mapping, type = "column", ..., +apex <- function(data, mapping, + type = "column", + ..., auto_update = TRUE, synchronize = NULL, serie_name = NULL, diff --git a/R/apexcharter.R b/R/apexcharter.R index f905c35..c661dc7 100644 --- a/R/apexcharter.R +++ b/R/apexcharter.R @@ -1,22 +1,26 @@ -#' Create an apexcharts.js widget +#' Create an ApexCharts widget #' -#' @param ax_opts A \code{list} in JSON format with chart parameters. +#' @param ax_opts A `list` in JSON format with chart parameters. #' @param auto_update In Shiny application, update existing chart -#' rather than generating new one. Can be \code{TRUE}/\code{FALSE} or -#' use \code{\link{config_update}} for more control. -#' @param width A numeric input in pixels. -#' @param height A numeric input in pixels. +#' rather than generating new one. Can be `TRUE`/`FALSE` or +#' use [config_update()] for more control. +#' @param width,height A numeric input in pixels. #' @param elementId Use an explicit element ID for the widget. #' -#' @return A \code{apexcharts} \code{htmlwidget} object. +#' @return An [apexchart()] `htmlwidget` object. +#' @seealso For quickly create a chart, see [apex()]. #' @export #' #' @importFrom htmlwidgets createWidget sizingPolicy #' #' @example examples/apexchart.R -apexchart <- function(ax_opts = list(), auto_update = TRUE, width = NULL, height = NULL, elementId = NULL) { - +apexchart <- function(ax_opts = list(), + auto_update = TRUE, + width = NULL, + height = NULL, + elementId = NULL) { + if (isTRUE(auto_update)) { auto_update <- config_update() } @@ -63,9 +67,9 @@ add_locale_apex <- function(widget) { defaultLocale <- widget$x$ax_opts$chart$defaultLocale defaultLocale <- match.arg( arg = defaultLocale, - choices = c("ca", "cs", "de", "el", "en", "es", "fi", "fr", "he", "hi", - "hr", "hu", "hy", "id", "it", "ja", "ka", "ko", "lt", "nb", "nl", - "pl", "pt-br", "pt", "rs", "ru", "se", "sk", "sl", "sq", "th", + choices = c("ca", "cs", "de", "el", "en", "es", "fi", "fr", "he", "hi", + "hr", "hu", "hy", "id", "it", "ja", "ka", "ko", "lt", "nb", "nl", + "pl", "pt-br", "pt", "rs", "ru", "se", "sk", "sl", "sq", "th", "tr", "ua", "zh-cn") ) if (!is.null(widget$x$ax_opts$chart$locales)) { @@ -93,22 +97,22 @@ add_locale_apex <- function(widget) { #' @param update_options Update or not global options for chart. #' @param options_animate Should the chart animate on re-rendering. #' @param options_redrawPaths When the chart is re-rendered, -#' should it draw from the existing paths or completely redraw -#' the chart paths from the beginning. By default, the chart +#' should it draw from the existing paths or completely redraw +#' the chart paths from the beginning. By default, the chart #' is re-rendered from the existing paths. #' @param update_synced_charts All the charts in a group should #' also update when one chart in a group is updated. -#' +#' #' @export -config_update <- function(series_animate = TRUE, - update_options = FALSE, - options_animate = TRUE, +config_update <- function(series_animate = TRUE, + update_options = FALSE, + options_animate = TRUE, options_redrawPaths = TRUE, update_synced_charts = FALSE) { list( - series_animate = series_animate, - update_options = update_options, - options_animate = options_animate, + series_animate = series_animate, + update_options = update_options, + options_animate = options_animate, options_redrawPaths = options_redrawPaths, update_synced_charts = update_synced_charts ) @@ -120,23 +124,26 @@ config_update <- function(series_animate = TRUE, #' @description Output and render functions for using apexcharter within Shiny #' applications and interactive Rmd documents. #' -#' @param outputId output variable to read from -#' @param width,height Must be a valid CSS unit (like \code{'100\%'}, -#' \code{'400px'}, \code{'auto'}) or a number, which will be coerced to a -#' string and have \code{'px'} appended. -#' @param expr An expression that generates a apexcharter -#' @param env The environment in which to evaluate \code{expr}. -#' @param quoted Is \code{expr} a quoted expression (with \code{quote()})? This +#' @param outputId Output variable to read from. +#' @param width,height Must be a valid CSS unit (like `100%`, +#' `400px`, `auto`) or a number, which will be coerced to a +#' string and have `px` appended. +#' @param expr An expression that generates a calendar +#' @param env The environment in which to evaluate `expr`. +#' @param quoted Is `expr` a quoted expression (with `quote()`)? This #' is useful if you want to save an expression in a variable. -#' -#' @return An Apexcharts output that can be included in the application UI. +#' +#' @return Output element that can be included in UI. Render function to create output in server. +#' +#' @note To render a chart with facets (using [ax_facet_wrap()] or [ax_facet_grid()]) in Shiny, +#' see [apexfacetOutput()] (in UI) and [renderApexfacet()] (in Server). #' #' @name apexcharter-shiny #' #' @export #' #' @importFrom htmlwidgets shinyWidgetOutput shinyRenderWidget -#' +#' #' @example examples/apexcharter-shiny.R apexchartOutput <- function(outputId, width = "100%", height = "400px") { # nocov start htmlwidgets::shinyWidgetOutput(outputId, "apexcharter", width, height, package = "apexcharter") diff --git a/man/apex.Rd b/man/apex.Rd index 0f9ad13..d25f204 100644 --- a/man/apex.Rd +++ b/man/apex.Rd @@ -36,7 +36,7 @@ a \code{data.frame}, it will be coerced to with \code{as.data.frame}.} \item{auto_update}{In Shiny application, update existing chart rather than generating new one. Can be \code{TRUE}/\code{FALSE} or -use \code{\link{config_update}} for more control.} +use \code{\link[=config_update]{config_update()}} for more control.} \item{synchronize}{Give a common id to charts to synchronize them (tooltip and zoom).} @@ -50,7 +50,7 @@ only used for single serie.} \item{elementId}{Use an explicit element ID for the widget.} } \value{ -A \code{apexcharts} \code{htmlwidget} object. +An \code{\link[=apexchart]{apexchart()}} \code{htmlwidget} object. } \description{ Initialize a chart with three main parameters : diff --git a/man/apexchart.Rd b/man/apexchart.Rd index c4bed03..a0319c4 100644 --- a/man/apexchart.Rd +++ b/man/apexchart.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/apexcharter.R \name{apexchart} \alias{apexchart} -\title{Create an apexcharts.js widget} +\title{Create an ApexCharts widget} \usage{ apexchart( ax_opts = list(), @@ -17,19 +17,17 @@ apexchart( \item{auto_update}{In Shiny application, update existing chart rather than generating new one. Can be \code{TRUE}/\code{FALSE} or -use \code{\link{config_update}} for more control.} +use \code{\link[=config_update]{config_update()}} for more control.} -\item{width}{A numeric input in pixels.} - -\item{height}{A numeric input in pixels.} +\item{width, height}{A numeric input in pixels.} \item{elementId}{Use an explicit element ID for the widget.} } \value{ -A \code{apexcharts} \code{htmlwidget} object. +An \code{\link[=apexchart]{apexchart()}} \code{htmlwidget} object. } \description{ -Create an apexcharts.js widget +Create an ApexCharts widget } \examples{ library(apexcharter) @@ -66,3 +64,6 @@ apexchart() \%>\% categories = LETTERS[1:5] ) } +\seealso{ +For quickly create a chart, see \code{\link[=apex]{apex()}}. +} diff --git a/man/apexcharter-shiny.Rd b/man/apexcharter-shiny.Rd index aca652d..22e5fdc 100644 --- a/man/apexcharter-shiny.Rd +++ b/man/apexcharter-shiny.Rd @@ -17,13 +17,13 @@ sparkBoxOutput(outputId, width = "100\%", height = "160px") renderSparkBox(expr, env = parent.frame(), quoted = FALSE) } \arguments{ -\item{outputId}{output variable to read from} +\item{outputId}{Output variable to read from.} -\item{width, height}{Must be a valid CSS unit (like \code{'100\%'}, -\code{'400px'}, \code{'auto'}) or a number, which will be coerced to a -string and have \code{'px'} appended.} +\item{width, height}{Must be a valid CSS unit (like \verb{100\%}, +\verb{400px}, \code{auto}) or a number, which will be coerced to a +string and have \code{px} appended.} -\item{expr}{An expression that generates a apexcharter} +\item{expr}{An expression that generates a calendar} \item{env}{The environment in which to evaluate \code{expr}.} @@ -31,12 +31,16 @@ string and have \code{'px'} appended.} is useful if you want to save an expression in a variable.} } \value{ -An Apexcharts output that can be included in the application UI. +Output element that can be included in UI. Render function to create output in server. } \description{ Output and render functions for using apexcharter within Shiny applications and interactive Rmd documents. } +\note{ +To render a chart with facets (using \code{\link[=ax_facet_wrap]{ax_facet_wrap()}} or \code{\link[=ax_facet_grid]{ax_facet_grid()}}) in Shiny, +see \code{\link[=apexfacetOutput]{apexfacetOutput()}} (in UI) and \code{\link[=renderApexfacet]{renderApexfacet()}} (in Server). +} \examples{ if (interactive()) { library(shiny)