Урок 3. Добавляем виджеты

Перевод-пересказ руководства.

Этот урок покажет вам как добавлять виджеты (widget) в своё Shiny-приложение. Что такое виджет (элемент управления)? Это элемент интерфейса приложения (например, кнопка) с которым может взаимодействовать пользователь. Виджеты позволяют пользователям отправлять сообщения приложению.

Виджеты Shiny получают от пользователя некоторые значения. Когда пользователь изменяет виджет (например, выбирает пункт списка), изменяется и значение, передаваемое виджетом приложению. Возможности "научить" приложение реагировать на изменения значений виджетов будут рассмотрены на Уроке 4.

Основные виджеты

В Shiny поставляется с набором встроенных виджетов, каждый из которых создается с помощью соответствующим образом названной функции R. Например, в Shiny есть функция actionButton, которая создает кнопку (action button) и функция, названная sliderInput, которая создает ползунок (slider bar).

Вот стандартные виджеты Shiny:

функция	виджет
actionButton	Action Button
checkboxGroupInput	A group of check boxes
checkboxInput	A single check box
dateInput	A calendar to aid date selection
dateRangeInput	A pair of calendars for selecting a date range
fileInput	A file upload control wizard
helpText	Help text that can be added to an input form
numericInput	A field to enter numbers
radioButtons	A set of radio buttons
selectInput	A box with choices to select from
sliderInput	A slider bar
submitButton	A submit button
textInput	A field to enter text

Некоторые из этих виджетов построены с использованием проекта Twitter Bootstrap — популярной открытой библиотеки для создания пользовательских интерфейсов.

Добавление виджетов

Вы можете добавить виджет на вашу веб-страницу тем же способом, каким добавляли разметку HTML на Уроке 2. Чтобы добавить виджет в приложение, поместите функцию, отвечающую за создание виджета, внутрь sidebarPanel или mainPanel в файле ui.R.

У каждой функции, реализующей виджет, есть несколько аргументов. Первые два аргумента для любого виджета это:

имя виджета. Пользователь его не увидит, но имя можно использовать для доступа к значению (value) виджета. Имя должно быть текстовой строкой;
метка. Метка (label) появится в приложении вместе с виджетом. Это должна быть текстовая строка, которая может быть пустой ("").

В следующем примере имя виджета — "action", а метка — "Action":

actionButton("action", label = "Action")

Остальные аргументы могут отличаться от виджета к виджету, в зависимости от того, какие операции он выполняет. Это могут быть входные данные, необходимые для работы виджета: отдельные значения, диапазоны значений (минимум, максимум), величины приращений и т.п. Полный список аргументов необходимых тому или иному виджету вы можете найти на странице справки по соответствующей функции виджета (например, ?selectInput — команда вызова справки по функции selectInput).

Скрипт ui.R, размещённый ниже, создает приложение, показанное на картинке вверху. Измените соответствующим образом файл ui.R своего приложения App-1, а затем запустите приложение.

Поиграйте с каждым виджетом, чтобы понять, что он делает. Экспериментируйте, изменяя значения функций виджета, и посмотрите к каким эффектам это приведёт. Если вас заинтересовала компоновка (макет) этого приложения, то прочитать о том как создать нечто подобное можно в application layout guide. На этом уроке мы будем использовать более простые макеты, но это не значит что возможности Shiny ими ограничиваются.

# ui.R

shinyUI(fluidPage(
  titlePanel("Basic widgets"),

  fluidRow(

    column(3,
      h3("Buttons"),
      actionButton("action", label = "Action"),
      br(),
      br(), 
      submitButton("Submit")),

    column(3,
      h3("Single checkbox"),
      checkboxInput("checkbox", label = "Choice A", value = TRUE)),

    column(3, 
      checkboxGroupInput("checkGroup", 
        label = h3("Checkbox group"), 
        choices = list("Choice 1" = 1, 
           "Choice 2" = 2, "Choice 3" = 3),
        selected = 1)),

    column(3, 
      dateInput("date", 
        label = h3("Date input"), 
        value = "2014-01-01"))   
  ),

  fluidRow(

    column(3,
      dateRangeInput("dates", label = h3("Date range"))),

    column(3,
      fileInput("file", label = h3("File input"))),

    column(3, 
      h3("Help text"),
      helpText("Note: help text isn't a true widget,", 
        "but it provides an easy way to add text to",
        "accompany other widgets.")),

    column(3, 
      numericInput("num", 
        label = h3("Numeric input"), 
        value = 1))   
  ),

  fluidRow(

    column(3,
      radioButtons("radio", label = h3("Radio buttons"),
        choices = list("Choice 1" = 1, "Choice 2" = 2,
                       "Choice 3" = 3),selected = 1)),

    column(3,
      selectInput("select", label = h3("Select box"), 
        choices = list("Choice 1" = 1, "Choice 2" = 2,
                       "Choice 3" = 3), selected = 1)),

    column(3, 
      sliderInput("slider1", label = h3("Sliders"),
        min = 0, max = 100, value = 50),
      sliderInput("slider2", "",
        min = 0, max = 100, value = c(25, 75))
      ),

    column(3, 
      textInput("text", label = h3("Text input"), 
        value = "Enter text..."))   
  )

))

Ваша очередь

Перепишите ваш скрипт ui.R так, чтобы создать пользовательский интерфейс, показанный на рисунке ниже. Обратите внимание, что это приложение Shiny использует базовый макет (без колонок) и содержит три виджета, показанных в примере выше. Значения элементов выпадающего списка показаны на нижнем рисунке.

Ответы

Перед тем как двигаться дальше, убедитесь, что ваш скрипт идентичен приведенному ниже. Мы бум использовать этот скрипт на Уроке 4 и Уроке 5, как часть приложения, отображающего результаты переписи.

В частности, убедитесь, что виджет списка (select box) имеет имя "var", а ползунок (slider) — "range".

И, наконец, проверьте, что ползунок имеет два значения, а не одно.

# ui.R

shinyUI(fluidPage(
  titlePanel("censusVis"),

  sidebarLayout(
    sidebarPanel(
      helpText("Create demographic maps with 
        information from the 2010 US Census."),

      selectInput("var", 
        label = "Choose a variable to display",
        choices = list("Percent White", "Percent Black",
          "Percent Hispanic", "Percent Asian"),
        selected = "Percent White"),

      sliderInput("range", 
        label = "Range of interest:",
        min = 0, max = 100, value = c(0, 100))
    ),

    mainPanel()
  )
))

Резюме

Добавлять полностью готовые к работе виджеты в приложения Shiny очень просто.

Shiny содержит набор функций для создания этих виджетов.
Каждому виджету нужно указать имя и метку.
Некоторые функции требуют дополнительных значений для своей работы.
Вы добавляете виджеты в свое приложение так же, как добавляли различный HTML-контент (см. Урок 2).

Идём дальше

В Галерее виджетов Shiny показано множество шаблонов, которые вы можете использовать в своих приложениях.

Чтобы использовать шаблон, посетите галерею. В ней показан каждый виджет Shiny и то, как изменяются значения виджетов в ответ на изменение входных данных.

Выберите виджет и нажмите кнопку "See Code", расположенную под виджетом. Галерея даёт возможность изучить полноценный пример использования того или иного виджета. Для того чтобы использовать виджет, скопируйте и вставьте нужный код из файла ui.R примера в свой файл ui.R.

На Уроке 4 вы узнаете как соединить виджеты, чтобы добиться реакции на изменение входных ванных. Объекты будут обновляться всякий раз, как только пользователь изменит значение виджета.