Package org.apache.juneau.console.freemarker

Class PageSpec

java.lang.Object
org.apache.juneau.console.freemarker.PageSpec
public final class PageSpec extends Object
Java description of one console page: the active tab, toolkits, page CSS and init scripts, per-request header fields, the stock theme by name, and the page's cards (tables, html and registered custom types) and body attributes.

A PageSpec renders nothing itself. Its values are seeded into the request's PageCapture before any directive runs, so a built page goes through the same <@console> chrome and emits the same #juneau-page contract and the same toolkit asset tags as an FTL page. Chrome (brand, nav tree, footer, theme tokens) stays in the app's chrome template.

Example:

var spec = PageSpec.create() .title("SLO") .tab("slo") .toolkit("views") .css("/css/slo.css") .csrf(token, "X-CSRF") .html("intro", "<p>Queue health</p>") .table(sloTable);

Example:

return PageSpec.create() .tab("changes") .table(ChangesView.def(), c -> c.title("Changes")) .table(TasksView.def(), c -> c.title("Tasks for the selected change") .subscribes(Subscription.to(Topics.selection("changes")).as("params").map("changeId", "ids.0"))) .card(ChartDef.bar("byOwner").title("Open changes by owner").src("/rest/changes/by-owner?q={q}") .x("owner").series("open", "Open").toCardSpec() .subscribes(Subscription.to(Topics.filter("changes")).as("params").map("q", "search"))) .view(req);

Since:
10.0.0

  • Field Details

  • Method Details

    • create

      public static PageSpec create()
      Creates a new, empty spec.
      Returns:
      A new spec.

    • template

      public PageSpec template(String pageTemplateName)
      Sets the page template, overriding the mixin's configured chrome template.
      Parameters:
      pageTemplateName - The template name (no .ftlh).
      Returns:
      This object.

    • attr

      public PageSpec attr(String key, Object value)
      Adds a passthrough attribute, applied to the view this spec builds.
      Parameters:
      key - The attribute name.
      value - The attribute value.
      Returns:
      This object.

    • header

      public PageSpec header(String name, String value)
      Adds a passthrough HTTP response header, applied to the view this spec builds.
      Parameters:
      name - The header name.
      value - The header value.
      Returns:
      This object.

    • title

      public PageSpec title(String v)
      Sets the page title. The spec always wins over <@console title>.
      Parameters:
      v - The title.
      Returns:
      This object.

    • tab

      public PageSpec tab(String idPath)
      Sets the <@page tab>-equivalent active-nav path.
      Parameters:
      idPath - A '/'-separated id path, e.g. "home/skills/core".
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If blank, or any segment is blank.

    • theme

      public PageSpec theme(String stockName)
      Selects a stock theme by name. Validated immediately via ConsoleChromeMixin.stockTheme(String).
      Parameters:
      stockName - One of ConsoleChromeMixin.BUILTIN_THEME_NAMES.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If stockName is not a built-in stock-theme name.

    • scheme

      public PageSpec scheme(String name)
      Pins the page's colour scheme.

      auto (the default) follows the browser's prefers-color-scheme; light and dark pin the page. An explicit <@console scheme="…"> on the page template wins over this value.

      Parameters:
      name - One of ConsoleChromeMixin.SCHEMES.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If name is not a known scheme.

    • schemeToggle

      public PageSpec schemeToggle(boolean value)
      Lets the visitor override the page's colour scheme with a stored choice.

      An explicit <@console schemeToggle="…"> on the page template wins over this value.

      Parameters:
      value - Whether the stored choice is honoured.
      Returns:
      This object.

    • toolkit

      public PageSpec toolkit(String... names)
      Adds toolkit names, appending any not already present.
      Parameters:
      names - The toolkit names.
      Returns:
      This object.

    • css

      public PageSpec css(String... urls)
      Adds page CSS URLs, appending any not already present.
      Parameters:
      urls - The CSS URLs.
      Returns:
      This object.

    • init

      public PageSpec init(String... urls)
      Adds page init-script URLs, appending any not already present.
      Parameters:
      urls - The script URLs.
      Returns:
      This object.

    • header

      public PageSpec header(Consumer<PageCapture.HeaderSpec> c)
      Sets the header's subtitle and/or userMenu. These are the only two header fields this builder may set; every other field belongs in the chrome template.
      Parameters:
      c - Mutates a scratch PageCapture.HeaderSpec.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If c sets any field other than subtitle/userMenu, or the user menu has a key the page contract does not allow.

    • table

      public PageSpec table(TableSpec table)
      Adds a datatables card for table, with no title.
      Parameters:
      table - The table. Validated and snapshotted immediately; later changes to it do not affect this page.
      Returns:
      This object.

    • table

      public PageSpec table(TableSpec table, String title)
      Adds a datatables card for table, with a title.
      Parameters:
      table - The table.
      title - The card title.
      Returns:
      This object.

    • table

      public PageSpec table(TableSpec table, Consumer<CardSpec> card)
      Adds a datatables card for table, letting card adjust the card.

      The table's CSS class, if set, is carried onto the card wrapper before card runs, so card may override it. The card body is produced by the card-type registry when the spec is seeded into a page.

      Parameters:
      table - The table.
      card - Mutates the card. May be null.
      Returns:
      This object.

    • html

      public PageSpec html(String id, String markup)
      Adds an html card whose body is markup, with no title.
      Parameters:
      id - The card id.
      markup - The markup, emitted as <template data-card=id>. Must not be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If markup is null.

    • html

      public PageSpec html(String id, String title, String markup)
      Adds an html card whose body is markup, with a title.
      Parameters:
      id - The card id.
      title - The card title.
      markup - The markup. Must not be null.
      Returns:
      This object.

    • html

      public PageSpec html(String id, String markup, Consumer<CardSpec> card)
      Adds an html card whose body is markup, letting card adjust the card (title, CSS class, and so on). card must not also set src or template.
      Parameters:
      id - The card id.
      markup - The markup. Must not be null.
      card - Mutates the card. May be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If markup is null, or card sets src or template.

    • htmlSrc

      public PageSpec htmlSrc(String id, String title, String src)
      Adds an html card whose body is fetched from src, with a title, unsanitized. See htmlSrc(String,String,String,boolean) for the trust boundary.
      Parameters:
      id - The card id.
      title - The card title. May be null for no title.
      src - The same-origin path of the HTML fragment endpoint. Must not be blank.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If src is null or blank.

    • htmlSrc

      public PageSpec htmlSrc(String id, String title, String src, boolean sanitize)
      Adds an html card whose body is fetched from src, with a title, optionally rebuilt through the views attribute-allowlist sanitizer. The equivalent of <@card type="html" src="..." sanitize=true>.
      Trust boundary:

      With sanitize false the shell fetches src and inserts the returned HTML as-is through a raw HTML-sink assignment, unsanitized, the same trust level as footer.text (see HtmlCardType). The endpoint must therefore be a trusted first-party route, must never be derived from request data, and must escape any data it embeds in the fragment. src must be a same-origin path; an absolute URL, a scheme, //, .. or a backslash is refused when the page is built, exactly as for every other card.

      With sanitize true the fragment is rebuilt through the views attribute-allowlist sanitizer instead: script, on* handlers, javascript: and data: URLs and every attribute off the allowlist are dropped, and benign markup (text, tables, links, images) survives. It needs the views toolkit on the page; without the toolkit nothing is painted (the shell fails closed rather than inserting the fragment unsanitized). The sanitizer does not remove the need to escape any data you embed in the fragment. Turn it on when the fragment's content is not fully under your control (it embeds user-supplied or third-party markup, or comes from an endpoint you do not own); leave it off for a fragment that needs class, id, style, forms, SVG or iframes, which the allowlist drops. The default stays off.

      Parameters:
      id - The card id.
      title - The card title. May be null for no title.
      src - The same-origin path of the HTML fragment endpoint. Must not be blank.
      sanitize - Whether to rebuild the fetched fragment through the sanitizer.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If src is null or blank.

    • card

      public PageSpec card(CardSpec card)
      Adds a custom-type card with no inline markup.

      When the page renders, a card of an adopter type (any type that is not reserved) is built as <@card> builds it: its body map is the authored body, the type's registered CardTypeHandler validates it and returns the fragment the card carries, and an invalid body fails the render with the <@card> message. An unregistered type takes the generic passthrough, so its body map is carried as-is.

      Parameters:
      card - The card. Its type must not be a removed type or one with a dedicated method.
      Returns:
      This object.

    • card

      public PageSpec card(CardSpec card, String markupOrNull)
      Adds a custom-type card that also takes inline markup.
      Parameters:
      card - The card. See card(CardSpec).
      markupOrNull - The markup, or null. For an adopter type it is the card's body, as the content of <@card> is: the handler parses it (JSON5) or captures it as <template data-card=card.id()>, and subscribes / publishes keys in JSON5 markup are wired onto the card. A card takes at most one of a body map, non-blank markup, template or src.
      Returns:
      This object.

    • dashboard

      public PageSpec dashboard(DashboardSpec dashboard)
      Adds the page's dashboard: a rail of filter sections beside a grid of card panels.

      The panel and card-section cards built by the dashboard are added to this page as ordinary cards, and the dashboard toolkit pack is added (just before charts when that is listed). A by-id panel (panel("notes")) must name a card added before this call, for example with html(String, String).

      Parameters:
      dashboard - The dashboard.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - E-77 on any dashboard problem, or if the page already has a dashboard.

    • csrf

      public PageSpec csrf(String token, String headerName)
      Sets the CSRF body attributes: data-juneau-csrf and, if headerName is non-blank, data-juneau-csrf-header.
      Parameters:
      token - The CSRF token value.
      headerName - The CSRF header name, or null/blank to omit the header attribute.
      Returns:
      This object.

    • bodyAttr

      public PageSpec bodyAttr(String name, String value)
      Sets one <body> attribute.
      Parameters:
      name - The attribute name.
      value - The attribute value; & < > " are escaped.
      Returns:
      This object.

    • cards

      public List<CardSpec> cards()
      Returns:
      The declared cards, in declaration order; a snapshot.

    • card

      public Optional<CardSpec> card(String id)
      Looks up a declared card by id.
      Parameters:
      id - The card id.
      Returns:
      The card, or empty if none was declared with this id.

    • badge

      public PageSpec badge(BadgeDef def)
      Adds a header badge. The Java twin of <@badge>.
      Parameters:
      def - The badge. Must not be null.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - If BadgeDef.validate() rejects it.

    • facts

      public PageSpec facts(Map<String,Object> v)
      Seeds page-level facts, which visibleWhen rules test on the client. Repeated calls merge, last wins, on this side only; the strict check against chrome-supplied facts runs once, at </@console>.
      Parameters:
      v - The facts. Leaves must be strings, numbers, booleans, string lists or maps.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - On a leaf of any other type.

    • topic

      public PageSpec topic(TopicDecl decl)
      Declares a page-level custom topic; repeatable. Unions with FTL <@topic>.
      Parameters:
      decl - The declaration; needs retain and publisher.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - E-46 if the topic is already declared with a different retain or publisher.

    • bridge

      public PageSpec bridge(BridgeDecl decl)
      Declares a server bridge; repeatable. Unions with FTL <@bridge>.
      Parameters:
      decl - The bridge.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - E-51 on a duplicate id, or from BridgeDecl.toMap().

    • data

      public PageSpec data(DataSourceDef def)
      Declares a data source, published on data:<id>; repeatable.
      Parameters:
      def - The source.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - E-76 on a duplicate id or a bad declaration; also on a null definition.

    • data

      public PageSpec data(Derived def)
      Declares a derived data source, published on data:<as>; repeatable.
      Parameters:
      def - The derived source.
      Returns:
      This object.
      Throws:
      IllegalArgumentException - E-76 on a duplicate id or a bad declaration; also on a null definition.
      IllegalStateException - If Derived.as(String) was not called.

    • template

      public String template()
      Returns:
      The template name, or null if unset (the mixin's chrome template applies).

    • tab

      public String tab()
      Returns:
      The tab path, or "" if unset.

    • toolkits

      public List<String> toolkits()
      Returns:
      The toolkit names, in declaration order.

    • view

      public FreemarkerView view(RestRequest req)
      Builds the view for this spec.

      The template is template(String) when set, else the ConsoleFreemarkerMixin's chrome template. A built spec is not modified by rendering, so it may be cached and reused across requests. Call spec.view(req) on each request: a reused FreemarkerView would share one adoption flag.

      Parameters:
      req - The current REST request.
      Returns:
      A view for the template, carrying this spec and every attr(String, Object) / header(String, String) passthrough.
      Throws:
      IllegalStateException - If no template was set and the request has no ConsoleFreemarkerMixin bean.
      IllegalArgumentException - If this spec has no page template and its bus wiring fails R-10 / R-11.