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.