Add NEWS item

NAMESPACE

@@ -146,6 +146,7 @@ export(maskReactiveContext)
 export(memoryCache)
 export(modalButton)
 export(modalDialog)
+export(moduleServer)
 export(navbarMenu)
 export(navbarPage)
 export(navlistPanel)

NEWS.md

@@ -7,6 +7,8 @@ shiny 1.4.0.9001
 
 ### New features
 
+* The new `moduleServer` function provides a simpler interface for creating and using modules. ([#2773](https://github.com/rstudio/shiny/pull/2773))
+
 ### Minor new features and improvements
 
 * Fixed [#2042](https://github.com/rstudio/shiny/issues/2042), [#2628](https://github.com/rstudio/shiny/issues/2628): In a `dateInput` and `dateRangeInput`, disabled months and years are now a lighter gray, to make it easier to see that they are disabled. ([#2690](https://github.com/rstudio/shiny/pull/2690))

R/modules.R

@@ -37,24 +37,100 @@ createSessionProxy <- function(parentSession, ...) {
 `[[<-.session_proxy` <- `$<-.session_proxy`
 
 
-#' Invoke a Shiny module
+#' Shiny modules
 #'
 #' Shiny's module feature lets you break complicated UI and server logic into
 #' smaller, self-contained pieces. Compared to large monolithic Shiny apps,
 #' modules are easier to reuse and easier to reason about. See the article at
 #' <http://shiny.rstudio.com/articles/modules.html> to learn more.
 #'
-#' @param module A Shiny module server function
+#' Starting in Shiny 1.5.0, we recommend using `moduleFunction` instead of
+#' `callModule`, because syntax is a little easier to understand.
+#'
+#' @param module A Shiny module server function.
 #' @param id An ID string that corresponds with the ID used to call the module's
-#'   UI function
-#' @param ... Additional parameters to pass to module server function
+#'   UI function.
+#' @param ... For `callModule`, additional parameters to pass to module server
+#'   function.
 #' @param session Session from which to make a child scope (the default should
-#'   almost always be used)
+#'   almost always be used).
 #'
 #' @return The return value, if any, from executing the module server function
 #' @seealso <http://shiny.rstudio.com/articles/modules.html>
+#'
+#' @examples
+#' # Define the UI for a module
+#' counterUI <- function(id, label = "Counter") {
+#'   ns <- NS(id)
+#'   tagList(
+#'     actionButton(ns("button"), label = label),
+#'     verbatimTextOutput(ns("out"))
+#'   )
+#' }
+#'
+#' # Define the server logic for a module
+#' counterServer <- function(id) {
+#'   moduleServer(id, function(input, output, session) {
+#'     count <- reactiveVal(0)
+#'     observeEvent(input$button, {
+#'       count(count() + 1)
+#'     })
+#'     output$out <- renderText({
+#'       count()
+#'     })
+#'     count
+#'   })
+#' }
+#'
+#' # Use the module in an app
+#' ui <- fluidPage(
+#'   counterUI("counter1", "Counter #1"),
+#'   counterUI("counter2", "Counter #2")
+#' )
+#' server <- function(input, output, session) {
+#'   counterServer("counter1")
+#'   counterServer("counter2")
+#' }
+#' shinyApp(ui, server)
+#'
+#'
+#'
+#' # If you want to pass extra parameters to the module's server logic, you can
+#' # add them to your function. In this case `prefix` is text that will be
+#' # printed before the count.
+#' counterServer2 <- function(id, prefix = NULL) {
+#'   moduleServer(id, function(input, output, session) {
+#'     count <- reactiveVal(0)
+#'     observeEvent(input$button, {
+#'       count(count() + 1)
+#'     })
+#'     output$out <- renderText({
+#'       paste0(prefix, count())
+#'     })
+#'     count
+#'   })
+#' }
+#'
+#' ui <- fluidPage(
+#'   counterUI("counter", "Counter"),
+#' )
+#' server <- function(input, output, session) {
+#'   counterServer2("counter", "The current count is: ")
+#' }
+#' shinyApp(ui, server)
+#'
+#' @export
+moduleServer <- function(id, module, session = getDefaultReactiveDomain()) {
+  callModule(module, id, session = session)
+}
+
+
+#' @rdname moduleServer
 #' @export
 callModule <- function(module, id, ..., session = getDefaultReactiveDomain()) {
+  if (!inherits(session, "ShinySession") && !inherits(session, "session_proxy")) {
+    stop("session must be a ShinySession or session_proxy object.")
+  }
   childScope <- session$makeScope(id)
 
   withReactiveDomain(childScope, {

man/callModule.Rd

@@ -1,31 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/modules.R
-\name{callModule}
-\alias{callModule}
-\title{Invoke a Shiny module}
-\usage{
-callModule(module, id, ..., session = getDefaultReactiveDomain())
-}
-\arguments{
-\item{module}{A Shiny module server function}
-
-\item{id}{An ID string that corresponds with the ID used to call the module's
-UI function}
-
-\item{...}{Additional parameters to pass to module server function}
-
-\item{session}{Session from which to make a child scope (the default should
-almost always be used)}
-}
-\value{
-The return value, if any, from executing the module server function
-}
-\description{
-Shiny's module feature lets you break complicated UI and server logic into
-smaller, self-contained pieces. Compared to large monolithic Shiny apps,
-modules are easier to reuse and easier to reason about. See the article at
-\url{http://shiny.rstudio.com/articles/modules.html} to learn more.
-}
-\seealso{
-\url{http://shiny.rstudio.com/articles/modules.html}
-}

man/moduleServer.Rd

@@ -0,0 +1,101 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/modules.R
+\name{moduleServer}
+\alias{moduleServer}
+\alias{callModule}
+\title{Shiny modules}
+\usage{
+moduleServer(id, module, session = getDefaultReactiveDomain())
+
+callModule(module, id, ..., session = getDefaultReactiveDomain())
+}
+\arguments{
+\item{id}{An ID string that corresponds with the ID used to call the module's
+UI function.}
+
+\item{module}{A Shiny module server function.}
+
+\item{session}{Session from which to make a child scope (the default should
+almost always be used).}
+
+\item{...}{For \code{callModule}, additional parameters to pass to module server
+function.}
+}
+\value{
+The return value, if any, from executing the module server function
+}
+\description{
+Shiny's module feature lets you break complicated UI and server logic into
+smaller, self-contained pieces. Compared to large monolithic Shiny apps,
+modules are easier to reuse and easier to reason about. See the article at
+\url{http://shiny.rstudio.com/articles/modules.html} to learn more.
+}
+\details{
+Starting in Shiny 1.5.0, we recommend using \code{moduleFunction} instead of
+\code{callModule}, because syntax is a little easier to understand.
+}
+\examples{
+# Define the UI for a module
+counterUI <- function(id, label = "Counter") {
+  ns <- NS(id)
+  tagList(
+    actionButton(ns("button"), label = label),
+    verbatimTextOutput(ns("out"))
+  )
+}
+
+# Define the server logic for a module
+counterServer <- function(id) {
+  moduleServer(id, function(input, output, session) {
+    count <- reactiveVal(0)
+    observeEvent(input$button, {
+      count(count() + 1)
+    })
+    output$out <- renderText({
+      count()
+    })
+    count
+  })
+}
+
+# Use the module in an app
+ui <- fluidPage(
+  counterUI("counter1", "Counter #1"),
+  counterUI("counter2", "Counter #2")
+)
+server <- function(input, output, session) {
+  counterServer("counter1")
+  counterServer("counter2")
+}
+shinyApp(ui, server)
+
+
+
+# If you want to pass extra parameters to the module's server logic, you can
+# add them to your function. In this case `prefix` is text that will be
+# printed before the count.
+counterServer2 <- function(id, prefix = NULL) {
+  moduleServer(id, function(input, output, session) {
+    count <- reactiveVal(0)
+    observeEvent(input$button, {
+      count(count() + 1)
+    })
+    output$out <- renderText({
+      paste0(prefix, count())
+    })
+    count
+  })
+}
+
+ui <- fluidPage(
+  counterUI("counter", "Counter"),
+)
+server <- function(input, output, session) {
+  counterServer2("counter", "The current count is: ")
+}
+shinyApp(ui, server)
+
+}
+\seealso{
+\url{http://shiny.rstudio.com/articles/modules.html}
+}