-
Notifications
You must be signed in to change notification settings - Fork 1
/
12-staticImages.Rmd
executable file
·160 lines (113 loc) · 10.1 KB
/
12-staticImages.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# Static Images {#staticImages}
Static image refers to any image you're using in your App which is not produced by `R`. These are usually PNG or JPG/JPEG files which you end up calling in the UI portion of your code.
Within your App's folder/directory, there needs to be a sub-folder/directory called `www`. This is the place where you'll need to place ALL static image files.
## Adding an Image
To include the image in your App, you'll need to make use of the image tag, `img`. When you run your App, Shiny automatically knows to check the `www` folder any time the `img` tag gets called.
There are two main ways to add a static image: through a Figure Environment and In Line.
### Figure Environment {#figEnv}
This is our __preferred method__ for adding static images to a shiny app. Here is example code for adding an image within a figure environment:
```{r imageEx1, echo=TRUE, eval=FALSE}
#[code omitted]
tags$figure(
class = "centerFigure",
tags$img(
src = "astragalus.jpg",
width = 600,
alt = "Picture of an astragalus (bone die)"
),
tags$figcaption("Image of Astragalus by Yaan, 2007")
)
#[code omitted]
```
In this first example, we've created a figure environment with the `tags$figure` call. The `centerFigure` class (the first argument) will center your figure appropriately on the page.
The second part of the figure is the actual call to load the static image; `tags$img`. Much like the heading and paragraph HTML tags, you can omit `tags$` in this case. However, it doesn't hurt to be cautious, hence why we've left this in our code. You will need to provide at least two arguments (`src` and `alt`) to this call. The `src` ("source") refers to what file the image is in you want; the value of this argument should be file name of the image located in the `www` folder. The `alt` argument refers to the [Alt Text](#altStatic) for the image.
The other argument (`width`) is one of two sizing arguments (along with `height`) that you can set to alter the size of your figure. Check out the [Sizing Section](#imageSize) section below.
The last portion of the figure environment is the `tags$figcaption`. The figure caption is an opportunity to give a bit of information about the figure AND provide any credit. In our example, we've mentioned what the image is a picture of (an astragalus) as well as citing who the image belongs to (Yaan). Figure captions do not replace Alt Text and Alt Text does not replace figure captions; these are both complementary and distinct elements of static images.
### In Line Images
In a rare case when you need to place an image inside of a line of text, you can use code similar to the following:
```{r imageEx2, echo=TRUE, eval=FALSE}
#[code omitted]
p("Check your answer here -->",
tags$img(
src = "check.PNG",
alt = "Success, you are correct",
width = 25,
height = 25
),
"<-- Check your answer here"
),
#[code omitted]
```
Notice that here we did not use either `tags$figure` nor `tags$figcaption`, rather we just used `tags$img` within a paragraph environment. The biggest caution we need to give here is to make sure you find an optimal size for your image.
## Sizing Your Image {#imageSize}
All image files have a native size that is part of that file. For instance, the check mark image is 270 x 250 pixels. However, we overrode that that sizing with the `width` and `height` arguments.
We recommend that you test out your app with the image's natural sizing (i.e., omit both `width` and `height` arguments) and see how that looks. From there, you can start a the testing process. Except in a few cases (like our checkmark example above), you will only want to set either `width` or `height` but not both. This will allow each user's browser to optimize the resolution of the image so that the image does not appear unduly stretched or compressed. Generally, go with changing the `width` argument.
How did we decide on what size to use? We tested out various sizes until we found one that appeared to work well with our goals (i.e., not too large, not too small, but just right). This Goldilocks Zone of image size will change between every app as well as for different images within the same app. Try different sizes out and ask for specific feedback on image sizes. While finding an optimal size and position for your image can take some time, seeing bad settings is pretty obvious. Feel free to reach out to Neil and Bob for assistance.
## Adding Alt Text to Static Images {#altStatic}
Any graphical element you include in your App __MUST__ have an alternative (assistive) text description ("alt text"). This provides a short description of what is in the image or plot for users who are visual impaired. (Tables, when properly formatted will handle this automatically.)
Here are several resources worth checking out:
+ [WebAIM Alternative Text Guide](https://webaim.org/techniques/alttext/#basics)
+ [Penn State's Image ALT Text Page](https://accessibility.psu.edu/images/alttext/)
+ [W3C's ALT Text Decision Tree](https://www.w3.org/WAI/tutorials/images/decision-tree/)
In the prior section on static images, you saw exactly how to set the alt text; here is a generic example:
```{r altText1, echo=TRUE, eval=FALSE}
#[code omitted]
img(
src = "yourImage.PNG",
alt = "Short description of what's in the pic",
width = 25, height = 25
)
#[code omitted]
```
You MUST include *descriptive* alt text to each and every static image you include.
## Getty Images
A common/popular source of images online is [Getty Images](https://www.gettyimages.com/). As a general rule, Getty Images do require licensing to use. However, they do provide a way to use their images in non-commercial sites (like our apps). To do this, we need to embed the image within the app.
### Finding the Image
To get started, you'll need to search the Getty Images site, for the topic you're wanting to get an image of and specify that results should be restricted to embeddable images. The easiest way to do this is to use the search bar on [Getty Image's Embed page](https://www.gettyimages.com/resources/embed). Using this search bar will automatically ensure that the image can be used.
Once you select the image you want to use, click on the image in the search results to open the image up. Just below the image you'll find a set of four buttons with the leftmost saying "Embed". Click this button. A popup window will appear titled "Embed an image or slideshow" with a field showing code below. Make sure that the field is set to "Standard code" and then copy __all__ of the code text. You should end up with something like the following:
`<a id='rK3nO0ArRmNenhcm-f1w8Q' class='gie-single' href='http://www.gettyimages.com/detail/1165647019' target='_blank' style='color:#a7a7a7;text-decoration:none;font-weight:normal !important;border:none;display:inline-block;'>Embed from Getty Images</a><script>window.gie=window.gie||function(c){(gie.q=gie.q||[]).push(c)};gie(function(){gie.widgets.load({id:'rK3nO0ArRmNenhcm-f1w8Q',sig:'3eV7zRFdjS-0p2iNm4tob-3E1tRfxfCNjaXnJgiMueo=',w:'525px',h:'328px',items:'1165647019',caption: true ,tld:'com',is360: false })});</script><script src='//embed-cdn.gettyimages.com/widgets.js' charset='utf-8' async></script>`
### Placing in Your App
Once you have the embed code, you can go into your app. You will need to use the [figure environment](#figEnv) with a some modifications.
```{r imgEx3, echo=TRUE, eval=FALSE}
# Getty Images Example
#[code omitted]
tags$figure(
class = "centerGettyImage",
HTML("<a id='rK3nO0ArRmNenhcm-f1w8Q' class='gie-single'
href='http://www.gettyimages.com/detail/1165647019' target='_blank'
style='color:#a7a7a7;text-decoration:none;font-weight:normal
!important;border:none;display:inline-block;'>Embed from Getty
Images</a>
<script>window.gie=window.gie||function(c){(gie.q=gie.q||[]).push(c)};
gie(function(){gie.widgets.load({id:'rK3nO0ArRmNenhcm-f1w8Q',
sig:'3eV7zRFdjS-0p2iNm4tob-3E1tRfxfCNjaXnJgiMueo=',w:'525px',h:'328px',
items:'1165647019',caption: true ,tld:'com',is360: false })});</script>
<script src='//embed-cdn.gettyimages.com/widgets.js' charset='utf-8' async></script>"),
tags$figcaption("Rolling Two Dice")
)
#[code omitted]
```
The two key modifications are:
+ Use the `centerGettyImage` class instead of `centerFigure`
+ Replace the `tags$img` command with the `HTML` command.
Within the `HTML` command you'll need to put a set of double quotation marks and then paste the embed code you copied from Getty Images. Be sure that you have the close double quotation marks and the close parenthesis for the `HTML` command. While you'll still need to provide a figure caption (via `tags$figcaption`), you will not need to provide an alt text argument. (Getty Images has provided alt text as part of their embedding process.)
By following the process, you should end up with the Getty Image you want to use in your app, much like the example below. It is important to keep in mind that when you embed an image in your app, it will take a few moments for your app to load the image. Thus, try to see if there are other freely available images that we can use instead.
```{css gettyStyle, echo=FALSE}
.centerGettyImage{
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
}
.centerGettyImage a{
color: #000000 !important;
font-family: 'Open Sans', -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif, "Segoe UI Symbol";
font-weight: 400;
font-size: 1rem;
line-height: 1.5rem;
}
```
<figure class = "centerGettyImage">
<a id='rK3nO0ArRmNenhcm-f1w8Q' class='gie-single' href='http://www.gettyimages.com/detail/1165647019' target='_blank' style='color:#a7a7a7;text-decoration:none;font-weight:normal !important;border:none;display:inline-block;'>Embed from Getty Images</a><script>window.gie=window.gie||function(c){(gie.q=gie.q||[]).push(c)};gie(function(){gie.widgets.load({id:'rK3nO0ArRmNenhcm-f1w8Q',sig:'3eV7zRFdjS-0p2iNm4tob-3E1tRfxfCNjaXnJgiMueo=',w:'525px',h:'328px',items:'1165647019',caption: true ,tld:'com',is360: false })});</script><script src='//embed-cdn.gettyimages.com/widgets.js' charset='utf-8' async></script>
<figcaption>Rolling Two Dice</figcaption>
</figure>