Skip to contents

Add a button to a website

Source: R/input_button.R
input_button.Rd

Adds a button to reset an input or trigger a predefined function (including data export) to a website.

Usage

input_button(label, target = "reset_selection", id = label,
  dataview = NULL, query = list(), from_api = FALSE, class = "", ...,
  note = NULL)

Arguments

label

Text in the button for the user.

target

The ID of an input element to reset, a vector with IDs of input elements as names and values to set those inputs to as values, or the name of a function to trigger (e.g., c(input_a = 1)). Available function are refresh (to force a reprocessing of the current input state), reset_selection (to reset all input elements that are not settings), reset_storage (to clear local storage, reset all settings, and reload), export (to download data), copy (to save an API link to the clipboard), and filter (to open a data filter menu). This can also be a URL (including protocol) for a button-like link.

id

Unique ID of the element to be created.

dataview

Name of a data view to get selection and filter options from for export.

query

A list of query parameters, if target is "export" or "copy". See the API section.

from_api

Logical; if TRUE, target is "export", and an endpoint has been provided in site_build, links to the API rather than exporting from the browser.

class

Additional class names to add to the element.

...

Additional attributes to set on the element.

note

Text to display as a tooltip for the button.

Value

A character vector of the contents to be added.

API Query

The query argument can be used to specify export options for a download button. These options can also be included as query parameters in a site API's URL:

Format

These options affect the format of the returned file:

  • file_format: Specifies the separator between columns: 'csv' (default) for commas, or 'tsv' for tabs.

  • table_format: Specifies the layout of the data: 'tall' for a row for each value, with all values in the same column (repeats over entities, times, and variables); 'mixed' (default) for a row for each time, with a column for each variable (repeats over entities); 'wide' for a row for each entity, with a column for each variable at each time.

  • features: Specifies which features to include in the first columns of the file: A list with names for year column name, and value with the feature name to include in that column. Currently not available through the URL.

  • include: Specifies which variables to include: a vector or variable names, or (for the URL interface) a string with variable names separated by commas. By default, all variables are included.

  • exclude: Specifies which variables to exclude: a vector or variable names, or (for the URL interface) a string with variable names separated by commas.

Filters

These options can be used to subset data:

  • dataset: The name of a dataset, or vector (comma separated string) of dataset names. Includes all datasets by default.

  • variable[component]=value: Sets conditions on the summary of a variable. The summary of a variable is within each entity, which results in a set of summary components: "first", "min", "mean", "sum", "max", "last". The = sign can be another operator: "!=", ">=", "<=". values can be comma-separated sets of values.

  • feature=value: Sets conditions on a feature of each entity.

  • time_range: Selects a time or time range to include: ">=" or "<=" with a single minimal or maximal time, or "=" with a single time, or comma-separated set of two times.

See also

For buttons to select between a set of options, use input_buttongroup.

Examples

if (FALSE) {
# a selection reset button
input_button("Reset")

# a button to export all data, plus some added features
input_button("Download All Data", "export", query = list(
  features = list(ID = "id", Feature_A = "ft_a")
))

# a button to export a special subset
# from a URL:
#   https://example.com/api?dataset=set_a&include=variable_a,variable_b&
#   variable_a[min]>=10&feature_a=type_a,type_b
input_button("Download Subset", "export", query = list(
  dataset = "set_a", include = c("variable_a", "variable_b"),
  variable_a = list(component = "min", operator = ">", value = 10),
  feature_a = c("type_a", "type_b")
))
}