dev— title: “Basic how to package” author: “Jonas Vaclavek” date: “2019-06-15” output: rmarkdown::html_vignette vignette: > % % % —

While developing web applications, CSS is used to style web application’s web pages. The CSS is often written using CSS preprocessor such as SASS or LESS.

rless is a package, which helps to convert LESS files to CSS files within R environment.

This documentation is divided into three sections:

rless functions

parse_less

The parse_less function is a core function of the package. It takes LESS content and converts it to CSS.

library(rless)

less <- "
@width: 10px;
@height: @width + 10px;

#header {
  width: @width;
  height: @height;
}
"

css <- parse_less(less)
cat(css)
#> #header {
#>   width: 10px;
#>   height: 20px;
#> }

convert_file

Passing text into parse_less function is suitable for small chunks. However, for more complex codes, it is more convenient to write LESS file separately and convert the file using convert_file function. It requires two parameters:

  • file name
  • path to the file (both relative and absolute are supported)

The converted file will be stored in tempdir folder or use output_folder argument to set different output location.

The function returns full path to the converted.

less_file <- file.path("path", "to", "styles.less")
convert_file(dirname(less_file), basename(less_file), getwd())

convert_folder

When having multiple LESS files, one can use rless function convert_folder. The function requires only input folder to be specified. It goes through the folder and converts all files matching a pattern (*.less by default) into CSS files. tempdir folder is used again as a default output location.

The function allows to specify optional argument:

  • output_folder - folder, where converted files will be places
  • recursive - whether to scan for files in nested folders
  • pattern - file name pattern used to select files to convert
styles_folder <- file.path("path", "to", "styles", "folder")

paths_to_files <- convert_folder(styles_folder)

# set different output folder
paths_to_files <- convert_folder(styles_folder, output_folder = getwd())

# convert also files in file.path(styles_folder, "nested_folder", "even_more_nested_folder")
paths_to_files <- convert_folder(styles_folder, recursive = TRUE)

# convert only files with filename ending with 'styles.less'
paths_to_files <- convert_folder(styles_folder, pattern = "^*.styles.less$")

List of paths to converted files is returned.

LESS

The following sections introduce the basic concepts of LESS with a use of rless function parse_less. More information about LESS features can be found here.

Variables

Use variables at multiple places in your LESS/CSS.

library(rless)

less <- "
@width: 10px;
@height: @width + 10px;

#header {
  width: @width;
  height: @height;
}

#footer{
  width: @width;
  height: @height;
}
"

css <- parse_less(less)
cat(css)
#> #header {
#>   width: 10px;
#>   height: 20px;
#> }
#> #footer {
#>   width: 10px;
#>   height: 20px;
#> }

Nesting and parent selector

Basic nesting of CSS selectors

less <- "
ul {
  li {
    color: cyan;
  }  
}
"

css <- parse_less(less)
cat(css)
#> ul li {
#>   color: cyan;
#> }

Nesting with reference to parent.

less <- "
.button {
  &-ok {
    background-color: green;
  }
  && {
    backgrou-color: transparent;
  }
}
"

css <- parse_less(less)
cat(css)
#> .button-ok {
#>   background-color: green;
#> }
#> .button.button {
#>   backgrou-color: transparent;
#> }

Mixins

Combine chunks of CSS using mixins.

less <- "
.bordered {
  border-top: dotted 1px black;
  border-bottom: solid 2px black;
}

#menu a {
  color: #111;
  .bordered();
}

.post a {
  color: red;
  .bordered();
}
"

css <- parse_less(less)
cat(css)
#> .bordered {
#>   border-top: dotted 1px black;
#>   border-bottom: solid 2px black;
#> }
#> #menu a {
#>   color: #111;
#>   border-top: dotted 1px black;
#>   border-bottom: solid 2px black;
#> }
#> .post a {
#>   color: red;
#>   border-top: dotted 1px black;
#>   border-bottom: solid 2px black;
#> }

Using in Shiny apps

One of the typical ways of creating web applications in R is using Shiny. This sections shows how easy is to combine it with our rless package.

Single LESS file

# global.R
convert_file(getwd(), "styles.less", "www")

# ui.R
shinyUI(
  fluidPage(
    tags$head(
      tags$link(rel = "stylesheet", type = "text/css", href = "styles.css")
    )
  )
)

Multiple LESS files

# ui.R
shinyUI(
  fluidPage(
    lapply(convert_folder(input_folder, output_folder), includeCSS)
  )
)