Skip to contents

Build a multilingual minisite index for generated species labels

Source: R/arboretum_minisite.R
arboretum_minisite.Rd

This function builds a standalone multilingual HTML index page for species labels generated by arboretum_labels(). It scans a directory containing _label.html files, extracts family and species names from the filenames, and creates a searchable index with direct links to each individual species label.

When a mined-data file from arboretum_data() is supplied through data_path, the minisite also displays vernacular names on species cards and includes an interactive summary dashboard with collection-level statistics. The generated page supports Portuguese, English, French, and Spanish interface text according to the languages selected in printed_lang.

The resulting index.html is first saved inside labels_dir. After the index is written, the entire labels directory is renamed using site_title, converted to ASCII and with spaces replaced by underscores, followed by the suffix _minisite.

Usage

arboretum_minisite(
  labels_dir = NULL,
  data_path = NULL,
  output_file = NULL,
  site_title = "Plant Collection",
  printed_lang = c("pt", "en", "fr", "es"),
  group_by_family = TRUE,
  logo = NULL,
  logo_url = NULL,
  verbose = TRUE
)

Arguments

labels_dir

Character string. Path to the directory containing the HTML label files produced by arboretum_labels(). The directory must exist and must contain files ending in _label.html.

data_path

Character string or NULL. Optional path to the CSV or Excel file produced by arboretum_data(), usually the same file used to generate the species labels. When supplied and successfully read, vernacular names are added to species cards, the search box also searches vernacular names, and the dashboard is rendered. If the file cannot be read, the function proceeds without vernacular names and without the dashboard. Default is NULL.

output_file

Character string or NULL. Full path for the output index HTML file. If NULL, the file is written as index.html inside labels_dir. If supplied, the parent directory must already exist. Default is NULL.

site_title

Character string. Title displayed in the browser tab and page header. It is also used to rename the final minisite folder after index.html is written. Default is "Plant Collection".

printed_lang

Character vector. Language codes to include in the minisite interface. Accepted values are "pt" for Portuguese, "en" for English, "fr" for French, and "es" for Spanish. The first language in the vector sets the initial display language. Default is c("pt", "en", "fr", "es").

group_by_family

Logical. If TRUE, species cards are grouped under family headings. If FALSE, all species cards are shown in a single flat grid. Default is TRUE.

Character string or NULL. Optional path to a logo image to embed in the minisite header as a Base64 data URI. Supported formats are PNG, JPG/JPEG, SVG, and WebP. If NULL, no logo is shown. Default is NULL.

logo_url

Character string or NULL. Optional URL to open when the logo is clicked. Used only when logo is supplied. If NULL, the logo is displayed without a hyperlink. Default is NULL.

verbose

Logical. If TRUE, prints a summary message after saving the minisite index and renaming the labels directory. Default is TRUE.

Value

Invisibly returns the path used to write the index HTML file. The function is called mainly for its side effects:

  • scans labels_dir for _label.html files;

  • writes a multilingual index.html file;

  • optionally embeds a logo as a Base64 data URI;

  • optionally reads mined species data to add vernacular names and dashboard summaries;

  • renames the labels directory using the sanitized site_title plus the suffix _minisite.

Details

The function follows five main steps:

  1. Input validation

    • Checks that labels_dir exists.

    • Searches for files ending in _label.html.

    • Checks that site_title is a single non-empty character string.

    • Validates the selected interface languages.

    • Checks that the parent directory of output_file exists, when output_file is supplied.

  2. Optional mined-data loading

    • Reads the file supplied through data_path, when provided.

    • Uses the mined data to join vernacular names to the species cards.

    • Uses the mined data to compute dashboard statistics.

    • Continues without a dashboard if the file cannot be read.

  3. Filename parsing

    • Parses label filenames following the pattern FAMILY_Genus_species_label.html.

    • Treats the first underscore-separated token as the family.

    • Joins the remaining tokens as the species name.

    • Handles species names with more than two epithet tokens, provided they follow the same filename convention.

  4. HTML minisite construction

    • Builds a searchable species index.

    • Adds real-time filtering by species, family, and vernacular name when vernacular names are available.

    • Adds language-switching buttons when more than one language is supplied.

    • Groups species by family when group_by_family = TRUE.

    • Adds a footer linking to aRboretum.

  5. Dashboard construction

    • Builds summary cards for total species, genera, and families.

    • Builds an origin donut chart from FFB.establishmentMeans.

    • Builds a Brazilian state bar chart from FFB.stateProvince.

    • Builds a phytogeographic-domain donut chart from FFB.phytogeographicDomain.

    • Builds a world-distribution bar chart from country.

    • Dynamically translates dashboard headings and labels when the interface language is changed.

The dashboard requires columns from the mined-data file, especially taxonName, family, FFB.vernacularName, FFB.establishmentMeans, FFB.stateProvince, FFB.phytogeographicDomain, and country. Missing optional values may simply result in empty or omitted dashboard panels.

Note

  • The function expects label filenames produced by arboretum_labels().

  • The minisite links are relative links to the individual species label files.

  • The function renames labels_dir after writing the index. For example, site_title = "JBRJ Arboretum" renames the folder to JBRJ_Arboretum_minisite.

  • Because the directory is renamed after writing, users should open the final index.html inside the renamed minisite folder.

  • Existing folders with the same final minisite name may cause file.rename() to fail, depending on the operating system.

  • The output is a standalone HTML file, but it links to the separate species label HTML files in the same folder.

See also

arboretum_data, arboretum_labels

Author

Domingos Cardoso & Martin Boucknooghe

Examples

if (FALSE) { # \dontrun{
# Build a minisite index from a folder of generated labels
arboretum_minisite(
labels_dir = "arboretum_species_labels"
)

# Build a minisite with vernacular names and dashboard summaries
arboretum_minisite(
labels_dir = "arboretum_species_labels",
data_path = "arboretum_data/arboretum_data.xlsx"
)

# Portuguese and English interface, flat species grid, custom title
arboretum_minisite(
labels_dir = "arboretum_species_labels",
data_path = "arboretum_data/arboretum_data.xlsx",
site_title = "JBRJ Arboretum",
printed_lang = c("pt", "en"),
group_by_family = FALSE
)

# Add a clickable institutional logo
arboretum_minisite(
labels_dir = "arboretum_species_labels",
data_path = "arboretum_data/arboretum_data.xlsx",
site_title = "Plant Collection",
logo = "path/to/logo.png",
logo_url = "https://www.institution.org"
)
} # }