Breaking change: epoxy_latex() and the epoxy_latex chunk engine it
powers now use << and >> to delimit inline expressions. Where you
previously may have used <expr>, please now use <<expr>>. This breaking
change was necessary to allow the expr to include common R operators like
< and >. (#107)
Breaking change: the whisker engine is now powered by
epoxy_mustache(), resulting in a few small changes. In particular, if you
previously used a list for the .data chunk option in a whisker chunk, and
relied on the whisker engine's special treatment of lists to iterate over
their items, you'll need to specifically opt into this behavior by adding a
.vectorized = TRUE chunk option.
This chunk engine still vectorizes over rows in a data frame by default, where it's much more likely to be the behavior you want, but bare lists require specifically opting in. (#103)
.data is now the preferred chunk option for passing data frames or lists of
data to epoxy chunks, where previously data was used in some places. It
works in whisker and epoxy chunks, and is more consistent with the .data
argument of glue() and epoxy(). (#102)
New epoxy_mustache() provides an epoxy-style interface to the
mustache templating language, using the
whisker package. This function
also now powers the whisker or mustache knitr engines. epoxy also now
provides aliases for whisker and mustache in all places, so you can use
whichever name resonates with you. (#103)
New epoxy_use_chunk() and epoxy_use_file() allow you to re-use an
epoxy(), epoxy_html() or other epoxy-provided knitr chunk or file as a
template. epoxy_use_chunk() lets you re-use a template chunk with new data,
and epoxy_use_file() lets you repeatedly use a template stored in a file.
Both functions also re-use the options from the template chunk or the options
set in the YAML from matter of the template file. See ?epoxy_use for more
details about how options for both functions are determined. (#106, #116)
epoxy() now adds a .data pronoun that allows you to refer to the list or
data frame passed into either the .data argument of epoxy() or the data
or .data chunk options. (#100)
epoxy_html() now supports inline transformations prefixed with @ instead
of ., e.g. @strong instead of .strong. Previously, you would have to
place the inline transformer in a nested {{ }} block, e.g.
{{ {{ .strong expr }} }}, but now you only need {{@strong expr}}. To combine the HTML transformer (epoxy_transform_html()) with the inline
transformer, you still need to nest: {{.text-muted {{@strong expr}}}}
creates <span class="text-muted"><strong>{expr}</strong></span>. (#120)
epoxy(), and by extension the LaTex and HTML counterparts, and all epoxy_*
knitr engines gain a .collapse argument to determine how a vector of
epoxy-transformed templates should be collapsed. The default is NULL, which
means that the output is returned as a vector. This argument is also useful in
epoxy_use_chunk() and for knitr chunks being used as a vectorized template.
(#115)
Aded .sentence (alias .sc) to the list of inline transformers provided by
epoxy_transform_inline(). This transformer will capitalize the first letter
of the first word in the expression. This is useful when you want to need to
start a sentence with a variable that may contain more than one word. (#112)
The .titlecase inline transformer now coerces inputs to character with
as.character() before applying tools::toTitleCase(), since toTitleCase()
will throw an error for non-character inputs. (#112)
epoxy(), epoxy_html(), epoxy_latex() and epoxy_mustache() (and their
related knitr engines) will all collect remote tbl_sql tables before
evaluation. This makes it much easier to pass data from a remote database
using {dplyr} and {dbplyr}. (#117)
Fixed an issue with epoxy_inline_transform() when used with custom
delimiters (#116).
epoxy_transform_html() now (again) returns a collapsed character string for
inline HTML transformations. This makes it easier to wrap a vector in
individual HTML tags and then slot it into a parent template. You can still
get length-consistent output by setting collapse = FALSE, which is most
useful when you want the template around the expression to repeat. (#96)
Fixed an issue with epoxy_transform_set() that prevented it from working
when knitr::opts_current$get("engine") returned an unexpected value.
This is epoxy's first release on CRAN! This NEWS file collects changes from versions that were available on GitHub prior to the CRAN release.
epoxy's knitr engine is now epoxy and not glue. This avoids a name clash
with the glue package, which provides a glue
knitr engine with similar functionality. epoxy also provides epoxy_html and
epoxy_latex knitr engines, although they can still be used via their aliases
glue_html and glue_latex. (#21)
The development version of epoxy included, for some time, two features that have changed significantly in this release:
The epoxy_style() functions were renamed epoxy_transform() and the
.style argument was deprecated in favor of the .transformer argument.
This change was made to avoid confusion with other meanings of "style", and
for consistency with glue::glue(). The epoxy_style_ prefix is now
epoxy_transform_, e.g. epoxy_transform_bold() or
epoxy_transform_collapse(). (#87)
The previous form of inline formatting -- epoxy_style_format() --
has been removed in favor of epoxy_transform_inline(). This new
transformer uses cli-style inline formatting and is enabled by default in
epoxy(), epoxy_html() and epoxy_latex() (#68).
epoxy_transform_html() now returns a character vector rather than a
collapsed character string when a template expression is a vector.
Added a new internal dataset, bechdel, containing details for a random
sample of ten movies that received a score of 3 on the
Bechdel Test (#24).
epoxy's transformers can now be chained via epoxy_transform(). For
example to use both epoxy_transform_bold() and epoxy_transform_collapse()
on all replacement strings, you can call epoxy_transform("bold", "collapse"). epoxy_transform() accepts a transform function name, e.g.
"collapse", the function object directly, e.g. epoxy_transform_collapse,
or a call to a transform function, e.g. epoxy_transform_collapse() (#26).
Values passed to the .transformer chunk option are now passed first to
epoxy_transform(), allowing you to provide a vector of transformer names or
a list of functions, e.g. .transformer = c("bold", "collapse"). This was
originally introduced using a separate chunk option epoxy_style, which is
now deprecated (#31, #87).
epoxy, epoxy_html() and epoxy_latex() are now exported functions that
power the knitr engines and use the same defaults (#46).
The HTML element syntax used in ui_epoxy_html() is now available in
epoxy_transform_html() and is used by default in epoxy_html() (#46).
The HTML syntax used by ui_epoxy_html() and epoxy_html() now provides a
mechanism for differentiating between HTML-safe and -unsafe content. To mark
an expression as HTML-safe, use !! before the variable or expression:
e.g. {{ button !!expr }} (#88).
A new ui_epoxy_markdown() function provides a way to create dynamic Shiny
UI elements written in Markdown. Rendering from markdown to HTML is handled
using pandoc::pandoc_convert() if the {pandoc} package is installed, or
otherwise commonmark::markdown_html() is used.
New ui_epoxy_mustache() provides a dynamically rendered Shiny UI element
that uses the mustache templating syntax. The
advantage of mustache templating over ui_epoxy_html() is that you have
dynamic variables in the template can appear anywhere in the HTML, not just in
the text portion (#51).
ui_epoxy_whisker() is also provided as an alias for discoverability/user
comfort (#60).epoxyHTML() and renderEpoxyHTML() were renamed ui_epoxy_html() and
render_epoxy() respectively. This better fits newer Shiny naming conventions
and reflects that render_epoxy() serves both ui_epoxy_html() and
ui_epoxy_mustache() (#56).
Added epoxy_transform_set() to enable setting the default .transformer
option for all chunks or epoxy functions. You can use this function to set the
epoxy transformer for all chunk engines or a subset of chunk engines. Use
epoxy_transform_get() to retrieve the epoxy transformer for a particular
engine.
You can also use epoxy_transform_set() to set the inline transformation
functions by matching the syntax used by epoxy_transform_inline(). See
?epoxy_transform_set for an example.
epoxy_transform_inline() is the default .transformer for epoxy() and
epoxy_latex() and their related knitr engines. epoxy_html() now uses
.transformer = epoxy_transform(c("inline", "html")).
Added a new vignette("inline-reporting") with thanks to @tjmahr for the
inspiration (#25).
epoxy requires glue >= 1.5.0.
ui_epoxy_html() will now render elements with IDs using the # syntax, e.g.
{{h3#name.author full_name}} will create an element that is (essentially)
<h3 id="name" class="author">{{ full_name }}</h3> (#22).
ui_epoxy_html(), instead of updating the entire ui_epoxy_html() region,
now only updates the part of the UI that has actually changed. If the template
variables are only included in the text portion of the template, you should
prefer ui_epoxy_html() over ui_epoxy_mustache() for this reason --
ui_epoxy_mustache() re-renders the entire template with every update.
The epoxy transformers for bold, italic and code transformations now choose
the correct syntax for the epoxy (markdown), epoxy_html and epoxy_latex
engines. Alternatively, you can force the desired syntax by setting the
syntax option (#28).
epoxy's knitr engines can now be set manually via the newly exported (and
renamed) use_epoxy_knitr_engines(). This function is called when epoxy is
loaded, so you most likely do not need to call it directly. In general, you
can instead simply library(epoxy). epoxy previously provided a glue chunk
rather than an epoxy chunk and you can restore this behavior by calling
use_epoxy_glue_engine() (#30).
A new transformer, epoxy_transform_apply(), can be used to globally apply a
function to glue expressions. epoxy_transform_apply() uses the same syntax
as purrr::map() for defining the function, i.e. tolower or ~ tolower(.x)
(#37).
epoxy_transform_collapse() now uses the
and package, which provides language-aware
conjoining of strings. As a result, the sep_and and sep_or arguments of
epoxy_transform_collapse() are deprecated and are silently ignored if
provided (#45).
Added engine_pick() for providing a set of options where the correct option
will be chosen based on the current chunk or epoxy engine.
Added a whisker engine that uses the whisker
package instead of glue.
The chunk option glue_data was changed to data.
The glue_html engine now uses {{ and }} for open/close delimiters.
glue/whisker chunks now accept .envir chunk option for the containing
environment, otherwise falling back to the knitr::knit_global() env.