plotly · rpkyle · Feb 11, 2020 · Jan 4, 2020 · Jan 5, 2020 · Jan 9, 2020
@@ -1,6 +1,6 @@
 Package: dash
 Title: An Interface to the Dash Ecosystem for Authoring Reactive Web Applications
-Version: 0.2.0
+Version: 0.3.0
 Authors@R: c(person("Chris", "Parmer", role = c("aut"), email = "chris@plot.ly"), person("Ryan Patrick", "Kyle", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-5829-9867"), email = "ryan@plot.ly"), person("Carson", "Sievert", role = c("aut"), comment = c(ORCID = "0000-0002-4958-2844")), person(family = "Plotly Technologies", role = "cph")) 
 Description: A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required.
 Depends:

@@ -27,4 +27,5 @@ importFrom(routr,RouteStack)
 importFrom(routr,ressource_route)
 importFrom(stats,setNames)
 importFrom(tools,file_ext)
-importFrom(utils,getFromNamespace)
+importFrom(utils,getFromNamespace)
+
@@ -114,7 +114,55 @@
 #'     present a warning and return `NULL` if the Dash app was not loaded via `source()`
 #'     if the `DASH_APP_PATH` environment variable is undefined.
 #'   }
-#'   \item{`run_server(host =  Sys.getenv('HOST', "127.0.0.1"),
+#'  \item{`index_string(string)`}{
+#'     The `index_string` method allows the specification of a custom index by changing
+#'     the default `HTML` template that is generated by the Dash UI. Meta tags, CSS, Javascript,
+#'     are some examples of features that can be modified..This method will present a warning if your 
+#'     HTML template is missing any necessary components and return an error if a valid index is not defined
+#'     {%metas%}        # optional - The registered meta tags.
+#'     {%favicon%}      # optional - A favicon link tag if found in `assets`.
+#'     {%css%}          # optional - link tags to css resources.
+#'     {%config%}       # required - Config generated by dash for the renderer.
+#'     {%app_entry%}    # required - The container where dash react components are rendered.
+#'     {%scripts%}      # required - Collected dependencies scripts tags.
+#'     
+#'     Example of a basic html index:
+#'     "<!DOCTYPE html>
+#'     <html>
+#'       <head>
+#'         {%meta_tags%}
+#'         <title>{private$name}</title>
+#'         {%favicon%}
+#'         {%css_tags%}
+#'       </head>
+#'       <body>
+#'         {%app_entry%}
+#'         <footer>
+#'          {%config%}
+#'          {%scripts%} 
+#'         </footer>
+#'       </body>
+#'     </html>"
+#'
+#'     \describe{
+#'       \item{string}{Character. A formatted string with a complete HTML index}
+#'     }
+#'   }
+#'  \item{`interpolate_index(template_index, ...)`}{
+#'     With the `interpolate_index` method, we can pass a custom index with template string
+#'     variables that are already evaluated. We can directly pass arguments to the `template_index`
+#'     by assigning them to variables present in the template. This is similar to the `index_string` method
+#'     but offers the ability to change the default components of the Dash index as seen in the example below:
+#'     
+#'     """
+#'     app$interpolate_index(template_index, metas = "<meta_charset='UTF-8'/>", renderer = renderer, config = config)
+#'     \describe{
+#'     \item{template_index}{Character. A formatted string with the HTML index string. Defaults to the initial template}
+#'     \item{unnamed arguments}{Named List. These can be passed as individual named lists corresponding to the components
+#'     of the Dash html index. These include the same arguments as those found in the `index_string()` template.}
+#'     }
+#'  } 
+#'  \item{`run_server(host =  Sys.getenv('HOST', "127.0.0.1"),
 #'    port = Sys.getenv('PORT', 8050), block = TRUE, showcase = FALSE, ...)`}{
 #'     The `run_server` method has 13 formal arguments, several of which are optional:
 #'     \describe{
@@ -763,11 +811,53 @@ Dash <- R6::R6Class(
                         sep="/")))
     },
 
+    # ------------------------------------------------------------------------
+    # specify a custom index string
+    # ------------------------------------------------------------------------
+    index_string = function(string) {
+      requiredKeys <- c("app_entry", "config", "scripts")
+
+      checks <- sapply(requiredKeys, function(x) grepl(x, string))
+
+      if (FALSE %in% checks) {
+        stop(sprintf("Did you forget to include %s in your index string?", 
+                     paste(requiredKeys[!checks], collapse = ", ")))
+      }
+      private$custom_index = string
+    },
+
+    # ------------------------------------------------------------------------
+    # modify the templated variables by using the `interpolate_index` method. 
+    # ------------------------------------------------------------------------
+    interpolate_index = function(template_index = private$template_index[[1]], ...) {
+      template = template_index
+      kwargs <- list(...)
+
+      for (name in names(kwargs)) {
+        key = paste0('\\{\\%', name, '\\%\\}')
+        template = sub(key, kwargs[[name]], template)
+      } 
+
+      cat(template)
+
+      requiredKeys <- c("app_entry", "config", "scripts")
+
+      checks <- sapply(requiredKeys, function(x) grepl(x, names(kwargs)))
+
+      if (FALSE %in% checks) {
+        stop(sprintf("Did you forget to include %s in your index string?", 
+                     paste(requiredKeys[!checks], collapse = ", ")))
+      }
+
+      private$template_index = template
+    },
+
     # ------------------------------------------------------------------------
     # convenient fiery wrappers
     # ------------------------------------------------------------------------
     run_server = function(host = Sys.getenv('HOST', "127.0.0.1"),
                           port = Sys.getenv('PORT', 8050),
+
                           block = TRUE,
                           showcase = FALSE,
                           use_viewer = FALSE,
@@ -1266,6 +1356,24 @@ Dash <- R6::R6Class(
 
     # akin to https://github.com/plotly/dash/blob/d2ebc837/dash/dash.py#L338
     # note discussion here https://github.com/plotly/dash/blob/d2ebc837/dash/dash.py#L279-L284
+    custom_index = NULL,
+    template_index = c(
+    "<!DOCTYPE html>
+        <html>
+          <head>
+            {%meta_tags%}
+            <title>{%private$name%}</title>
+            {%favicon%}
+            {%css_tags%}
+          </head>
+          <body>
+            {%app_entry%}
+            <footer>
+              {%config%}
+              {%scripts%}
+            </footer>
+          </body>
+        </html>", NA),
     .index = NULL,
 
     generateReloadHash = function() {
@@ -1434,13 +1542,29 @@ Dash <- R6::R6Class(
       css_tags <- all_tags[["css_tags"]]
 
       # retrieve script tags for serving in the index
-      scripts_tags <- all_tags[["scripts_tags"]]
+      scripts <- all_tags[["scripts_tags"]]
 
       # insert meta tags if present
       meta_tags <- all_tags[["meta_tags"]]
+
+      # define the react-entry-point
+      app_entry <- "<div id='react-entry-point'><div class='_dash-loading'>Loading...</div></div>"
+      # define the dash default config key
+      config <- sprintf("<script id='_dash-config' type='application/json'> %s </script>", to_JSON(self$config))
+
+      if (!is.null(private$custom_index)) {
+        string_index <- glue::glue(private$custom_index, .open = "{%", .close = "%}")
+
+        private$.index <- string_index
+      }
+
+      else if (length(private$template_index) == 1) {
+        private$.index <- private$template_index
+      }
 
-      private$.index <- sprintf(
-        '<!DOCTYPE html>
+      else {
+        private$.index <- sprintf(
+       '<!DOCTYPE html>
         <html>
           <head>
             %s
@@ -1450,23 +1574,22 @@ Dash <- R6::R6Class(
           </head>
 
           <body>
-            <div id="react-entry-point">
-              <div class="_dash-loading">Loading...</div>
-            </div>
-
+            %s
             <footer>
-              <script id="_dash-config" type="application/json"> %s </script>
+              %s
               %s
             </footer>
           </body>
         </html>',
-        meta_tags,
-        private$name,
-        favicon,
-        css_tags,
-        to_JSON(self$config),
-        scripts_tags
-      )
+          meta_tags,
+          private$name,
+          favicon,
+          css_tags,
+          app_entry,
+          config,
+          scripts
+        )
+      }
     }
   )
 )

@@ -1270,3 +1270,20 @@ tryCompress <- function(request, response) {
   }
   return(response$compress())
 }
+
+interpolate_str <- function(index_template, ...) {
+  # This function takes an index string, along with
+  # user specified keys for the html keys of the index
+  # and sets the default values of the keys to the 
+  # ones specified by the keys themselves, returning
+  # the custom index template. 
+  template = index_template 
+  kwargs <- list(...)
+
+  for (name in names(kwargs)) {
+    key = paste0('\\{', name, '\\}')
+
+    template = sub(key, kwargs[[name]], template)
+  } 
+  return(template)
+}
@@ -1,4 +1,4 @@
-[![CircleCI](https://circleci.com/gh/plotly/dashR/tree/dev.svg?style=svg)](https://circleci.com/gh/plotly/dashR/tree/dev)
+[![CircleCI](https://circleci.com/gh/plotly/dashR/tree/master.svg?style=svg)](https://circleci.com/gh/plotly/dashR/tree/master)
 [![GitHub](https://img.shields.io/github/license/plotly/dashR.svg?color=dark-green)](https://github.com/plotly/dashR/blob/master/LICENSE)
 [![GitHub commit activity](https://img.shields.io/github/commit-activity/y/plotly/dashR.svg?color=dark-green)](https://github.com/plotly/dashR/graphs/contributors)