Overview

RStudio v1.1 introduces support for custom, user-defined project templates. Project templates can be used to create new projects with a pre-specified structure.

Project templates can be accessed through the New Project… wizard. All registered project templates are made available within the New Directory portion of the wizard:

R packages are the primary vehicle through which RStudio project templates are distributed. Package authors can provide a small bit of metadata describing the template functions available in their package – RStudio will discover these project templates on start up, and make them available in the New Project… dialog.

Example

We’ll use the ptexamples package to illustrate how a project template can be defined. This package exports a project template that is presented like so from the New Project… wizard:

After the user clicks Create Project, a new project will be created, and the hello_world() template function will be called to initialize the project. Here’s what the IDE looks like after calling this template function with the aforementioned inputs:

If you want to try using this project template yourself, try installing the package with:

devtools::install_github("rstudio/ptexamples")

and then accessing it from the New Project… wizard.

Let’s dive in and see how exactly the ptexamples package defines and exports this project template.

Defining the Template Function

The ptexamples package contains a function, hello_world(), intended to be used as a project template. The function has the signature:

hello_world <- function(path, ...) {
  # ensure path exists
  dir.create(path, recursive = TRUE, showWarnings = FALSE)

  # generate header for file
  header <- c(
    "# This file was generated by a call to 'ptexamples::hello_world()'.",
    "# The following inputs were received:",
    ""
  )

  # collect inputs and paste together as 'Parameter: Value'
  dots <- list(...)
  text <- lapply(seq_along(dots), function(i) {
    key <- names(dots)[[i]]
    val <- dots[[i]]
    paste0(key, ": ", val)
  })

  # collect into single text string
  contents <- paste(
    paste(header, collapse = "\n"),
    paste(text, collapse = "\n"),
    sep = "\n"
  )

  # write to index file
  writeLines(contents, con = file.path(path, "INDEX"))
}

When this function is invoked by RStudio, it will receive the path as the path to the newly created project, as well as arguments as received from its input widgets. This function simply collects its inputs, and echos them to a file called INDEX in the newly-created project path.

Defining the Template Metadata

After defining a function to be used as a project template, some initial metadata must be provided to let RStudio know how to use this function as a project template. The ptexamples package defines a project template in a file located at:

https://github.com/rstudio/ptexamples/blob/master/inst/rstudio/templates/project/hello_world.dcf

The first set of fields are used to define primary information about the project template:

Binding: hello_world
Title: Example Project Template
OpenFiles: INDEX

  • The Binding field tells RStudio which R function the project template is associated with. When a user creates a new project using this template, the hello_world() function defined by this package will be used to generate the project.

  • The Title field is used and shown within the new project wizard.

  • The OpenFiles field instructs the IDE to open a file called INDEX when the project is first opened, after creating the project.

The following sets of fields are used to define input widgets – we’ll examine the first widget description in detail.

Parameter: check
Widget: CheckboxInput
Label: Checkbox Input
Default: On
Position: left

  • The Parameter field is used to identify the parameter name. That is, the value of the widget used here will be associated with the parameter called check when passed to the template function hello_world().

  • The Widget field is used to specify the type of widget to be used. Here, we use a checkbox, to allow for ‘on / off’ input from the user.

  • The Label field is used to give a label associated with the checkbox.

  • The Default field gives the default value for the checkbox input – here, we want to default having the checkbox ‘on’, or checked.

  • The Position field tells the RStudio IDE that this widget should be displayed on the left side of the wizard dialog.

All together, this information tells RStudio that hello_world() is a function to be used in generating new projects, as well as what widgets should be used for arguments that the hello_world() can accept.

Reference

Primary Metadata

The following fields are accepted as part of the primary metadata regarding a project template:

  • Binding (required): The name of the R function to be called when this project template is invoked.

  • Title (required): The title to be shown within the New Project… wizard.

  • Subtitle: The subtitle to be shown within the New Project… wizard. This will be shown when the user hovers over the project name in the dialog. When unsupplied, this field will be generated based on the content of the Title field.

  • Caption: The caption to be shown on the landing page for this template function. When unsupplied, this field will be generated based on the content of the Title field.

  • Icon: The path to an icon, on disk, to be used in the dialog. Must be a .png file of size less than 64kb.

  • OpenFiles: A comma-delimited set of values, indicating files that should be opened by RStudio when the project is generated. Shell-style globs can be used to indicate when multiple files matching some pattern should be opened – for example, OpenFiles: R/*.R would indicate that RStudio should open all .R files within the R folder of the generated project.

Input Widgets

The following widget types are accepted for the Widget field in widget descriptions.

CheckboxInput

Represent a TRUE / FALSE input value using a checkbox.

Example
Parameter: check
Widget: CheckboxInput
Label: label

SelectInput

Select a single item out of a menu list of items. The Fields field should be a comma-separated list of fields to be included in the select input.

Example
Parameter: project_type
Widget: SelectInput
Label: Project Type
Fields: project, package

TextInput

Accept unrestricted text input from the user.

Example
Parameter: author
Widget: TextInput
Label: Author

FileInput

Provide the path to a file on disk.

Example
Parameter: file
Widget: FileInput
Label: Data file