add $addPlots() method to PlotGridConfiguration (#269)

* add `$addPlots()` method to `PlotGridConfiguration`

Closes #268

* add example

* also anticipate single plot entered in a list

* comment

* more docs

R/plot-grid.R

@@ -140,7 +140,7 @@ plotGrid <- function(plotGridConfiguration) {
 PlotGridConfiguration <- R6::R6Class(
   "PlotGridConfiguration",
   public = list(
-    plotList = NULL,
+    plotList = list(),
     title = NULL,
     subtitle = NULL,
     caption = NULL,
@@ -164,6 +164,52 @@ PlotGridConfiguration <- R6::R6Class(
     #' @return A `PlotGridConfiguration` object.
     initialize = function(plotList = NULL) {
       self$plotList <- plotList
+    },
+
+    #' @description Add a plot object.
+    #'
+    #' @param plots A single or a list containing `ggplot` object(s).
+    #'
+    #' @examples
+    #'
+    #' library(ggplot2)
+    #'
+    #' myPlotGrid <- PlotGridConfiguration$new()
+    #'
+    #' # You can add a single ggplot object
+    #' p <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
+    #' myPlotGrid$addPlots(p)
+    #'
+    #' # Or you can also pass a list
+    #' myPlotGrid$addPlots(list("p1" = ggplot(), "p2" = ggplot()))
+    #'
+    #' # Since we added three plots, the `plotList` field should
+    #' # now be a list of length `3`
+    #' length(myPlotGrid$plotList)
+    #'
+    #' @return `PlotGridConfiguration` object with `$plotList` field updated to
+    #'   store entered plots.
+    addPlots = function(plots = NULL) {
+      if (!is.null(plots)) {
+        validateIsOfType(plots, "ggplot")
+
+        # When only single instance of `ggplot` object is entered:
+        # `addPlots = ggplot()`
+        if (objectCount(plots) == 1L) {
+          # This single object needs to be converted to a list *only if* it
+          # already hasn't been entered in a list: `addPlots = list(ggplot())`.
+          #
+          # `ggplot` objects themselves are lists, but they will always have a
+          # length greater than 1. That's how we can distinguish between
+          # `ggplot` object itself as a list and the same object stored in a
+          # list.
+          if (is.list(plots) && length(plots) > 1L) {
+            plots <- list(plots)
+          }
+        }
+
+        self$plotList <- append(self$plotList, plots)
+      }
     }
   )
 )

tests/testthat/test-plot-grid.R

@@ -43,3 +43,24 @@ test_that("plots grid is rendered correctly", {
   #   fig = plotGrid(plotGridObj)
   # )
 })
+
+test_that("adding plots works with plots grid configuration", {
+  myPlotGrid <- PlotGridConfiguration$new()
+
+  # adding single plot works
+  myPlotGrid$addPlots(ggplot())
+
+  expect_equal(length(myPlotGrid$plotList), 1L)
+
+  # adding a list of plot works
+  myPlotGrid$addPlots(list("p1" = ggplot(), "p2" = ggplot()))
+
+  expect_equal(length(myPlotGrid$plotList), 3L)
+
+  # adding a list of a single plot also works
+  myPlotGrid$addPlots(list("p3" = ggplot()))
+
+  expect_equal(length(myPlotGrid$plotList), 4L)
+
+  expect_equal(names(myPlotGrid$plotList), c("", "p1", "p2", "p3"))
+})