Add shiny best practice #120
Open
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
christopherdias11
requested review from
rmbielby,
cjrace,
chfoster and
jen-machin
jen-machin
reviewed
Nov 19, 2024
|
|
||
| --- | ||
|
|
||
| There a lots of options for rendering tables in Quarto, RMarkdown and R Shiny, many of which are covered in [this blog about beautiful tables](https://rfortherestofus.com/2019/11/how-to-make-beautiful-tables-in-r/). Think about the user needs in the first instance and go from there - there's compelling arguments for each package mentioned. |
There was a problem hiding this comment.
I think this should be "there are" at the start of the paragraph
| There are a lot of resources already available to support you when working with R Shiny, if you're new, then this [blog post](https://www.r-bloggers.com/2021/03/a-gentle-introduction-to-r-shiny/) provides a gentle introduction. | ||
|
|
||
| If you like learning by reading/doing then the [Posit Shiny-specific site](https://shiny.posit.co/r/getstarted/shiny-basics/lesson1/index.html) has lots of resources that you can work through. Likewise [Introduction section of Mastering Shiny](https://mastering-shiny.org/basic-intro.html) is also a helpful resources. |
There was a problem hiding this comment.
for accessibility reasons we should try and have spaces before and after /
e.g. reading / doing
| Our [template shiny app repository](https://github.com/dfe-analytical-services/shiny-template) is a useful starting point for all public facing dashboards in the department. Please see the [dashboard template section](#dfe-dashboard-template) for guidance on what the dashboard template includes and how to use it. | ||
|
|
||
| For more advanced shiny knowledge it's worth taking a look at the guide to [engineering production-grade shiny apps](https://engineering-shiny.org/). | ||
| [Shiny layouts](https://shiny.posit.co/r/layouts/) gives a high level idea of how to structure an R Shiny app. Alongside this it is recommended you take a look at [`bslib`](https://rstudio.github.io/bslib/index.html) which makes constructing beautiful user interface easy. This site is full of information on how to construct the page and how to work themeing. If you like watching it done then [this video](https://www.youtube.com/watch?v=3l3w2p1Fy4M) is a good place to start. |
There was a problem hiding this comment.
Should be "interfaces", not "interface"? Sorry, nitpicky comment
| - Your code should be [tested](#code-testing) | ||
| - Your file structure should be [well-organised](https://mastering-shiny.org/best-practices.html#code-organization) | ||
| - You should use [dependency management](https://mastering-shiny.org/best-practices.html#dependency-management) | ||
| - If using [databases](#databases-with-shiny), you should use the pool package and ensure you are careful of SQL Injection |
There was a problem hiding this comment.
Not sure if we have much info on SQL injection - worth adding an explainer sentence here maybe so people know what it is? Either here or in the actual section itself
| } | ||
| ``` | ||
|
|
||
| ### Levelling up your shiny |
There was a problem hiding this comment.
Shiny should have capital S here (sorry)
|
|
||
| For improving your **tables**, check out [this section](../learning-development/r.html#rendering-tables). | ||
|
|
||
| For more advanced shiny knowledge it's worth taking a look at the guide to [engineering production-grade shiny apps](https://engineering-shiny.org/). It's worth reading and considering how much to adopt, remember that just because it sounds clever doesn't make it easy for other analysts to pick up. Read the [Don't sacrifice readability](https://engineering-shiny.org/need-for-optimization.html#dont-sacrifice-readability) section and then work from there. |
| - Going beyond DfE there's a wealth of resources and communities online, including [Stack Overflow](https://stackoverflow.com/) discussions, cross government slack channels (e.g. #R and #Shiny on govdatascience.slack.com) and even tweets about [R Shiny on twitter](https://twitter.com/search?q=rshiny&src=spelling_expansion_revert_click). | ||
|
|
||
| --- | ||
|
|
||
| # DfE styling and the DfE R Shiny template | ||
| ## DfE styling and the DfE R Shiny template | ||
|
|
||
| --- |
There was a problem hiding this comment.
Level 2 headings don't need --- under them so this one can be removed 😄
|
|
||
| --- | ||
|
|
||
| Our [template shiny app repository](https://github.com/dfe-analytical-services/shiny-template) should be used a starting point for all public facing dashboards as it gives a consistent set up for publishing and provides template code for common parts. You can start your own repository using the 'Use this template' green button on the template repository. You will need a GitHub account to do this. If you are unsure or need help, contact the Statistics Development team who will be able to walk you through this. | ||
|
|
||
| --- | ||
|
|
||
| ## What's in the template | ||
| ### What's in the template |
There was a problem hiding this comment.
Level 3 headings DO need --- underneath
Several more of these below with the same issue 😄
|
|
||
| In terms of colour choices beyond charts, teams should pick from the [gov.uk design system colours](https://design-system.service.gov.uk/styles/colour/) when creating dashboards. Colours for the charts are pulled in using the [afcolours package](https://best-practice-and-impact.github.io/afcolours/), which is based on the [GSS colours guidance](https://analysisfunction.civilservice.gov.uk/policy-store/data-visualisation-colours-in-charts/). These colours can be reused elsewhere if you need to match colours with those in the charts. | ||
|
|
||
| As with charts, be careful when choosing colours, and make sure that colours have sufficient contrast to be placed next to each other to meet WCAG AA standards using the [colour contrast checker](https://webaim.org/resources/contrastchecker/). | ||
|
|
||
| --- | ||
|
|
||
| # Hosting dashboard code on GitHub | ||
| ## Hosting dashboard code on GitHub | ||
|
|
||
| --- |
| @@ -170,7 +282,7 @@ Given the above, all analysts intending to create a dashboard should ensure they | |||
|
|
|||
| --- | |||
|
|
|||
| # Publishing your dashboard | |||
| ## Publishing your dashboard | |||
|
|
|||
| --- | |||
chfoster
reviewed
Nov 19, 2024
|
|
||
| --- | ||
|
|
||
| Shiny is an R package that makes it easy to build interactive web apps straight from R. You can host standalone apps on a webpage, embed them in [R Markdown documents](http://rmarkdown.rstudio.com/) or build [dashboards](http://rstudio.github.io/shinydashboard/). You can also extend your Shiny apps with [CSS themes](http://rstudio.github.io/shinythemes/), [htmlwidgets](http://www.htmlwidgets.org/), and [JavaScript actions](https://github.com/daattali/shinyjs/blob/master/README.md). |
There was a problem hiding this comment.
Why remove this link? Is it outdated?
| Our [template shiny app repository](https://github.com/dfe-analytical-services/shiny-template) is a useful starting point for all public facing dashboards in the department. Please see the [dashboard template section](#dfe-dashboard-template) for guidance on what the dashboard template includes and how to use it. | ||
|
|
||
| For more advanced shiny knowledge it's worth taking a look at the guide to [engineering production-grade shiny apps](https://engineering-shiny.org/). | ||
| [Shiny layouts](https://shiny.posit.co/r/layouts/) gives a high level idea of how to structure an R Shiny app. Alongside this it is recommended you take a look at [`bslib`](https://rstudio.github.io/bslib/index.html) which makes constructing beautiful user interface easy. This site is full of information on how to construct the page and how to work themeing. If you like watching it done then [this video](https://www.youtube.com/watch?v=3l3w2p1Fy4M) is a good place to start. |
There was a problem hiding this comment.
I get this when i try the video link:
| [Shiny layouts](https://shiny.posit.co/r/layouts/) gives a high level idea of how to structure an R Shiny app. Alongside this it is recommended you take a look at [`bslib`](https://rstudio.github.io/bslib/index.html) which makes constructing beautiful user interface easy. This site is full of information on how to construct the page and how to work themeing. If you like watching it done then [this video](https://www.youtube.com/watch?v=3l3w2p1Fy4M) is a good place to start. | ||
|
|
||
| :::{.callout-warning} | ||
| Previously a lot of dashboards used `shinydashboard` - if starting afresh we **recommend `bslib` instead**. `shinydashboard` is uses an old version of bootstrap and has not been updated in many years. It shouldn't immediately break but a risk nonetheless. |
There was a problem hiding this comment.
@rmbielby to check messaging - I know the dfeshiny package uses bslib now so do we want to use stronger language to push towards bslib?
There was a problem hiding this comment.
I think that level of pushing bslib is fine.
|
|
||
| ### Databases with Shiny | ||
|
|
||
| Currently only internal dashboards can have connectivity to databases. Check out [this data article from Posit](https://solutions.posit.co/connections/db/best-practices/) on best practice - in particular you should look to use the [`pool`](https://rstudio.github.io/pool/) package for database connections and be careful of [SQL Injection](https://solutions.posit.co/connections/db/best-practices/run-queries-safely/). |
| Finally, you should seek to make use of the community that is already out there, see what others are doing, ask them questions and for advice on any decisions or problems that you're facing, and share what it is that you're doing. | ||
| - The Statistics Development Team are experienced with R Shiny and happy to help or offer advice, and there is the [DfE R community](https://teams.microsoft.com/l/team/19%3a311ec2e4d46b4dd38f0d61f05fb93383%40thread.skype/conversations?groupId=b95c605d-8fbc-4e4d-9a76-2f7d1c55e70a&tenantId=fad277c9-c60a-4da1-b5f3-b3b8b34a82f9) on teams. | ||
| - There is a bank of [tips and tricks](https://teams.microsoft.com/l/entity/com.microsoft.teamspace.tab.wiki/tab::d9f50997-7180-407d-baf9-47f9ec9d54a3?context=%7B%22subEntityId%22%3A%22%7B%5C%22pageId%5C%22%3A21%2C%5C%22origin%5C%22%3A2%7D%22%2C%22channelId%22%3A%2219%3A311ec2e4d46b4dd38f0d61f05fb93383%40thread.skype%22%7D&tenantId=fad277c9-c60a-4da1-b5f3-b3b8b34a82f9){target="_blank" rel="noopener noreferrer"} stored in the DfE R teams area too. | ||
| - The Statistics Development Team are experienced with R Shiny and happy to help or offer advice; |
There was a problem hiding this comment.
I think we should make this a mailto:statistics.development@education.gov.uk?
chfoster
reviewed
Nov 19, 2024
| If you like learning by watching then the [Posit Youtube channel](https://www.youtube.com/@PositPBC/videos) is also full of good resources. | ||
|
|
||
| ### Creating a user interface | ||
|
|
||
| Our [template shiny app repository](https://github.com/dfe-analytical-services/shiny-template) is a useful starting point for all public facing dashboards in the department. Please see the [dashboard template section](#dfe-dashboard-template) for guidance on what the dashboard template includes and how to use it. |
There was a problem hiding this comment.
Chris didn't do this but the #dfe-dashboard-template link isn't working (think it needs changing to #dfe-styling-and-the-dfe-r-shiny-template ???)
chfoster
requested changes
Nov 19, 2024
| HTML, CSS and Bootstrap are a slippery slope into web development. Remember that if you're working with Shiny then good analysis comes first! | ||
| ::: | ||
|
|
||
| For **interactive maps**, check out [this section](../learning-development/r.html#example-shiny-app-with-map). |
There was a problem hiding this comment.
'this section' isn't great link text for accessibility, could you make it more like 'this section on interactive maps' ?
|
|
||
| For **interactive maps**, check out [this section](../learning-development/r.html#example-shiny-app-with-map). | ||
|
|
||
| For improving your **tables**, check out [this section](../learning-development/r.html#rendering-tables). |
chfoster
reviewed
Nov 19, 2024
|
|
||
| --- | ||
|
|
||
| Our [template shiny app repository](https://github.com/dfe-analytical-services/shiny-template) should be used a starting point for all public facing dashboards as it gives a consistent set up for publishing and provides template code for common parts. You can start your own repository using the 'Use this template' green button on the template repository. You will need a GitHub account to do this. If you are unsure or need help, contact the Statistics Development team who will be able to walk you through this. | ||
|
|
||
| --- | ||
|
|
||
| ## What's in the template | ||
| ### What's in the template | ||
|
|
||
| The template provides code for a basic interactive dashboard, with an example line chart using drop-downs for education level and geographic levels. It also includes an example accessibility statement (this is a requirement for all public dashboards and must be filled in, see the [Accessibility](#accessibility) and [Accessibility testing](#accessibility-testing) sections earlier in this guidance), and a 'Support and feedback' page with suggested contact information and links. |
There was a problem hiding this comment.
Again, Chris didn't add this text but the section links to #accessibility and accessibility-testing are outdated/not working
rmbielby
requested changes
Nov 25, 2024
| - [Functions with Shiny](https://mastering-shiny.org/scaling-functions.html) make your life much easier | ||
|
|
||
|
|
||
| ### Databases with Shiny |
There was a problem hiding this comment.
I'd be keen to have this section down in Dashboards and data section rather than up here. Wary that we'll end up with repetition or conflict having this as a separate thing.
|
|
||
| [Mastering Shiny](https://mastering-shiny.org/index.html) is a really useful read, especially the [Best Practice](https://mastering-shiny.org/scaling-intro.html) section. | ||
|
|
||
| There is a plethora of [awesome shiny extensions](https://github.com/nanxstats/awesome-shiny-extensions) to explore. Keep it accessible, use packages from CRAN/ones you trust and the world is your oyster. |
There was a problem hiding this comment.
I'm not keen on pointing analysts to extra extensions as standard, without us first verifying that they are definitely built with accessibility and continuity of service in mind. Too many dashboards already use shinyWidgets, which are a complete crapshow in terms of accessibility.
| [Shiny layouts](https://shiny.posit.co/r/layouts/) gives a high level idea of how to structure an R Shiny app. Alongside this it is recommended you take a look at [`bslib`](https://rstudio.github.io/bslib/index.html) which makes constructing beautiful user interface easy. This site is full of information on how to construct the page and how to work themeing. If you like watching it done then [this video](https://www.youtube.com/watch?v=3l3w2p1Fy4M) is a good place to start. | ||
|
|
||
| :::{.callout-warning} | ||
| Previously a lot of dashboards used `shinydashboard` - if starting afresh we **recommend `bslib` instead**. `shinydashboard` is uses an old version of bootstrap and has not been updated in many years. It shouldn't immediately break but a risk nonetheless. |
There was a problem hiding this comment.
I think that level of pushing bslib is fine.
| } | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
We're going to want a section on caching using bindCache here as well, but happy for that to be a separate PR and to write it.
|
|
||
| For improving your **tables**, check out [this section](../learning-development/r.html#rendering-tables). | ||
|
|
||
| For more advanced shiny knowledge it's worth taking a look at the guide to [engineering production-grade shiny apps](https://engineering-shiny.org/). It's worth reading and considering how much to adopt, remember that just because it sounds clever doesn't make it easy for other analysts to pick up. Read the [Don't sacrifice readability](https://engineering-shiny.org/need-for-optimization.html#dont-sacrifice-readability) section and then work from there. |
There was a problem hiding this comment.
I'm a big fan of the "just because it sounds clever, doesn't make it easy for other analysts to pick up" line. I'd be tempted to add a rephrasing of this right near the start of this page in a call-out box (could be any of note, tip, warning or danger...).
Maybe something along the lines of: "Just because something looks clever, doesn't mean you should do it. Don't over-complicate your user interface or the underlying code. Your priorities should be making something that meets user's needs, whilst also creating something that's manageable for whoever follows you in maintaining your dashboard."
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Overview of changes
This adds more to the Learning R Shiny section.
Why are these changes being made?
As part of work in a Dashboards working group we are looking to promote consistent approaches to R Shiny dashboards across the DfE. This aims to give:
Detailed description of changes
The following changes to writing-visualising/dashboards_rshiny.qmd:
To check:
Issue ticket number/s and link
Issue #112
Checklist before requesting a review