# Meet the Tile

Dashboard Tiles/Notecards are a great way to visualize just one number, and make it big and pretty. They can emphasize results in an easily digestible and colourful format. This package dates back to the days before infoboxes and valueboxes were available from flexdashboard and shinydashboards, and still has some utility today due to it’s flexibility.

This package uses Twitter’s Bootstrap CSS files, and pushes content into buttons that then have different functionality. These buttons are good for embedding in static reports, in Rmd files, and Shiny dashboards. See examples below!

Let’s start small. Note: Please link to References for explanation on full functionality of used tile. (Available if function is underlined/highlighted when hovered over. eg. Hover over ‘solo_box’ below and click. ) Here’s the most basic button:

require(TileMaker) ## to install, use devtools::install_github("DataStrategist/TileMaker")
solo_box(value = 3.3, txt = "Important parameter")
=======

## Overview

Dashboard Tiles, also named Notecards, are a great way to visualize key numbers. They can emphasize results in an easily digestible and colorful format. This package is an alternative to infoboxes and valueboxes available from flexdashboard and shinydashboards.

This package uses Twitter’s Bootstrap CSS files. It pushes the key numbers into buttons using all the functionnality provided by bootstrap. These buttons are good for embedding in static reports, in Rmd files, and Shiny dashboards. See examples below!

## Getting Started

Install the TileMaker package from Github as follows:

# install.packages("TileMaker")
devtools::install_github("DataStrategist/TileMaker")
library(TileMaker)

## Solo Box

The solo_box function allows to create a simple colored box.

solo_box(value = 3.3, txt = "My metric")

The solo_box function only represents one key value. In addition, many feature exist allowing to tune the box entirely.

solo_box(
value = 42, txt = "My metric", former = 99, size = "lg", icon = "check",
type = "warning", link = "https://google.com", units = "kg", hover = "Warning reason", textModifier = "h3"
)

(did you try to hover your mouse over the button?) As you can see, plenty of bells and whistles. Most of the stuff above is pretty intuitive, but let’s explore a bit more, starting with icons (ignore the div_maker for now):

## Icons

div_maker(
subtitle = "One pic is worth a thousand words", textModifier = "h3",
=======
If you rest your mouse over above button, you should see the text “Warning reason” appearing.

Icons
Most of the features above are pretty intuitive. Most favored, icons are also available using Glyphicons.
div_maker(
subtitle = "Icons", textModifier = "h4",
solo_box(value = 3.3, txt = "envelope", icon = "envelope"),
solo_box(value = 3.3, txt = "pushpin", icon = "pushpin"),
solo_box(value = 3.3, txt = "calendar", icon = "calendar")
)

One pic is worth a thousand words
=======
Icons

^ as you can see, we are just using common glyphicons. See the documentation to check your options.
Next, let’s explore the size.

Size
div_maker(
subtitle = "Supersize it!", textModifier = "h3",
=======
Only the name of the icon needs to be supplied, the left hand side of the icon name, “gyphicon-” is automatically managed.
The div_maker functions allows to wrap multiple icons together.

Size
div_maker(
subtitle = "sizes", textModifier = "h4",
solo_box(value = 3.3, txt = "extra small", size = "xs"),
solo_box(value = 3.3, txt = "small", size = "sm"),
solo_box(value = 3.3, txt = "medium", size = "md"),
solo_box(value = 3.3, txt = "large", size = "lg")
)

Supersize it!
=======
sizes

And the type, which dictates the color using the css classes (watch the case sensitivity here!).

Color
div_maker(
subtitle = "... all the colors of a rainbow", textModifier = "h3",
=======

Color
The type argument controls the type of box and dictates the color.
By default, Bootstrap Version 3 is used. 6 types of boxes are available. It can be customised to use boostrap 4.
div_maker(
subtitle = "colors", textModifier = "h4",
solo_box(value = 3.3, txt = "Default", type = "default"),
solo_box(value = 3.3, txt = "Primary", type = "primary"),
solo_box(value = 3.3, txt = "Success", type = "success"),
solo_box(value = 3.3, txt = "Info", type = "info"),
solo_box(value = 3.3, txt = "Warning", type = "warning"),
solo_box(value = 3.3, txt = "Danger", type = "danger")
)

... all the colors of a rainbow
=======
colors

The solo_gradient box automatically changes colors from red to yellow to green based on a target and some thresholds. By default, the target is set to 100 and the thresholds are set to 50 and 90, but obviously those are customizeable.
=======

The solo_gradient_box function allows to automatically pick colors among classic traffic light colors, green-orange-red, and some thresholds. By default, the target is set to 100 and thresholds are set to 50 and 90.
div_maker(
subtitle = "Available gradients", textModifier = "h4",
)

By default, the value is used as the target. It is possible to compare the value to a target using the target argument. The color is then determined by comparing target / value to the thresholds.
div_maker(
subtitle = "Playing with the thresholds", textModifier = "h4",
)

Playing with the thresholds

Arguments thresholdHigh and thresholdLow allow to customise the thresholds.
solo_gradient_box(value = 46, txt = "Customized target<br>and threshold", target = 50, thresholdHigh = 93)

You can see that the box changes to orange since it’s now between thresholdHigh and thresholdLow.
The <br> element above forces a line break. Text accepts full html code, natively written.

The multi_box, in contrast to the solo_box, takes multiple values in one button, providing an easy way to summarize a ton of information in one button.
=======

Multi Box
The multi_box function takes multiple values in one button, providing an easy way to summarize a ton of information in one button.
multi_box(values = c(4, 5, 6), txt = c("Sally", "George", "Mohammed"), icons = c("check", "plus", "calendar"), title = "Candidates")

Last but not least, here’s the tile_matrix
=======

Tile Matrix
The tile_matrix function creates several new solo_gradient_boxes and compiles them all into a grid.
suppressPackageStartupMessages(library(dplyr))
#> Warning: package 'dplyr' was built under R version 3.5.2

df <- data_frame(
values = c(2, 5, 6),
txt = c("Sally", "George", "Mohammed")
)
#> Warning: data_frame() is deprecated, use tibble().
#> This warning is displayed once per session.
tile_matrix(df, values = values, txt = txt, target = 10, thresholdHigh = 60, thresholdLow = 40, textModifier = "h2")

The function takes a dataframe as first value and as such can be used in a tidyverse pipe.
Example:
mtcars %>%
# name of car model is contained in the rowname
mutate(names = rownames(.)) %>%
tile_matrix(
values = "disp", txt = "names",
target = 500, thresholdHigh = 80, thresholdLow = 50
)

The concept of the tile_matrix is to provide a quick way to visualize simple informations. The fact that the thresholds scale automatically to the target is useful, since one need only set the target in order to quickly obtain actionable information.
For example, if one wanted to quickly see diamond prices:
library(ggplot2)
#> Warning: package 'ggplot2' was built under R version 3.5.2
diamonds %>%
group_by(color) %>%
summarize(price = mean(price)) %>%
## Assume there was some former price that was a bit different
mutate(old_price = price * (1 * runif(n = 7, min = -.2, max = .5))) %>%
tile_matrix(data = ., values = price, txt = color, former = old_price, target = 5000, roundVal = 0)

So we’ve seen this former value a few times now, but what does it do? Simply put it contextualizes the displayed value in comparision with a former value. This is especially useful to measure performance increase or declines. In order to show the functionality, let’s use a quite contrived scenario:
suppressPackageStartupMessages(library(dplyr))
df <- data_frame(
values = seq(from = 0, to = 100, by = 10),
txt = "comparison to 50",
former = 50
)

## Let's pretend that all previous values were 50... so:
tile_matrix(data = df, values = values, txt = txt, former = former)

Grammar of tile_maker
Buttons are put into a div (which is more or less an html “row”… kinda). And these divs are put into a finalizer.
=======
The former argument contextualizes the displayed value in comparison with a former value. This is especially useful to measure growth of a metric.

Grammar of tile_maker
Buttons are put into a div tag and final values are put into a finalizer.
Value1 <- 88
Value2 <- 1985
Value3 <- 1.22
Value4 <- 30
Value5 <- 42

## Make the buttons how you like
Button1 <- solo_box(value = Value1, txt = "Speed", units = "mph", type = "danger")
Button2 <- solo_box(value = Value2, txt = "Origin", type = "warning", icon = "flash")
value = Value3, txt = "Powah", units = "GW", hover = "Great Scott!",
target = 1.22, thresholdHigh = 100, thresholdLow = 99
)
Button4 <- solo_box(value = Value4, txt = "Heads turned", units = "K", type = "info")
Button5 <- solo_box(
value = Value5, txt = "Answer", hover = "Whales rule. Petunias suck",
link = "https://en.wikipedia.org/wiki/The_Hitchhiker%27s_Guide_to_the_Galaxy", type = "primary"
)

## Combine in 2 rows:
Div1 <- div_maker(subtitle = "Future", textModifier = "h2", Button1, Button2, Button3)
Div2 <- div_maker(subtitle = "Effect", textModifier = "h2", Button4, Button5)

## Now put them all together:
finisher(
title = "Important block", css = "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css",
file = NULL, textModifier = "h1", div_maker(subtitle = "Boom", textModifier = "hi",Div1, Div2)
)

Important block

Boom
Future

Effect

These functions are included to help with inclusion in different document types and for testing small snipets of code.

It’s not working / you broke my entire report / help
So let’s be very clear… this is a hack, might even be an ugly hack. I’m controlling how these elements work by porting and controlling the HTML element within. Sometimes that makes a mess out of the document you’re preparing. Towhit, I have included a few features:
=======

Bug Report / help
HTML elements within tile_maker blocks have a fixed css controlled by the functions. It may affect others elements of your webpage.
The tilemaker package work by porting bootstrap functionnality and controlling the HTML element within. It may affect others elements of your webpage.
A few features are included to try to prevent these effects:

Most of the time, wrapping your buttons or groups of buttons in div_makers, and/or in finishers… seems to fix issues most of the time.
In some cases, for example in markdown documents that include a Table of Contents, format depends of previous html elements. It is advised to then use the textModifier option. You can change the textModifier from the default h1 to h4 or <br> or anything you think might work in your report.

Contents

Meet the Tile
Icons
Size
Color

Last but not least, here’s the tile_matrix
=======
Overview
Getting Started
Solo Box
Multi Box
Tile Matrix
Grammar of tile_maker
Bug Report / help

Developed by Amit Kohli.

Site built with pkgdown 1.3.0.