From 00fa782c274200533ef44e3fdada0b508d9af2a8 Mon Sep 17 00:00:00 2001
From: Yihui Xie <xie@yihui.name>
Date: Tue, 22 Oct 2013 12:14:56 -0500
Subject: [PATCH] documentation of datatables in the tutorial (#279)

---
 _includes/tutorial/datatables.md | 130 +++++++++++++++++++++++++++++++
 tutorial/index.html              |  11 +++
 2 files changed, 141 insertions(+)
 create mode 100644 _includes/tutorial/datatables.md

diff --git a/_includes/tutorial/datatables.md b/_includes/tutorial/datatables.md
new file mode 100644
index 000000000..95e3ce80d
--- /dev/null
+++ b/_includes/tutorial/datatables.md
@@ -0,0 +1,130 @@
+
+
+![DataTables Screenshot](http://i.imgur.com/06A0HDM.png)
+
+### Basic Usage
+
+The [DataTables application](http://glimmer.rstudio.com/yihui/12_datatables/)
+demonstrates HTML tables using the jQuery library
+[DataTables](http://datatables.net). To run the example type:
+
+{% highlight r %}
+library(shiny)
+runGitHub("shiny-examples", "rstudio", subdir = "12_datatables")
+{% endhighlight %}
+
+The basic usage is to create an output element in the UI using
+`dataTableOutput(id = 'foo')`, and render a table using `output$foo <-
+renderDataTable({ data })` in the server script. Normally `renderDataTable()` takes
+an expression that returns a rectangular data object with column names, such
+as a data frame or a matrix. Below is a minimal example:
+
+{% highlight r %}
+library(shiny)
+
+runApp(list(
+  ui = basicPage(
+    h2('The mtcars data'),
+    dataTableOutput('mytable')
+  ),
+  server = function(input, output) {
+    output$mytable = renderDataTable({
+      mtcars
+    })
+  }
+))
+{% endhighlight %}
+
+By default, the data is paginated, showing 25 rows per page. The number of
+rows to display can be changed through the drop down menu in the top-left.
+We can sort the columns by clicking on the column headers, and sort multiple
+columns by holding the `Shift` key while clicking (the sorting direction
+loops through `ascending`, `descending`, and `none` if we keep on clicking).
+We can search globally in the table using the text input box in the
+top-right, or search individual columns using the text boxes at the bottom.
+Currently the searching terms are treated as regular expressions in R. Since
+searching can be time-consuming in large datasets, there is a delay of 0.5
+seconds (customizable) before searching is really processed; that means if
+we type fast enough in the search box, searching may be processed only once
+on the server side even if we have typed more than one character.
+
+### Customizing DataTables
+
+There are a large number of options in DataTables that are customizable (see
+its website for details). In [this
+example](http://glimmer.rstudio.com/yihui/12_datatables/), we show a few
+possibilities. First, we create the UI to display three datasets `diamonds`,
+`mtcars`, and `iris`, with each dataset in its own tab:
+
+#### ui.R
+
+{% highlight r %}
+library(shiny)
+library(ggplot2)  # for the diamonds dataset
+
+shinyUI(pageWithSidebar(
+  headerPanel('Examples of DataTables'),
+  sidebarPanel(
+    checkboxGroupInput('show_vars', 'Columns in diamonds to show:', names(diamonds),
+                       selected = names(diamonds)),
+    helpText('For the diamonds data, we can select variables to show in the table;
+             for the mtcars example, we use bSortClasses = TRUE so that sorted
+             columns are colored since they have special CSS classes attached;
+             for the iris data, we customize the length menu so we can display 5
+             rows per page.')
+  ),
+  mainPanel(
+    tabsetPanel(
+      tabPanel('diamonds',
+               dataTableOutput("mytable1")),
+      tabPanel('mtcars',
+               dataTableOutput("mytable2")),
+      tabPanel('iris',
+               dataTableOutput("mytable3"))
+    )
+  )
+))
+{% endhighlight %}
+
+We also added a checkbox group to select the columns to show in the
+`diamonds` data.
+
+### Server Script
+
+The `options` argument in `renderDataTable()` can take a list (literally an
+R list) of options, and pass them to DataTables when the table is
+initialized. For example, for the `mtcars` data, we pass `bSortClasses =
+TRUE` to DataTables so that the sorted columns will have CSS classes
+attached on them (this is disabled by default); in this example, we can see
+the sorted columns are highlighted by darker colors. For the `iris` data, we
+pass the options `aLengthMenu` and `iDisplayLength` to customize the drop
+down menu, which has items `[10, 25, 50, 100]` by default; now the menu has
+three items `[5, 30, 50]`, and `5` is selected as the default value.
+
+#### server.R
+
+{% highlight r %}
+library(shiny)
+
+shinyServer(function(input, output) {
+
+  # a large table, reative to input$show_vars
+  output$mytable1 = renderDataTable({
+    library(ggplot2)
+    diamonds[, input$show_vars, drop = FALSE]
+  })
+
+  # sorted columns are colored now because CSS are attached to them
+  output$mytable2 = renderDataTable({
+    mtcars
+  }, options = list(bSortClasses = TRUE))
+
+  # customize the length drop-down menu; display 5 rows per page by default
+  output$mytable3 = renderDataTable({
+    iris
+  }, options = list(aLengthMenu = c(5, 30, 50), iDisplayLength = 5))
+
+})
+{% endhighlight %}
+
+For more DataTable options, please refer to its full reference on its website.
diff --git a/tutorial/index.html b/tutorial/index.html
index 7c68c7352..f41616de2 100644
--- a/tutorial/index.html
+++ b/tutorial/index.html
@@ -170,6 +170,9 @@ hljs.initHighlightingOnLoad();
    <li>
       <a target="_self" href="#tabsets">Tabsets</a>
    </li>
+   <li>
+      <a target="_self" href="#datatables">DataTables</a>
+   </li>
    <li>
       <a target="_self" href="#more-widgets">More Widgets</a>
    </li>
@@ -305,6 +308,14 @@ hljs.initHighlightingOnLoad();
 {% capture tabsets %}{% include tutorial/tabsets.md %}{% endcapture %}
 {{ tabsets | markdownify }}
 
+</div>
+
+
+<!-- Tabsets -->
+<div class="tab-pane" id="datatables">
+
+{% capture datatables %}{% include tutorial/datatables.md %}{% endcapture %}
+{{ datatables | markdownify }}
 
 </div>