The studio guide for update_mascot().
The same page is read in the mascot studio.
mascot::mascot_studio(fn = "update_mascot")
It opens on this function's guide; change a control and watch the mascot.
What each kind of value does in update_mascot()
| You pass | Example | The mascot |
|---|---|---|
| nothing (NULL) | mood = NULL |
keeps it as it is |
| an empty helper | bubble = mascot_bubble() |
clears it or goes back to the default |
| a value | mood = "happy" |
changes it |
Reset table: what each argument resets to
| Setting | Reset sent to update_mascot() |
|---|---|
| Character |
character = mascot_character() (back to “tessa”) |
| Mood |
mood = mascot_mood() (back to “idle”) |
| Size |
size = mascot_size() (160, small_screen = “auto”) |
| Status |
status = mascot_status() (follows the mood) |
| Bubble |
bubble = mascot_bubble() (removes it) |
| Theme |
theme = mascot_theme() (restores character
colours) |
| Click |
click = mascot_action() (or mascot_popup_menu(),
removes it) |
| Placement |
placement = mascot_placement() (resets to bottom-right;
mascot_placement(“inline”) returns inline) |
| Motion |
motion = mascot_motion_settings() (allows movement
subject to visitor preference) |
Whole setting. Each non-NULL argument replaces its whole setting (update_mascot(“h”, size = 200) also resets small_screen).
All or nothing. update_mascot() checks all values first. If any value is invalid, it warns, reports the issue, and sends nothing, preventing partial updates. Calling with an invalid argument name or outside a server session produces an error.
What else update_mascot() does
- In Shiny development mode, an invalid value also shows a worried mascot with the problem as its status; the next valid update clears it.
- Updates sent before a mascot appears are kept, one whole call at a
time, and applied once it does, also when the first mascot is made by
renderUI()orinsertUI(). Only the latest pending gesture plays. - A character or mood change applies before a gesture. During a character swap the gesture is skipped.
- A new placement replaces any position the visitor dragged the mascot to. With dragging on, the minimised restore button can be dragged too.
- The click count (
input$<id>_click) continues across changes of the click. - Bubbles survive mood changes and character swaps.
Condition classes
The classes are documented in ?"mascot-package". Errors
carry mascot_error, warnings mascot_warning
and messages mascot_message; the specific classes below
come in addition.
| Class | Type | When it occurs |
|---|---|---|
| mascot_error | Error | Any error raised by mascot, including checkmate assertions |
| mascot_warning | Warning | Any warning raised by mascot |
| mascot_message | Message | Any message raised by mascot |
| mascot_update_ignored | Warning | An invalid value in update_mascot(); the whole update is ignored |
| mascot_error_choice | Error | An invalid choice (the message lists valid options) |
| mascot_error_dots | Error | Unexpected arguments in … (e.g. an unnamed argument or typo) |
| mascot_error_argument | Error | An argument error in character authoring |
| mascot_error_character | Error | A character’s content is invalid |
| mascot_error_file | Error | A character file is invalid |
| mascot_contrast | Warning | Colour contrast against background is below 3:1 |
| mascot_placement_ignored | Message | Inline placement ignores minimise or drag |
| mascot_palette_dropped | Warning | A character swap drops a palette the incoming character lacks |
| mascot_gesture_dropped | Warning | Development diagnostic: a pending gesture cannot play |
| mascot_template_evicted | Warning | Development diagnostic: saved UI settings that no session uses are dropped to limit memory |
Warnings, errors and common mistakes
update_mascot("helper", character = "tessa", theme = "lilac_violet", session = session)
update_mascot() warns (class mascot_update_ignored) and ignores the whole update. The mascot and its current palette stay unchanged; nothing is dropped.
update_mascot("helper", "happy", session = session)
Arguments after id must be named. An unnamed argument reports "an unnamed argument" and lists the valid names.
update_mascot("helper", character = "tessa", mood = "sleepy", session = session)
Displays a warning listing valid moods. The mascot keeps its current mood.
update_mascot("helper", moood = "happy", session = session)
... must be empty, so typos produce an error listing the valid argument names.
update_mascot("helper", size = mascot_size(10), session = session)
A helper that errors gives a warning (class mascot_update_ignored); the whole update is ignored and the mascot stays unchanged.
update_mascot("helper", size = 10, session = session)
Sizes must be at least 24 pixels.
update_mascot("helper", placement = mascot_placement("inline", minimise = TRUE), session = session)
An inline mascot ignores minimise. An informational message explains this, and the mascot sits inline.
update_mascot("helper", bubble = mascot_bubble("Hi", duration = 0), session = session)
duration must be greater than zero. Use Inf to keep the bubble open.
update_mascot("helper", theme = list(outline = "not-a-colour"), session = session)
Colours are checked in R before sending to the browser.
update_mascot("helper", theme = list(outline = "#f8f9fa"), session = session)
The colour is applied, with a warning if contrast against the page is low. A plain list replaces the whole theme, so a selected palette is cleared.
update_mascot("helpr", mood = "happy", session = session)
No error, warning or console message, even in development mode: the server cannot see browser elements. The update is kept and applied if a mascot with that id appears later. Check the id against the one in the UI.