Custom Landing Page with connectwidgets

When you want to share deployed content as a cohesive project,

You can use one of the content curation tools available for Connect - connectwidgets - to build a customized landing page to share with your audience.

What is connectwidgets?

connectwidgets is an Posit-maintained R package that can be used to query a Connect server for a subset of your existing content items, then organize them within htmlwidgets in an R Markdown document or Shiny application.

This guide walks you through:

Requirements

  • Have Posit Connect
  • You need administrative privileges to access and edit the Connect configuration file to customize the following:
  • You need to have the following packages installed:
    • "usethis"
    • "xml2"
    • "rmarkdown"

Prework

API keys

If you have previously added API Keys to your .Renviron file as environment variables, please continue to the next section (connectwidgets).

API Keys let us make authenticated requests from RStudio to Connect.

We are going to add our API credentials to a .Renviron file, making them available to R as environment variables.

  • Navigate to Connect and create and copy your API Key.
  • Return to RStudio.
  • Use an .Renviron file to set the CONNECT_SERVER and CONNECT_API_KEY environment variables:

    • Run the following code in your R Console to open your .Renviron for editing:

      usethis::edit_r_environ()

    • Add the following:

      CONNECT_SERVER=<https://your-server-address.com/>
CONNECT_API_KEY=<paste key value>

    • Save and close the .Renviron file.

  • Restart R. Use the Session / Restart R menu item or its keyboard shortcut:
    • Mac: Cmd + Shift + F10
    • PC/Linux: ^ Ctrl + Shift + F10

connectwidgets

Install connectwidgets

Install connectwidegets and load the library:

install.packages("connectwidgets")
library(connectwidgets)
# This is the development version
# install.packages("remotes")
remotes::install_github("rstudio/connectwidgets")
library(connectwidgets)

The template

connectwidgets offers a built-in template that is easy to use and edit to get you started.

The template supplies intro code chunks that:

  • Load dplyr, which is used to create a subset of content from the server that you want to display.
  • Establish a connection to the server by using the environment variables CONNECT_SERVER and CONNECT_API_KEY.
  • Pulls down all of the content that you have access to on the Connect server.
  • Creates a sample_content variable that slices a set number of content items.

Additionally, you can configure a theme, add custom CSS, and select the components that you wish to display.

To use the template:

  • From RStudio, open a new R Markdown file: File > New File > R Markdown….
  • In the left pane, click From Template, select connectwidgets (HTML) and click OK.
  • Knit the template.

Here is an example of the knitted output:

Sample of rendered template.

Why aren’t the thumbnails of the content displaying?

Unfortunately, the thumbnails for the content do not display in development because:

  • That request cannot be made cross-origin. However, the actual content thumbnails are pulled once the page is deployed to Connect.
  • You do not have permission to view the images.
  • An image has not been set.

In the knitted output, notice that your data is grouped by component.

connectwidgets has different types of components, shown above, to display information about your filtered content data:

  • card
  • grid
  • table
  • search & filter (not shown in image above)

For a full description of these components, see the connectwidgets documentation.

Edit the template

Now, we have gotten to the point where we are ready to edit the template, configure theming, and add customizations.

Note

Don’t forget to Knit to apply your changes to the template.

  • Feel free to update the title of the template documentation.

  • Set the theme:

    You can set your theme by supplying a Bootswatch theme, such as minty, in the YAML header of the template:

    template.Rmd
    ---
title: "connectwidgets"
output:
  html_document:
    theme:
      bootswatch: minty
---

    Here is a sample output of the minty theme:

    Example of rendered minty theme.

Customize and choose your displayed content:

  1. Select the content to use/display by adding two helper functions to select content: by_tag and by_owner:

    1. Assuming that you don’t want to display a random set of content, for this example, we are going to filter by content tagged as “Python” and owned by user “kelly.”
    2. Delete the table and search & filter component entries from your template. Now, only the card and grid components display.

  2. You can also replace the stock image with an image of your own.

  3. Additionally, customize the headers for each component.

  4. If you replaced the stock image with an image of your own that isn’t web-based, then add the following to the YAML header:

    1. Add rmd_output_metadata and resource_files:

R Markdown template

You can paste all the R Markdown template changes below directly into your template:

template.Rmd
---
title: "connectwidgets"
output:
  html_document:
    theme:
      bootswatch: minty
rmd_output_metadata:
  rsc_output_files:
    - "connect-widgets.png"
resource_files:
- connect-widgets.png   
---

```{r setup, include=FALSE}
library(connectwidgets)
library(dplyr)

knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE)

client <- connect(
  # server  = Sys.getenv("CONNECT_SERVER"),
  # api_key = Sys.getenv("CONNECT_API_KEY")
)

all_content <- client %>%
  content()

sample_content <- all_content %>%
  by_tag("") %>%
  by_owner("")
```

## Python Content

### Featured Content

```{r card}
sample_content %>%
  slice(1) %>%
  rsc_card()
```

### Additional Content Items

```{r grid}
sample_content %>%
  rsc_grid()
```

Custom CSS

Now, we can take customization a step further and add CSS, which:

  • Adds a solid border to the bottom of the title.
  • Adds an image to the left of the title.
  • Styles the banner image and applies a background color, gradient, padding, and position.

CSS template

You can use the below template in your R Markdown file to easily include all of our customizations:

template.Rmd
```{css, echo=FALSE}

.title {
margin-top: 50px;
padding-bottom: 20px;
padding-left: 85px;
background-image: url("connect-widgets.png");
background-size: auto 64px;
background-repeat: no-repeat;
background-image: left-align;
}


img.banner {
background-color: #303030;
padding-left: 550px;
padding-top: 50px;
padding-bottom: 50px;
backrgound-position: right;
background-image: linear-gradient(to left, #303030 40%, white);
}
```

Here is an example of the rendered output:

Example of customized content.

Lastly, let’s compare the default template vs. the template that has a theme and our custom CSS changes applied:

Side-by-side comparison of the default template vs a themed template with custom CSS changes applied.

Publish your content to Connect

  • Once you are happy with your connectwidgets customizations in RStudio, publish your content to Connect.

Let’s recap!

  • You’ve installed connectwidgets
  • You’ve selected the components that you wish to display
  • Your template is customized
  • You’ve successfully published your content to Connect

A custom dashboard

Instead of the default Connect dashboard, imagine that you want your users to see a visually pretty and well curated dashboard that is built with your connectwidgets project/app after logging into Connect.

Setting the server configuration setting Server.RootRedirect to the vanity URL path for your content lets you do that! For example:

/opt/rstudio-connect/rstudio-connect.gcfg
[Server]
RootRedirect = "/pretty-dashboard"

This is a great way to showcase your pieces of related content and share them as a cohesive project.

To learn more about Server.RootRedirect before continuing, please see the Server.RootRedirect section in the Admin Guide.

Vanity URL

  • Navigate to your Connect server’s dashboard and open your published connectwidgets content.

  • Select the Access panel, set a unique Content URL, and save your changes.

    To learn more, see the Custom Content URL section in the User Guide.

Server.RootRedirect

Requires Role: Administrator

This section has procedures that require you to have administrative privileges to edit the Connect configuration. If you have not been granted these privileges, coordinate someone in your organization that is an administrator.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.

  • To set Server.RootRedirect, update the etc/rstudio-connect/rstudio-connect.gcfg file using the example below:

    File: /etc/rstudio-connect/rstudio-connect.gcfg
    [Server]
RootRedirect ="/pretty-dashboard"

    The /pretty-dashboard value is the same path that you used in the previous section for your Content URL.

  • Save your changes and restart your server:

    Terminal
    systemctl restart rstudio-connect

    Now, when anyone navigates to your Connect Server’s URL, they are redirected to the Server.RootRedirect path which points to your connectwidgets content that is hosted at the vanity URL path.

Server.DashboardPath

You might be wondering, how do I navigate to the Connect dashboard since the Server.RootRedirect brings you to your connectwidgets landing page?

You can configure Server.DashboardPath which is the URL path to where your Connect’s dashboard is hosted, allowing you to continue to access the dashboard.

  • Navigate to the /etc/rstudio-connect/rstudio-connect.gcfg file.

  • To set Server.DashboardPath, update the etc/rstudio-connect/rstudio-connect.gcfg file using the example below:

    File: etc/rstudio-connect/rstudio-connect.gcfg
    [Server]
DashboardPath ="/connect/dashboard"

  • Save your changes and restart your server:

    Terminal
    systemctl restart rstudio-connect

  • Now, open a browser and navigate to your Connect server’s IP using the Server.DashboardPath that you configured above: http://your-connect-server-address:3939/connect/dashboard/

Where do I go from here?

At this point, you know what connectwidgets is, whether it is useful for your workflow, and how to implement it. What’s next?

As you try connectwidgets on your own, here is a list of resources that might be helpful as you implement connectwidgets:

Any issues? Let us know here: https://github.com/rstudio/connectwidgets/issues/