Package org.zkoss.zk.ui.sys

Class HtmlPageRenders

java.lang.Object
org.zkoss.zk.ui.sys.HtmlPageRenders
public class HtmlPageRenders extends Object
Utilities for implementing HTML-based PageRenderer.
Since:
5.0.0
Author:
tomyeh

  • Constructor Details

    • HtmlPageRenders

      public HtmlPageRenders()

  • Method Details

    • setContentType

      public static final void setContentType(Execution exec, Page page)
      Sets the content type to the specified execution for the given page.
      Parameters:
      exec - the execution (never null)

    • setCspHeader

      public static final void setCspHeader(Execution exec, Page page)
      Sets the Content-Security-Policy response header for the given page, if CSP is enabled (i.e., <csp-enabled> in zk.xml). Nothing is done if the page does not belong to a desktop.

      It must be invoked before any output is written, since a header can no longer be set once the response has been committed. It shall be invoked only when rendering a document -- not for an asynchronous update, whose response the browser does not apply a policy to.

      If a page renderer generates a complete document by itself, it must invoke this method. The ZUL and ZHTML page renderers do it for the pages they render.

      The header content is produced by the configured CspProvider; refer to Configuration.getCspProvider().

      Parameters:
      exec - the execution (never null)
      page - the page being rendered (never null)
      Since:
      11.0.0

    • outDocType

      public static final String outDocType(Execution exec, Page page)
      Returns the doc type, or null if not available. It is null or <!DOCTYPE ...>.

    • outUnavailable

      public static String outUnavailable(Execution exec)
      Generates the unavailable message in HTML tags, if any.
      Parameters:
      exec - the execution (never null)

    • outFirstLine

      public static final String outFirstLine(Execution exec, Page page)
      Returns the first line to be generated to the output, or null if no special first line.

    • outResponseJavaScripts

      public static final String outResponseJavaScripts(Execution exec)
      Generates the AU responses that are part of a page rendering. Notice that outPageContent(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Page, java.io.Writer, boolean) will invoke this method automatically.

      It is the same as outResponseJavaScripts(exec, false).

    • outResponseJavaScripts

      public static final String outResponseJavaScripts(Execution exec, boolean directJS)
      Generates the AU responses that are part of a page rendering. Notice that outPageContent(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.Page, java.io.Writer, boolean) will invoke this method automatically.
      Parameters:
      directJS - whether to generate JS directly. If true, it generates "x,y" where x and y are assumed to the responses. If false, it generates <script>zkac(x,y);</script>
      Since:
      5.0.2

    • outLangJavaScripts

      public static final String outLangJavaScripts(Execution exec, WebApp wapp, String deviceType)
      Returns HTML tags to include all JavaScript files and codes that are required when loading a ZUML page (never null).

      FUTURE CONSIDERATION: we might generate the inclusion on demand instead of all at once.

      Parameters:
      exec - the execution (never null)
      wapp - the Web application. If null, exec.getDesktop().getWebApp() is used. So you have to specify it if the execution is not associated with desktop (a fake execution, such as JSP/DSP).
      deviceType - the device type, such as ajax. If null, exec.getDesktop().getDeviceType() is used. So you have to specify it if the execution is not associated with desktop (a fake execution).

    • outLangStyleSheets

      public static final String outLangStyleSheets(Execution exec, WebApp wapp, String deviceType)
      Returns HTML tags to include all style sheets that are defined in all languages of the specified device (never null).

      In addition to style sheets defined in lang.xml and lang-addon.xml, it also include:

      1. The style sheet specified in the theme-uri parameter.

      FUTURE CONSIDERATION: we might generate the inclusion on demand instead of all at once.

      Parameters:
      exec - the execution (never null)
      wapp - the Web application. If null, exec.getDesktop().getWebApp() is used. So you have to specify it if the execution is not associated with desktop (a fake execution, such as JSP/DSP).
      deviceType - the device type, such as ajax. If null, exec.getDesktop().getDeviceType() is used. So you have to specify it if the execution is not associated with desktop (a fake execution).

    • getStyleSheets

      public static final List<org.zkoss.html.StyleSheet> getStyleSheets(Execution exec, WebApp wapp, String deviceType)
      Returns a list of StyleSheet that shall be generated to the client for the specified execution.
      Parameters:
      exec - the execution (never null)
      wapp - the Web application. If null, exec.getDesktop().getWebApp() is used. So you have to specify it if the execution is not associated with desktop (a fake execution, such as JSP/DSP).
      deviceType - the device type, such as ajax. If null, exec.getDesktop().getDeviceType() is used. So you have to specify it if the execution is not associated with desktop (a fake execution).

    • getRenderContext

      public static final HtmlPageRenders.RenderContext getRenderContext(Execution exec)
      Returns the render context, or null if not available. It is used to render the content that will appear before the content generated by ContentRenderer, such as crawlable content.
      Parameters:
      exec - the execution. If null, Executions.getCurrent() is assumed.

    • outPageContent

      public static final void outPageContent(Execution exec, Page page, Writer out, boolean au) throws IOException
      Returns the HTML content representing a page.
      Parameters:
      au - whether it is caused by asynchronous update
      exec - the execution (never null)
      Throws:
      IOException

    • outCspNonceAttr

      public static String outCspNonceAttr(String output)
      Adds the CSP nonce attribute to every <script> and <style> open tag found in the given output, and returns the result. The output is returned as is if it is null, or if CSP with strict-dynamic is not enabled. A tag whose first attribute is already nonce is skipped, so an author-supplied nonce is never duplicated.

      It works by scanning the given markup, so it may be used only on a buffer whose every <script and <style occurrence is a real open tag that shall carry the nonce; the body of a script or a style is fine. A buffer that might embed the text inside an attribute value or a JavaScript string literal -- such as a render context's perm buffer, which carries component data -- is not: the live per-request nonce would be spliced into that value, both corrupting it and disclosing the nonce. Build such an open tag with getCspNonceAttr() instead.

      Parameters:
      output - the markup to stamp; null is allowed
      Returns:
      the markup with the nonce attribute added, or the given output unchanged
      Since:
      11.0.0
      See Also:

    • prepareCspNonce

      public static final void prepareCspNonce()
      Mints the per-request CSP nonce eagerly, if CSP with strict-dynamic is enabled; does nothing otherwise.

      The nonce is otherwise created lazily by the first call to getCspNonceAttr(), which happens while the response is being written -- that is, after the page has been composed. Page code that runs earlier would then read nothing: an EL expression such as ${cspNonce}, a composer, a ViewModel or zscript. Invoke this method before composition, so that every phase sees the same value the Content-Security-Policy header will carry.

      It is idempotent: the nonce is minted once per execution and reused afterwards.

      Since:
      11.0.0
      See Also:

    • getCspNonceAttr

      public static String getCspNonceAttr()
      Returns the CSP nonce attribute of the current request, i.e., nonce="xxx" -- with a leading space, so it may be appended right after a tag name. An empty string is returned if CSP with strict-dynamic is not enabled, or if there is no active Web application.

      Use it to build the open tag of a <script> or a <style> that is written into a buffer also carrying component data. Unlike outCspNonceAttr(java.lang.String), it never scans markup, so a <script occurring inside application data cannot pick the nonce up.

      The value is supplied by the configured CspProvider and HTML-attribute encoded here. If the provider fails, an empty string is returned and a warning is logged once per response.

      Returns:
      the nonce attribute, or an empty string (never null)
      Since:
      11.0.0
      See Also:

    • outSEOContent

      public static void outSEOContent(Page page, Writer out) throws IOException
      Generates the SEO content for the given page. Nothing is generated if the SEO content has been generated or it shall not be generated.

      The SEO content shall be placed inside <div class="z-temp">.

      If a page renderer generates <div class="z-temp"> by itself, it must invoke this method.

      Throws:
      IOException
      Since:
      5.0.9

    • outSpecialJS

      public static final String outSpecialJS(Desktop desktop)
      Generates the special JavaScript code, such as the application's name. It shall be called, before generating "zkmx(" and "zkx(".
      Since:
      5.0.6

    • outStandalone

      public static final void outStandalone(Execution exec, Component comp, Writer out) throws IOException
      Generates the content of a standalone component that the peer widget is not a child of the page widget at the client.
      Parameters:
      comp - the component to render. It is null if no child component at all.
      Throws:
      IOException

    • outHeaders

      public static final String outHeaders(Execution exec, Page page, boolean before)
      Returns the content of the specified condition that will be placed inside the header element of the specified page, or null if it was generated before. For HTML, the header element is the HEAD element.

      Notice that this method ignores the following invocations against the same page in the same execution. In other words, it is safe to invoke this method multiple times.

      Parameters:
      before - whether to return the headers that shall be shown before ZK's CSS/JS headers. If true, only the headers that shall be shown before (such as meta) are returned. If true, only the headers that shall be shown after (such as link) are returned.

    • outHeaderZkTags

      public static String outHeaderZkTags(Execution exec, Page page)
      Generates and returns the ZK specific HTML tags including the headers defined in the specified page, or null if it was generated before.

      It is shortcut of
      outZkHeader(exec, page, true)+outZkTags(exec, null, null)+outZkHeader(exec, page, false)

      Unlike outZkTags(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.WebApp, java.lang.String), this method cannot be called in JSP/DSP (since desktop is not available).

      See Also:

    • outZkTags

      public static String outZkTags(Execution exec, WebApp wapp, String deviceType)
      Generates and returns the ZK specific HTML tags such as stylesheet and JavaScript.

      For each desktop, we have to generate a set of HTML tags to load ZK Client engine, style sheets and so on. For ZUL pages, it is generated automatically by page.dsp. However, for ZHTML pages, we have to generate these tags with special component such as org.zkoss.zhtml.Head, such that the result HTML page is legal.

      Parameters:
      exec - the execution (never null)
      wapp - the Web application. If null, exec.getDesktop().getWebApp() is used. So you have to specify it if the execution is not associated with desktop (a fake execution, such as JSP/DSP).
      deviceType - the device type, such as ajax. If null, exec.getDesktop().getDeviceType() is used. So you have to specify it if the execution is not associated with desktop (a fake execution).
      Returns:
      the string holding the HTML tags, or null if already generated.
      See Also:

    • isZkTagsGenerated

      public static boolean isZkTagsGenerated(Execution exec)
      Returns if the ZK specific HTML tags are generated.
      Since:
      5.0.3

    • setDirectContent

      public static boolean setDirectContent(Execution exec, boolean direct)
      Sets whether a component can directly generate HTML tags to the output.
      See Also:

    • isDirectContent

      public static boolean isDirectContent(Execution exec)
      Returns whether a component can directly generate HTML tags to the output. This flag is used by components that can generate the content directly, such as HtmlNativeComponent
      See Also:

    • outInitCrashScript

      public static final String outInitCrashScript(Execution exec, WebApp wapp)
      Returns Script tag to include init-crash-script and init-crash-timeout defined in zk.xml

      It will be placed before all JavaScript files and codes generated by outLangJavaScripts(org.zkoss.zk.ui.Execution, org.zkoss.zk.ui.WebApp, java.lang.String)

      Parameters:
      exec - the execution (never null)
      wapp - the Web application. If null, exec.getDesktop().getWebApp() is used.
      Since:
      7.0.4