22# '
33# ' Scoutbar react widget for Shiny.
44# '
5+ # ' Provides a contextual menu users can activate
6+ # ' with keyboard shortcut or prommatically with \link{update_scoutbar}.
7+ # ' Scoutbar may be seen as an alternative to sidebars and navbars, as it allows
8+ # ' to construct better navigation menus.
9+ # '
510# ' @importFrom reactR createReactShinyInput
611# ' @importFrom htmltools htmlDependency tags
712# '
1520# ' @param ... Any other configuration parameter. See
1621# ' \url{https://www.scoutbar.co/docs/features}.
1722# '
23+ # ' @return A list of shiny tags containing all the web dependencies
24+ # ' and scoutbar elements required to instantiate the Scoutbar React widget from
25+ # ' JavaScript.
1826# ' @export
19- # ' @rdname scout-bar
27+ # ' @rdname scoutbar
2028scoutbar <- function (
2129 inputId ,
2230 theme = c(" light" " dark" " auto"
@@ -51,20 +59,42 @@ scoutbar <- function(
5159# ' Can embed \link{scout_action} on a separate
5260# ' view of the Scoutbar.
5361# '
62+ # ' Whenever many \link{scout_action} share a similar topic,
63+ # ' or have nested topics, this function allows you to provide a better
64+ # ' experience by isolating some actions in a separate view. You can nest
65+ # ' pages within other pages and combine it with \link{scout_section}.
66+ # '
5467# ' @param label Page label.
5568# ' @param ... Expect \link{scout_action}.
5669# ' @param .list To pass a list of \link{scout_action}.
70+ # ' \itemize{
71+ # ' \item children: a sublist where are passed the \link{scout_action}.
72+ # ' \item label: The page label.
73+ # ' \item class: a character vector to identify the page on the JavaScript side.
74+ # ' You are not expected to modify it as it will break the JavaScript binding.
75+ # ' }
5776# ' @export
5877scout_page <- function (label , ... , .list = NULL ) {
5978 scout_container(" scout_page" .list , label , ... )
6079}
6180
6281# ' Creates a scout section
6382# '
64- # ' Can sort \link{scout_action} on the same view.
83+ # ' Sort \link{scout_action} on the same view.
84+ # '
85+ # ' Whenever many \link{scout_action} share a similar topic,
86+ # ' you may use this function to sort them in the UI and offer
87+ # ' a better user experience. You can combine it with \link{scout_page}.
6588# '
6689# ' @param label Section label.
6790# ' @inheritParams scout_page
91+ # ' @return A list containing:
92+ # ' \itemize{
93+ # ' \item children: a sublist where are passed the \link{scout_action}.
94+ # ' \item label: The section label.
95+ # ' \item class: a character vector to identify the section on the JavaScript side.
96+ # ' You are not expected to modify it as it will break the JavaScript binding.
97+ # ' }
6898# ' @export
6999scout_section <- function (label , ... , .list = NULL ) {
70100 scout_container(" scout_section" .list , label , ... )
@@ -81,14 +111,26 @@ scout_container <- function(cl, .list, label, ...) {
81111
82112# ' Creates a scout action
83113# '
84- # ' Can sort \link{scout_action} on the same view.
114+ # ' Creates an item that can perform actions on the server side.
115+ # '
116+ # ' This function is meant to be embeded directly within
117+ # ' \link{scoutbar} or via a more structured way within \link{scout_page}
118+ # ' or \link{scout_section}. It serves as a bridge between R and JavaScript to
119+ # ' communicate with the Scoutbar React API, so you are not expected to call it on its
120+ # ' own.
85121# '
86122# ' @param id Unique id.
87123# ' @param label Action label.
88124# ' @param description Action description.
89125# ' @param closeOnClick Whether to close the scoutbar whenever this action is
90126# ' clicked. Default to TRUE.
91127# ' @param ... Other options. See \url{https://www.scoutbar.co/docs/actions}.
128+ # ' @return A list containing:
129+ # ' \itemize{
130+ # ' \item children: a sublist where are passed the options.
131+ # ' \item class: a character vector to identify the action on the JavaScript side.
132+ # ' You are not expected to modify it as it will break the JavaScript binding.
133+ # ' }
92134# ' @export
93135scout_action <- function (id , label , description , closeOnClick = TRUE , ... ) {
94136 props <- list (
@@ -110,19 +152,22 @@ scout_action <- function(id, label, description, closeOnClick = TRUE, ...) {
110152
111153# ' Update a Scoutbar widget on the client
112154# '
113- # ' Usee this function from the server side of
114- # ' your Shiny app.
155+ # ' Use this function from the server side of
156+ # ' your Shiny app to update a \link{scoutbar} .
115157# '
116158# ' @export
117159# ' @param session Shiny session object.
118- # ' @param configuration Scoutbar configuration. Expect a list of properties.
119- # ' See possible values here at \url{https://www.scoutbar.co/docs/features}.
120- # ' @rdname scout-bar
160+ # ' @param ... Scoutbar configuration. Expect a list of properties
161+ # ' like in \link{scoutbar}. See possible values here at \url{https://www.scoutbar.co/docs/features}.
162+ # ' @return This function is called for its side effect. It sends a message to JavaScript
163+ # ' through the current websocket connection, leveraging the shiny session object.
164+ # ' @rdname scoutbar
121165update_scoutbar <- function (
122166 session = shiny :: getDefaultReactiveDomain(),
123167 inputId ,
124- configuration = NULL ) {
168+ ... ) {
125169 message <- list ()
170+ configuration <- list (... )
126171 if (! is.null(configuration )) {
127172 message $ configuration <- c(
128173 configuration ,
0 commit comments