Package org.apache.juneau.console.freemarker

Class ChartDef

java.lang.Object
org.apache.juneau.console.freemarker.ChartDef
public final class ChartDef extends Object
Typed builder for a chart card.

Produces the same contract entry as <@card type="chart">; PageSpec runs it through ChartCardType when the page renders. The factories are line(String), bar(String), donut(String), heatmap(String), scatter(String), pie(String), treemap(String) and raw(String). line, bar and donut emit the flat legacy form (kind:"line", x:..., series:[...]) byte-for-byte; the other kinds emit helper:{kind, ...}, and raw emits neither (its option(JsonMap) is the whole chart).

Example:

page.card(ChartDef.line("orders-trend").title("Orders").src("/console/store/stats/daily") .x("day").series("placed", "Placed").series("delivered", "Delivered").toCardSpec());

Since:
10.0.0

  • Field Details

  • Method Details

    • line

      public static ChartDef line(String id)
      Parameters:
      id - The card id. @return A new line chart.

    • bar

      public static ChartDef bar(String id)
      Parameters:
      id - The card id. @return A new bar chart.

    • donut

      public static ChartDef donut(String id)
      Parameters:
      id - The card id. @return A new donut chart.

    • heatmap

      public static ChartDef heatmap(String id)
      Parameters:
      id - The card id. @return A new heatmap (category x, category y, a value field).

    • scatter

      public static ChartDef scatter(String id)
      Parameters:
      id - The card id. @return A new scatter chart.

    • pie

      public static ChartDef pie(String id)
      Parameters:
      id - The card id. @return A new pie chart.

    • treemap

      public static ChartDef treemap(String id)
      A treemap: rows nested into boxes by groupBy(String...), one tile per row, with pan and zoom.

      A click on a tile publishes the row's tileFields(String...) as meta (the tile's row is always null); a click on a group does nothing.

      Example:

      ChartDef.treemap("fleet").src("/api/hosts").groupBy("region", "cluster").label("host") .colorBy("health", ChartDef.legendItem("ok", "Healthy", "ok"), ChartDef.legendItem("down", "Down", "danger")) .tileFields("host", "health");

      Parameters:
      id - The card id.
      Returns:
      A new treemap; set its groups with groupBy(String...) and its tile label with label(String).

    • raw

      public static ChartDef raw(String id)
      A chart with no helper. Anything ECharts draws works this way, for example a box plot:

      ChartDef.raw("latency").src("/stats/latency") .option("{xAxis:{type:'category'},yAxis:{},series:[{type:'boxplot',encode:{x:'day',y:['lo','q1','med','q3','hi']}}]}");

      Parameters:
      id - The card id.
      Returns:
      A new chart with no helper; set its ECharts option with option(JsonMap).

    • title

      public ChartDef title(String v)
      Parameters:
      v - The card title. @return This object.

    • src

      public ChartDef src(String v)
      Parameters:
      v - A same-origin URL returning an array of rows or {rows:[...]}. @return This object.

    • data

      public ChartDef data(List<? extends Map<String,?>> rows)
      Parameters:
      rows - Inline rows (flat maps). @return This object.

    • x

      public ChartDef x(String field)
      Parameters:
      field - The x (category) field. @return This object.

    • x

      public ChartDef x(String field, String type, String label)
      Parameters:
      field - The x field.
      type - category (default), number or time; null for the default.
      label - The axis label, or null.
      Returns:
      This object.

    • y

      public ChartDef y(String label, Number min, String format)
      Parameters:
      label - The value-axis label, or null.
      min - The axis minimum, or null for 0 (or the data minimum when negative).
      format - integer, decimal, percent or compact; null for the default.
      Returns:
      This object.

    • series

      public ChartDef series(String field, String label)
      Parameters:
      field - A numeric row field. @param label The legend label. @return This object.

    • series

      public ChartDef series(String field, String label, int tone)
      Parameters:
      field - A numeric row field. @param label The legend label. @param tone Palette slot 1-8. @return This object.

    • series

      public ChartDef series(String field, String label, String tone)
      Parameters:
      field - A numeric row field. @param label The legend label. @param tone danger, ok or warning. @return This object.

    • stacked

      public ChartDef stacked(boolean v)
      Parameters:
      v - Whether bar series stack. @return This object.

    • horizontal

      public ChartDef horizontal()
      Draws bars horizontally. @return This object.

    • legend

      public ChartDef legend(String v)
      Parameters:
      v - bottom (default), right or none. @return This object.

    • height

      public ChartDef height(int px)
      Parameters:
      px - The plot height, at least MIN_HEIGHT. @return This object.

    • refreshMs

      public ChartDef refreshMs(long ms)
      Parameters:
      ms - The re-fetch interval, at least SafePathTemplate.MIN_POLL_INTERVAL_MS. @return This object.

    • onClickHref

      public ChartDef onClickHref(String template)
      Parameters:
      template - A same-origin path template (SafePathTemplate.isSameOriginPath(String)); {field} is replaced with the clicked row's value.
      Returns:
      This object.

    • onClickAction

      public ChartDef onClickAction(RowAction action)
      Runs a row action when a mark is clicked.

      A treemap tile runs it; clicking a treemap group header only zooms and runs nothing.

      Declares on("click", "<id>.click") unless a click topic is already declared, and runs action whenever that topic fires. Exclusive with onClickHref(String). The action is refused unless it has an endpoint (and, if set, a form) that is a same-origin path, a non-safe method, and no present other than dialog, and does not navigate on success.

      Parameters:
      action - The action; its id must be unique across the card's actions.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the action is not valid on a chart, onClickHref(String) was set, or no click topic can be derived: the id must match [a-z][a-z0-9-]{0,31}, or call on(String, String) with "click" first.

    • onTopicAction

      public ChartDef onTopicAction(String topic, RowAction action)
      Runs a row action when a topic this card publishes fires.

      Only a click has a keyboard equivalent (Enter on the focused point synthesizes a click); an action bound to another event, such as dblclick, is reachable by pointer only. A treemap group node publishes no events.

      Parameters:
      topic - A topic declared through on(String, String).
      action - The action; its id must be unique across the card's actions.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If the topic is not declared, or the action is not valid on a chart.

    • actions

      public ChartDef actions(RowAction... actions)
      Adds dialog actions that other actions can open as steps.

      Each entry must have present set to dialog, and obeys the same rules as onClickAction(RowAction). Calls accumulate.

      Parameters:
      actions - The actions; ids must be unique across the card's actions.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If an entry is null, is not a dialog action, or is not valid on a chart.

    • emptyText

      public ChartDef emptyText(String v)
      Parameters:
      v - The text shown when there are no rows. @return This object.

    • groupBy

      public ChartDef groupBy(String... fields)
      Parameters:
      fields - The treemap group fields, outermost first; at least one, each non-blank. @return This object.

    • size

      public ChartDef size(String field)
      Parameters:
      field - The numeric treemap field that sizes each tile; without it every tile has the same size. @return This object.

    • colorBy

      public ChartDef colorBy(String field, JsonMap... legend)
      Parameters:
      field - The treemap field whose value picks each tile's colour.
      legend - The colour key, one legendItem(String, String, String) per value; a value with no entry is neutral.
      Returns:
      This object.

    • tileFields

      public ChartDef tileFields(String... fields)
      Parameters:
      fields - The row fields a tile click publishes as meta and its tooltip shows; each matches [A-Za-z0-9_.-]+. @return This object.

    • legendItem

      public static JsonMap legendItem(String value, String label, String tone)
      One entry of a treemap colour key.
      Parameters:
      value - The field value this entry matches.
      label - The key text; defaults to the value.
      tone - ok, warning, danger, --jc-chart-1 to --jc-chart-8, or null for neutral.
      Returns:
      The entry, for colorBy(String, JsonMap...).

    • label

      public ChartDef label(String field)
      Parameters:
      field - The donut slice-label field, or the treemap tile-label field. @return This object.

    • value

      public ChartDef value(String field)
      Parameters:
      field - The donut slice-value field. @return This object.

    • center

      public ChartDef center(String v)
      Parameters:
      v - total or literal center text. @return This object.

    • option

      public ChartDef option(JsonMap v)
      Parameters:
      v - A raw ECharts option (JSON only; functions through Fn). @return This object.

    • option

      public ChartDef option(String json5)
      Parameters:
      json5 - A raw ECharts option as JSON5, parsed by toCardSpec(). @return This object.

    • decorate

      public ChartDef decorate(Decorator d)
      Parameters:
      d - A decorator; a topic it names is added to the card's publishes. @return This object.

    • decorate

      public ChartDef decorate(String name, JsonMap args)
      Parameters:
      name - A dotted app decorator name (or a built-in). @param args Its arguments (no use key). @return This object.

    • patch

      public ChartDef patch(JsonMap v)
      Parameters:
      v - Deep-merged into the final option (objects by key, arrays by element id). @return This object.

    • patch

      public ChartDef patch(String json5)
      Parameters:
      json5 - A patch as JSON5, parsed by toCardSpec(). @return This object.

    • on

      public ChartDef on(String event, String topic)
      Parameters:
      event - An ECharts event name matching ^[a-z][a-z0-9_]{0,31}$.
      topic - A custom topic; added to the card's publishes.
      Returns:
      This object.

    • publishZoom

      public ChartDef publishZoom()
      Publishes the zoom window on zoom:<id>. @return This object.

    • publishLegend

      public ChartDef publishLegend()
      Publishes the legend selection on legend:<id>. @return This object.

    • group

      public ChartDef group(String v)
      Parameters:
      v - A connect group shared with other chart cards. @return This object.

    • renderer

      public ChartDef renderer(String v)
      Parameters:
      v - canvas (default) or svg. @return This object.

    • theme

      public ChartDef theme(String v)
      Parameters:
      v - An ECharts theme name registered in the page; the default is the page theme. @return This object.

    • source

      public ChartDef source(String dataTopic)
      Parameters:
      dataTopic - A data: topic (Topics.data(String)). @return This object.

    • yField

      public ChartDef yField(String field)
      Parameters:
      field - The heatmap y (category) field. @return This object.

    • scale

      public ChartDef scale(Number min, Number max)
      Parameters:
      min - The heatmap colour-scale minimum. @param max Its maximum. @return This object.

    • symbolSizeBy

      public ChartDef symbolSizeBy(String field)
      Parameters:
      field - The scatter field sized by square root. @return This object.

    • largeData

      public ChartDef largeData(int threshold)
      Parameters:
      threshold - Rows above which the large-data defaults apply. @return This object.

    • largeData

      public ChartDef largeData(int threshold, boolean progressive)
      Parameters:
      threshold - Rows above which the large-data defaults apply. @param progressive true sets progressive to the threshold; false leaves the JS default (5000). @return This object.

    • partialFrames

      public ChartDef partialFrames()
      Draws partial frames during a chunked source load. @return This object.

    • a11y

      public ChartDef a11y(String summary, boolean table)
      Parameters:
      summary - The figure caption, or null for the generated one. @param table Show the data-table toggle. @return This object.

    • map

      public ChartDef map(String name, String path)
      Parameters:
      name - An ECharts map name. @param path A same-origin path to its GeoJSON. @return This object.

    • set

      public ChartDef set(String key, Object value)
      Sets a body key that has no dedicated method (for example an ECharts-level card key the glue reads). For a helper kind, a helper key set here is routed under helper.
      Parameters:
      key - A key with no dedicated method.
      value - Its value.
      Returns:
      This object.

    • visibleWhen

      public ChartDef visibleWhen(VisibilityRule... rules)
      Parameters:
      rules - Card-level visibility rules, ANDed. @return This object.

    • toCardSpec

      public CardSpec toCardSpec()
      Returns:
      The chart card.
      Throws:
      IllegalArgumentException - If not exactly one of src/data/source is set, a kind's required keys are missing, raw has no option, or an option/patch string is not valid JSON5.