% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/modules.R
\name{module_info}
\alias{module_info}
\alias{current_module}
\alias{active_module}
\alias{switch_module}
\alias{load_module}
\title{Obtain the module information}
\usage{
module_info(root_path = template_root(), settings_file = "modules.yaml")

current_module(
  session = shiny::getDefaultReactiveDomain(),
  root_path = template_root()
)

active_module(
  session = shiny::getDefaultReactiveDomain(),
  root_path = template_root()
)

switch_module(module_id, session = shiny::getDefaultReactiveDomain())

load_module(
  root_path = template_root(),
  request = list(QUERY_STRING = "/"),
  env = parent.frame()
)
}
\arguments{
\item{root_path}{the root path of the website project}

\item{settings_file}{the settings file containing the module information}

\item{session}{shiny reactive domain; used to extract the module id from
the URL query string when \code{.module_id} is not found.}

\item{module_id}{character string; the target module identifier (must
match an entry in \file{modules.yaml}).}

\item{request}{'HTTP' request string}

\item{env}{environment to load module variables into}
}
\value{
A data frame with the following columns that contain the module
information:
\describe{
\item{\code{id}}{module id, folder name}
\item{\code{order}}{display order in side-bar}
\item{\code{group}}{group menu name if applicable, otherwise \code{NA}}
\item{\code{label}}{the readable label to be displayed on the side-bar}
\item{\code{icon}}{icon that will be displayed ahead of label, will be
passed to \code{\link{as_icon}}}
\item{\code{badge}}{badge text that will be displayed
following the module label, will be passed to \code{\link{as_badge}}}
\item{\code{url}}{the relative 'URL' address of the module.}
}

\code{current_module}: a named list with \code{id}, \code{group},
\code{label}, \code{icon}, \code{badge}, and \code{url} of the current
module, or \code{NULL} if no module is active.

\code{active_module}: a named list with \code{id}, \code{group},
\code{label}, \code{icon}, \code{badge}, and \code{url} of the
currently active (visible) module, or \code{NULL} if no module is active.
}
\description{
\code{current_module} returns the information of the currently
running module. It looks up the \code{.module_id} variable in the calling
environment (set automatically when a module is loaded), then retrieves
the corresponding row from the module table.

\code{active_module} returns a \emph{reactive} value with
information about the module that is currently visible in the \verb{iframe}
tab (or the standalone module if no \verb{iframe} manager is present).
Unlike \code{current_module} which is static and always returns the module
whose server code is running, \code{active_module} dynamically tracks
which module the user is looking at from any context.

\code{switch_module} programmatically switches the active
module in the dashboard UI.
It sends a \code{shidashi.switch_module} message to the JavaScript
front-end.  When called from a module running inside an \verb{iframe}, the
handler automatically forwards the request to the parent window via
\code{postMessage} so that the sidebar highlight, tab bar, and \verb{iframe}
all update correctly.
}
\details{
The module files are stored in \code{modules/} folder in your
project. The folder names are the module id. Within each folder,
there should be one \code{"server.R"}, \code{R/}, and a
\code{"module-ui.html"}.

The \code{R/} folder stores R code files that generate variables,
which will be available to the other two files. These variables, along
with some built-ins, will be used to render \code{"module-ui.html"}.
The built-in functions are
\describe{
\item{ns}{shiny name-space function; should be used to generate the id for
inputs and outputs. This strategy avoids conflict id effectively.}
\item{.module_id}{a variable of the module id}
\item{module_title}{a function that returns the module label}
}

The \code{"server.R"} has access to all the code in \code{R/} as well.
Therefore it is highly recommended that you write each 'UI' component
side-by-side with their corresponding server functions and call
these server functions in \code{"server.R"}.

\code{active_module} works by reading the
\code{'@shidashi_active_module@'} Shiny input that is set by the
JavaScript front-end whenever a module tab is activated.
Because it accesses \code{session$rootScope()$input}, the return value
is reactive: when called inside an \code{observe} or \code{reactive}
context it will re-fire whenever the user switches modules.

If the input has not been set yet (e.g. before any module is opened),
the function falls back to \code{current_module()}.
}
\examples{

library(shiny)
module_info()

# load master module
load_module()

# load specific module
module_data <- load_module(
  request = list(QUERY_STRING = "/?module=module_id"))
env <- module_data$environment

if (interactive()) {

# get module title
env$module_title()

# generate module-specific shiny id
env$ns("input1")

# generate part of the UI
env$ui()

}

}
