|
| 1 | +--- |
| 2 | +title: "Dash HTML Components" |
| 3 | +output: rmarkdown::html_vignette |
| 4 | +vignette: > |
| 5 | + %\VignetteIndexEntry{Dash HTML Components} |
| 6 | + %\VignetteEngine{knitr::knitr} |
| 7 | + %\usepackage[UTF-8]{inputenc} |
| 8 | +--- |
| 9 | + |
| 10 | +Dash is a web application framework that provides pure R and Python abstraction around HTML, CSS, and JavaScript. Instead of writing HTML or using an HTML templating engine, you compose your layout using R functions within the `dashHtmlComponents` package. The source is on GitHub at [plotly/dash-html-components](https://github.com/plotly/dash-html-components). |
| 11 | + |
| 12 | +Please visit our online documentation, which is interactive and frequently updated: https://dashr.plot.ly. |
| 13 | + |
| 14 | +The components in this package are all simple wrappers for HTML5 elements. Extensive documentation for these elements is available online: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ |
| 15 | + |
| 16 | +Here is an example of a simple HTML structure: |
| 17 | + |
| 18 | +```r |
| 19 | +library(dashHtmlComponents) |
| 20 | +library(dash) |
| 21 | + |
| 22 | +htmlDiv(list( |
| 23 | + htmlH1('Hello Dash'), |
| 24 | + htmlDiv(list( |
| 25 | + htmlP('Dash converts R classes into HTML'), |
| 26 | + htmlP("This conversion happens behind the scenes by Dash's JavaScript front-end") |
| 27 | + )) |
| 28 | +)) |
| 29 | +``` |
| 30 | + |
| 31 | +which gets converted (behind the scenes) into the following HTML in your web application: |
| 32 | + |
| 33 | +```html |
| 34 | +<div> |
| 35 | + <h1>Hello Dash</h1> |
| 36 | + <div> |
| 37 | + <p>Dash converts Python classes into HTML</p> |
| 38 | + <p>This conversion happens behind the scenes by Dash's JavaScript front-end</p> |
| 39 | + </div> |
| 40 | +</div> |
| 41 | +``` |
| 42 | + |
| 43 | +If you're not comfortable with HTML, don't worry! You can get 95% of the way there with just a few elements and attributes. Dash's core component library also supports [Markdown](https://daringfireball.net/projects/markdown/). |
| 44 | + |
| 45 | +```r |
| 46 | +library(dashHtmlComponents) |
| 47 | +library(dash) |
| 48 | +dccMarkdown(''' |
| 49 | +#### Dash and Markdown |
| 50 | +Dash supports [Markdown](https://daringfireball.net/projects/markdown/). |
| 51 | +Markdown is a simple way to write and format text. |
| 52 | +It includes a syntax for things like **bold text** and *italics*, |
| 53 | +[links](https://daringfireball.net/projects/markdown/), inline `code` snippets, lists, |
| 54 | +quotes, and more. |
| 55 | +''') |
| 56 | +``` |
| 57 | + |
| 58 | +which renders the following: |
| 59 | + |
| 60 | +> #### Dash and Markdown |
| 61 | +Dash supports [Markdown](https://daringfireball.net/projects/markdown/) Markdown is a simple way to write and format text. It includes a syntax for things like **bold text** and *italics*, [links](https://daringfireball.net/projects/markdown/), inline `code` snippets, lists, quotes, and more. |
| 62 | + |
| 63 | +If you're using HTML components, then you also have access to properties like `style`, `class`, and `id`. |
| 64 | + |
| 65 | +All of these attributes are available in the R functions. The HTML elements and Dash classes are mostly the same but there are a few key differences: |
| 66 | + |
| 67 | +* The `style` property is a named list |
| 68 | +* Properties in the `style` dictionary are camelCased |
| 69 | +* The class key is renamed as `className` |
| 70 | +* Style properties in pixel units can be supplied as just numbers without the `px` unit |
| 71 | + |
| 72 | +Let's take a look at an example. |
| 73 | + |
| 74 | +```r |
| 75 | +library(dashHtmlComponents) |
| 76 | +library(dash) |
| 77 | +htmlDiv(list( |
| 78 | + htmlDiv('Example Div', style=list('color' = 'blue', 'fontSize' = 14)), |
| 79 | + htmlP('Example P', className='my-class', id='my-p-element') |
| 80 | +), style=list('marginBottom' = 50, 'marginTop' = 25)) |
| 81 | +``` |
| 82 | + |
| 83 | +That Dash code will render this HTML markup: |
| 84 | + |
| 85 | +```html |
| 86 | +<div style="margin-bottom: 50px; margin-top: 25px;"> |
| 87 | + |
| 88 | + <div style="color: blue; font-size: 14px"> |
| 89 | + Example Div |
| 90 | + </div> |
| 91 | + |
| 92 | + <p class="my-class", id="my-p-element"> |
| 93 | + Example P |
| 94 | + </p> |
| 95 | +</div> |
| 96 | +``` |
0 commit comments