View Source GGity.Theme (GGity v0.5.0)

Themes store style and other attributes of non-geom elements of a plot.

GGity generates an embedded stylesheet for the CSS presentation attributes of these elements that ties the specified styles to custom CSS classes that are automatically generated for each type of element.

Classes are generated irrespective of theme values, thereby allowing for the use of external stylesheets. To avoid overriding a style in an external stylesheet, set the value of the attribute(s) styled externally to nil in a plot's theme - GGity will not include a style in the embedded stylesheet for an attribute with a nil value.

Each key of a Theme struct represents a class. Allowed types for each item include:

  • nil - no selector or styles are generated for that class
  • %Element.Line{} struct - generates styles for a line element
  • %Element.Rect{} struct - generates styles for a rect element
  • %Element.Text{} struct - generates styles for a text element
  • An integer - for non-CSS attributes of a given element, e.g., :axis_ticks_length, which sets the value of the length attribute

See the documentation for each element type for allowed keys and values. Keys conform to the ggplot2 API, which means that a given attribute does not necessarily correspond to the CSS attribute of the same name. For example, :size means CSS stroke-width for lines and rectangles, and CSS font-size for text.

Element structs can be generated using the constructor function for that element type:

import GGity.Element.Text
alias GGity.Plot

Plot.theme(plot, axis_text: element_text(color: "green", size: 12))
#=> equivalent to Plot.theme(plot, axis_text: %GGity.Element.Text{color: "green", size 12})

The following attributes are supported:

  • :text style for all non-data text; overridden by other text attributes (Element.Text)
  • :axis_line x- and y axes lines (Element.Line)
  • :axis_line_x x axis; overrides :axis_line (Element.Line)
  • :axis_line_y y axis; overrides :axis_line (Element.Line)
  • :axis_text x- and y axis tick label text (Element.Text)
  • :axis_text_x x axis tick label text; overrides :axis_text (Element.Text)
  • :axis_text_y y axis tick label text; overrides :axis_text (Element.Text)
  • :axis_ticks x- and y axis ticks (Element.Line)
  • :axis_line_x x axis ticks; overrides :axis_ticks (Element.Line)
  • :axis_line_y y axis ticks; overrides :axis_ticks (Element.Line)
  • :axis_ticks_length length of x- and y axis ticks (Integer - non-CSS attribute)
  • :axis_ticks_x_length length of x axis tick; overrides :axis_tick_length (Integer)
  • :axis_ticks_y_length length of y axis tick; overrides :axis_tick_length (Integer)
  • :axis_title x- and y axis title text (Element.Text)
  • :axis_title_x x axis title text; overrides :axis_title (Element.Text)
  • :axis_title_y y axis title text; overrides :axis_title (Element.Text)
  • :legend_key legend key glyph box (Element.Rect)
  • :legend_text legend item text (Element.Text)
  • :legend_title legend title text (Element.Text)
  • :panel_background panel (area bounded by axes) background (Element.Rect)
  • :panel_border panel border (Element.Line)
  • :panel_grid minor and major gridlines (Element.Line)
  • :panel_grid_major major gridlines; overrides panel_grid (Element.Line)
  • :panel_grid_minor minor gridlines; overrides panel_grid (Element.Line)
  • :plot_title plot title text (Element.Text)
  • :plot_background plot (entire SVG element) background (Element.Rect)

security-considerations

Security Considerations

There is a significant security literature highlighting the risk associated with using embedded stylesheets. As a GGity user, you can address this risk in a few ways:

  1. Do not use GGity themes at all, by setting the :theme attribute of the Plot struct to nil. Use an external stylesheet that takes advantage of the classes that GGity attaches to elements of the plot. This option works well if plot styles do not need to be updated dynamically or stored in the same file as the SVG document. An external stylesheet also eliminates the overhead associated with generating and transmitting an embedded stylesheet every time the plot is rendered.

  2. Do not pass untrusted data (directly or indirectly) to Plot.theme/2. Depending on your use case, this may or may not be difficult to enforce with confidence.

If neither of these approaches are an option, GGity attempts to mitigate risk by HTML-escaping data that is rendered in a <text> element and by validating the values in each kind of Element struct prior to rendering. Most Element struct attributes are either colors (represented with strings) or numbers. GGity will not render those attributes if the value is invalid (colors must be a valid CSS color name or a hex value). Similarly, the :face attribute of an Element.Text struct is compared against a list of acceptable values.

This leaves the :family attribute of an Element.Text struct. These values are HTML-escaped, but are not otherwise sanitized and should not be set using untrusted data.

Link to this section Summary

Link to this section Types

@type t() :: %GGity.Theme{
  axis_line: term(),
  axis_line_x: term(),
  axis_line_y: term(),
  axis_text: term(),
  axis_text_x: term(),
  axis_text_y: term(),
  axis_ticks: term(),
  axis_ticks_length: term(),
  axis_ticks_length_x: term(),
  axis_ticks_length_y: term(),
  axis_ticks_x: term(),
  axis_ticks_y: term(),
  axis_title: term(),
  axis_title_x: term(),
  axis_title_y: term(),
  legend_key: term(),
  legend_text: term(),
  legend_title: term(),
  panel_background: term(),
  panel_border: term(),
  panel_grid: term(),
  panel_grid_major: term(),
  panel_grid_minor: term(),
  plot_background: term(),
  plot_title: term(),
  text: term()
}