Package org.apache.juneau.console.freemarker

Class PageCapture

java.lang.Object
org.apache.juneau.console.freemarker.PageCapture
public final class PageCapture extends Object
Typed, per-render capture of one console page: theme, header, footer, nav tree, active nav, cards and slot templates, held as FreeMarker Environment custom state (see KEY) so every directive in the render shares one instance. <@console> serializes it as the #juneau-page contract.
Example:

// Inside a custom directive that contributes a card: public void execute(Environment env, Map params, TemplateModel[] loop, TemplateDirectiveBody body) throws TemplateException, IOException { PageCapture page = PageCapture.of(env); page.addCard(CardSpec.html("intro").title("Welcome"), PageCapture.render(body)); } // In a test, after rendering: String json = PageCapture.get(env).toContractJson();

Since:
10.0.0

  • Field Details

  • Method Details

    • of

      public static PageCapture of(freemarker.core.Environment env) throws freemarker.template.TemplateModelException
      Returns the capture for this render, creating it on first use.

      On create, a PageSpec carried in the data model under PageSpec.ATTR is applied to the new capture before any directive writes to it, and marked adopted.

      Parameters:
      env - The FreeMarker environment.
      Returns:
      The capture, never null.
      Throws:
      freemarker.template.TemplateModelException - If seeding a PageSpec from the data model fails.

    • get

      public static PageCapture get(freemarker.core.Environment env)
      Returns the capture for this render, if one exists.
      Parameters:
      env - The FreeMarker environment.
      Returns:
      The capture, or null.

    • render

      public static String render(freemarker.template.TemplateDirectiveBody body) throws freemarker.template.TemplateException, IOException
      Renders a directive body to a string.
      Parameters:
      body - The body, or null.
      Returns:
      The rendered markup, or "" when the body is null.
      Throws:
      freemarker.template.TemplateException - On a template error.
      IOException - On an I/O error.

    • title

      public PageCapture title(String v)
      Parameters:
      v - The page title. @return This object.

    • theme

      public PageCapture theme(String name)
      Parameters:
      name - A stock theme name. @return This object.

    • scheme

      public PageCapture scheme(String name)
      Parameters:
      name - A colour-scheme pin: auto, light or dark. @return This object.

    • schemeToggle

      public PageCapture schemeToggle(boolean value)
      Parameters:
      value - Whether the visitor's stored scheme choice is honoured. @return This object.

    • tab

      public PageCapture tab(String v)
      Parameters:
      v - The <@page tab> value. @return This object.

    • toolkit

      public PageCapture toolkit(List<String> names)
      Parameters:
      names - Toolkit names from <@page toolkit>. @return This object.

    • header

      public PageCapture header(Consumer<PageCapture.HeaderSpec> c)
      Parameters:
      c - Mutates the header. @return This object.

    • footer

      public PageCapture footer(Consumer<PageCapture.FooterSpec> c)
      Parameters:
      c - Mutates the footer. @return This object.

    • select

      public PageCapture select(List<String> idPath) throws freemarker.template.TemplateModelException
      Explicitly selects a nav path (<@node selected="true">).
      Parameters:
      idPath - The root-first id path.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - If a path is already selected (E-6).

    • addCard

      public PageCapture addCard(CardSpec card, String markupOrNull) throws freemarker.template.TemplateModelException
      Appends a card.
      Parameters:
      card - The card.
      markupOrNull - Markup emitted as <template data-card="{id}">, or null.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - On a duplicate card id (E-9).

    • addSlot

      public PageCapture addSlot(String scope, String name, String markup)
      Adds a header or footer slot template.
      Parameters:
      scope - header or footer.
      name - The slot name.
      markup - The slot markup.
      Returns:
      This object.

    • addBadge

      public PageCapture addBadge(BadgeDef badge) throws freemarker.template.TemplateModelException
      Appends a header badge.
      Parameters:
      badge - The badge. Must not be null.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - On a duplicate badge id.

    • addPendingNavUnder

      public void addPendingNavUnder(String parentIdPath, PageCapture.NavAdder adder)
      Records a child to add under an existing chrome nav node, resolved later by applyPendingNavAdds().
      Parameters:
      parentIdPath - The root-first id path to the existing ancestor node.
      adder - Receives the resolved ancestor and adds its children to it.

    • applyPendingNavAdds

      public void applyPendingNavAdds() throws freemarker.template.TemplateModelException
      Resolves every pending nav addition recorded by addPendingNavUnder(java.lang.String, org.apache.juneau.console.freemarker.PageCapture.NavAdder), in declaration order. The pending list is cleared first, so a second call does nothing.
      Throws:
      freemarker.template.TemplateModelException - If a parentIdPath does not match an existing node.

    • mergeTab

      public PageCapture mergeTab(String tab) throws freemarker.template.TemplateModelException
      Merge-aware twin of tab(String): first writer wins, and any second non-blank writer is rejected, even with the same value.
      Parameters:
      tab - The <@page tab> value. Blank is a no-op.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - If a non-blank tab was already set.

    • mergeTheme

      public PageCapture mergeTheme(String name) throws freemarker.template.TemplateModelException
      Merge-aware twin of theme(String): first writer wins, a repeat of the same value is a no-op, and a differing second writer is rejected.
      Parameters:
      name - The <@theme name> value. Blank is a no-op.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - If a different, non-blank theme was already set.

    • mergeBodyAttrs

      public PageCapture mergeBodyAttrs(String attrs) throws freemarker.template.TemplateModelException
      Merge-aware setter for the raw <@body> attribute text: union by attribute name, existing (spec) text first and then the new text. The same attribute name on both sides is always rejected, even when the values agree. Called once, from checkConsoleClose(), with the text <@body> captured into ftlBodyAttrs.
      Parameters:
      attrs - The raw <@body> attribute text. Blank is a no-op.
      Returns:
      This object.
      Throws:
      freemarker.template.TemplateModelException - If an attribute name already set is set again.

    • mergeToolkit

      public PageCapture mergeToolkit(List<String> names)
      Union merge for toolkit(List): appends any name not already present, in first-seen order.
      Parameters:
      names - The names to union in.
      Returns:
      This object.

    • mergeCss

      public PageCapture mergeCss(List<String> hrefs)
      Union merge for the page stylesheets: appends any URL not already present, in first-seen order.
      Parameters:
      hrefs - The URLs to union in.
      Returns:
      This object.

    • mergeInit

      public PageCapture mergeInit(List<String> srcs)
      Union merge for the page init scripts: appends any URL not already present, in first-seen order.
      Parameters:
      srcs - The URLs to union in.
      Returns:
      This object.

    • require

      public PageCapture require(Collection<String> packs)
      Records toolkit packs the page needs, in first-seen order. Called by <@card> for each authored card and by other directives that emit markup needing a pack.
      Parameters:
      packs - The pack names.
      Returns:
      This object.

    • requiredPacks

      public Set<String> requiredPacks()
      Returns:
      The recorded pack names, in first-seen order.

    • inPage

      public boolean inPage()
      Returns:
      true while a <@page> body is rendering.

    • tab

      public String tab()
      Returns:
      The <@page tab> value, "" when absent.

    • toolkits

      public List<String> toolkits()
      Returns:
      The toolkit names.

    • activeNav

      public List<String> activeNav()
      Returns:
      The resolved active path (empty until <@console> closes, or when there is no selection).

    • cards

      public List<CardSpec> cards()
      Returns:
      The cards, in page order.

    • templates

      public Map<String,String> templates()
      Returns:
      Template id to markup, in emit order.

    • toContractJson

      public String toContractJson()
      Serializes the contract.
      Returns:
      Script-safe contract JSON (every < written as the JSON unicode escape).

    • writeBody

      public void writeBody(Writer out) throws IOException
      Writes the contract island, the templates and the shell script tag.
      Parameters:
      out - The writer.
      Throws:
      IOException - On an I/O error.