Defaults and Custom Settings for the Web App

What this article covers

EJAM has several ways to customize the Shiny app. They act at different times and are not interchangeable:

Mechanism	Best for	Scope
Arguments to ejamapp()	Configuring a local app or a deployment	Fixed for that app process
App launch parameters such as ?fips=	Opening an already-running app with sites or a radius	One visitor’s session
A Shiny bookmark	Restoring Shiny input controls	One saved session state
The Advanced Settings tab	Changing the controls exposed there	Current session, after launch
EJAM API request parameters	Requesting a report or data without the Shiny app	One API request

This distinction is important. For example, adding an arbitrary ?name=value to the app URL does not turn it into an ejamapp(name = value) argument. The app recognizes only the launch parameters listed below. Likewise, an ejamapp() argument is not bookmarkable unless it becomes a Shiny input$ control.

For development-branch documentation, use:

• this article on the development site;
• the development ejamapp() reference;
• Accessing the Web App for the user-facing overview; and
• Using the EJAM API for API endpoints and parameters.

Configure an app with ejamapp()

Run ejamapp() from R to launch a local app. The root app.R used for the hosted public app calls ejamapp(isPublic = TRUE). A plain local ejamapp() call defaults to the fuller analyst configuration because isPublic is not set to TRUE.

The authoritative parameter examples are in ?ejamapp. Keep calls small and use the documented convenience names:

## A local app preloaded with two counties and a 3-mile radius
EJAM::ejamapp(
  fips = c("10001", "10003"),
  radius = 3,
  default_show_advanced_settings = TRUE
)

## Start with a detailed NAICS selection
EJAM::ejamapp(
  analysis_title = "Custom NAICS analysis",
  naics = "562211"
)

Use radius, not the internal setting name radius_default, in new ejamapp() calls. ejamapp() normalizes radius (and its synonym buffer) to that internal setting.

Supported convenience arguments

ejamapp() accepts ..., then normalizes these documented aliases before collecting the app defaults:

Argument supplied	Internal setting or data
radius or buffer	radius_default
pts, or lat plus lon	sitepoints
shp or shape	shapefile
fips	FIPS upload data
naics, sic, or mact	The corresponding default_* selection
analysis_title	default_standard_analysis_title
report_title	report_title_multisite
default_upload_dropdown	Backward-compatible alias for default_site_method

Supplying sites also selects the matching site-selection method. For example, fips= selects the FIPS upload path, shapefile= selects the polygon upload path, and naics= selects the dropdown NAICS path.

Because ... can accept any name, a misspelled or unused name is not guaranteed to produce an error. Use names documented by ?ejamapp, or an exact setting name that the UI or server reads through global_or_param().

How deploy-time defaults are collected

At launch, ejamapp():

1. normalizes its convenience arguments;
2. calls get_global_defaults_or_user_options();
3. keeps user-supplied values ahead of same-named defaults from global_defaults_package.R, global_defaults_shiny.R, and global_defaults_shiny_public.R;
4. stores the resulting list as golem options; and
5. creates the app with app_ui, app_server, and the requested bookmarking mode.

global_defaults_shiny_public.R uses isPublic to choose the simpler public configuration. Most code reads the collected value with global_or_param("setting_name").

Package maintainers may change a default in the appropriate inst/global_defaults_*.R source file. For a particular local run or deployment, prefer an ejamapp() argument instead of editing an installed package file.

Launch an already-running EJAM app

An app launch URL can preload sites for one visitor without changing the deployed app’s defaults. Use url_ejamapp() to build these links. It uses the query-preserving app alias recorded in DESCRIPTION, rather than hardcoding a deployment hostname.

EJAM::url_ejamapp(
  lat = c(33, 34),
  lon = c(-112, -114),
  radius = 3
)
#> [1] "https://ejam.ejanalysis.com?lat=33,34&lon=-112,-114&radius=3"

EJAM::url_ejamapp(fips = c("10001", "10003"), buffer = 0)
#> [1] "https://ejam.ejanalysis.com?fips=10001,10003&radius=0"

The app recognizes:

• ?lat=33,34&lon=-112,-114 for points;
• ?fips=10001,10003 for FIPS codes;
• ?shape=<URL-encoded inline GeoJSON> for a polygon or FeatureCollection;
• ?radius=3 or ?buffer=3 for the analysis radius in miles;
• ?handoff=<token> for a site collection stored temporarily by the EJAM API; and
• ?advanced=TRUE (or ?show_advanced_settings=TRUE) to show the Advanced Settings tab.

advanced accepts 1, true, t, yes, or y; the corresponding false values hide the tab. An unrecognized value is ignored. url_ejamapp() builds the site, radius, and handoff parameters. Append the Advanced Settings parameter when needed:

paste0(EJAM::url_ejamapp(), "?advanced=TRUE")
#> [1] "https://ejam.ejanalysis.com?advanced=TRUE"

paste0(
  EJAM::url_ejamapp(fips = c("10001", "10003")),
  "&advanced=TRUE"
)
#> [1] "https://ejam.ejanalysis.com?fips=10001,10003&advanced=TRUE"

Launch-parameter rules and limits

• A handoff token is handled instead of direct site parameters.
• Otherwise the app loads one place type, in this order: valid lat/lon points, then FIPS, then an inline GeoJSON shape.
• Point latitude and longitude vectors must have equal lengths and contain no missing values.
• shape= must contain inline GeoJSON. A URL or local file path is deliberately rejected.
• A single radius applies to all supplied sites. Radius zero is valid for FIPS and polygon analyses; a point radius is clamped to the point slider’s allowed range.
• Launch-provided sites and radius take precedence over corresponding ejamapp()/deployment defaults at startup. The user can still change controls afterward.

Large polygon collections can exceed normal URL limits. EJScreen’s “Send to EJAM” workflow sends those places to the EJAM API POST /handoff endpoint, receives a short-lived token, and opens the app with ?handoff=<token>. The app retrieves the collection from GET /handoff/<token>. See Using the EJAM API and the EJAM-API README.

Shiny bookmarks

Bookmarks restore Shiny input$ values. They are separate from the compact launch parameters above.

ejamapp(enableBookmarking = "url") is the default. When bookmarking is enabled, use the app’s Bookmark button to generate the URL; do not construct ?_inputs_&... URLs by hand. Input IDs and encoded formats can change.

• URL bookmarking stores input values in the URL but cannot carry uploaded files.
• Server bookmarking stores state on the server and can preserve uploads, subject to the Shiny server’s configuration and retention.
• enableBookmarking = "disable" disables the feature.

A bookmark captures inputs, not every app option. Values such as a deployment logo or an option that never becomes an input are not restored by a bookmark. Use the compact launch parameters for points, FIPS, polygons, handoff tokens, and radius rather than trying to encode uploaded site data as bookmark inputs.

Advanced Settings

The Advanced Settings tab exposes a subset of app settings as Shiny inputs. It does not expose every global_defaults_* value or every ejamapp() argument.

• For a local or purpose-built deployment, use ejamapp(default_show_advanced_settings = TRUE).
• To let users reveal or hide it from the About tab, use ejamapp(default_can_show_advanced_settings = TRUE).
• For one visitor to a running app, use ?advanced=TRUE. This also enables the tab in a public deployment where it is normally unavailable.

The UI is built before reactive input$ values exist. A normal static control therefore gets its initial selected= or value= from global_or_param(), never from input$.... When an Advanced Settings control changes a main control later, app_server.R applies it with an update*Input() function. Use renderUI() only when the widget’s structure itself depends on reactive state.

Advanced Settings includes experimental and specialist controls. Changing a cap in the tab cannot exceed an absolute maxmax_* limit set by the deployment.

Links from EJAM to EJScreen

url_ejscreenmap() builds the reverse kind of deep link: it opens the EJScreen map with a place drawn or selected. This is not an EJAM app-default mechanism, so its full parameter vocabulary is maintained in ?url_ejscreenmap and the EJScreen repository rather than duplicated here.

## One EJScreen URL containing both points
EJAM::url_ejscreenmap(
  lat = c(39, 39.7),
  lon = c(-75.5, -75.6),
  radius = 3,
  combined = TRUE
)
#> [1] "https://pedp-ejscreen.azurewebsites.net/index.html?lat=39,39.7&lon=-75.5,-75.6&radius=3"

The helper supports points, supported Census FIPS types, small polygon outlines, explicit ZIP codes, and wherestr place searches. The destination EJScreen deployment must include the deep-link support added in Public-Environmental-Data-Partners/EJScreen#70; older deployments ignore the newer selection parameters.

API parameters are a separate interface

ejamapi() and url_ejamapi() request reports or data from the REST API. They are not alternate ways to set arbitrary Shiny app controls. The API and app deep links share core site names such as lat, lon, fips, shape, radius, and buffer, but each interface has additional parameters and different return behavior.

See Using the EJAM API, ?ejamapi, ?url_ejamapi, and the EJAM-API README for the current endpoint-specific contract.

Developer maintenance checks

Do not paste a snapshot of every global default or input$ name into this article. Those lists become obsolete whenever the app changes. Inspect the source of truth instead:

## Consolidated defaults from the installed package
defaults <- EJAM:::get_global_defaults_or_user_options()
sort(names(defaults))

## Approximate input$ references in the current server source
EJAM:::input_names_listing("R/app_server.R")

When changing this system, check these files together:

• R/ejamapp.R for convenience arguments and launch-time normalization;
• R/utils_get_global_defaults_or_user_options.R and R/utils_global_or_param.R;
• inst/global_defaults_package.R, inst/global_defaults_shiny.R, and inst/global_defaults_shiny_public.R;
• R/app_ui.R for static controls and the Advanced Settings tab;
• R/app_server.R for launch-URL parsing, reactive controls, and update*Input() synchronization;
• R/url_ejamapp.R for app-link generation; and
• tests/testthat/test-webapp-ui_and_server.R and tests/testthat/test-URL_FUNCTIONS_part1.R for the corresponding contracts.

If a new launch parameter is added, update the parser, URL builder where applicable, tests, ?ejamapp/?url_ejamapp, this article, and the shorter cross-references in Accessing the Web App and Using the EJAM API.