CombinedMarkupOutputFormat (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.core, class: CombinedMarkupOutputFormat

Package freemarker.core

# Class CombinedMarkupOutputFormat

java.lang.Object
freemarker.core.OutputFormat
freemarker.core.MarkupOutputFormat<MO>
freemarker.core.CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>
freemarker.core.CombinedMarkupOutputFormat

public final class CombinedMarkupOutputFormat extends CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>
Represents two markup formats nested into each other. For example, markdown nested into HTML.

Since:
  2.3.24

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CombinedMarkupOutputFormat​(MarkupOutputFormat outer, MarkupOutputFormat inner)`
  Same as `CombinedMarkupOutputFormat(String, MarkupOutputFormat, MarkupOutputFormat)` with `null` as the `name` parameter.
  `CombinedMarkupOutputFormat​(String name, MarkupOutputFormat outer, MarkupOutputFormat inner)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `escapePlainText​(String plainTextContent)`
  Should give the same result as `MarkupOutputFormat.fromPlainTextByEscaping(String)` and then `MarkupOutputFormat.getMarkupString(TemplateMarkupOutputModel)`, but the implementation may use a more efficient solution.
  `MarkupOutputFormat`
  `getInnerOutputFormat()`
  `String`
  `getMimeType()`
  Returns the MIME type of the output format.
  `String`
  `getName()`
  The short name used to refer to this format (like in the `#ftl` header).
  `MarkupOutputFormat`
  `getOuterOutputFormat()`
  `boolean`
  `isAutoEscapedByDefault()`
  Tells if by default auto-escaping should be on for this format.
  `boolean`
  `isLegacyBuiltInBypassed​(String builtInName)`
  Tells if a string built-in that can't handle a `TemplateMarkupOutputModel` left hand operand can bypass this object as is.
  `boolean`
  `isOutputFormatMixingAllowed()`
  Tells if this output format allows inserting `TemplateMarkupOutputModel`-s of another output formats into it.
  `protected TemplateCombinedMarkupOutputModel`
  `newTemplateMarkupOutputModel​(String plainTextContent, String markupContent)`
  Creates a new `CommonTemplateMarkupOutputModel` that's bound to this `OutputFormat` instance.
  `void`
  `output​(String textToEsc, Writer out)`
  Equivalent to calling `MarkupOutputFormat.fromPlainTextByEscaping(String)` and then `MarkupOutputFormat.output(TemplateMarkupOutputModel, Writer)`, but the implementation may use a more efficient solution.
  `<MO2 extends TemplateMarkupOutputModel<MO2>>
  void`
  `outputForeign​(MO2 mo, Writer out)`
  Outputs a value from a foreign output format; only used if `OutputFormat.isOutputFormatMixingAllowed()` return `true`.

  ### Methods inherited from class freemarker.core.CommonMarkupOutputFormat

  `concat, fromMarkup, fromPlainTextByEscaping, getMarkupString, getSourcePlainText, isEmpty, output`

  ### Methods inherited from class freemarker.core.OutputFormat

  `toString, toStringExtraProperties`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### CombinedMarkupOutputFormat

    public CombinedMarkupOutputFormat​(MarkupOutputFormat outer, MarkupOutputFormat inner)
    Same as `CombinedMarkupOutputFormat(String, MarkupOutputFormat, MarkupOutputFormat)` with `null` as the `name` parameter.

  - ### CombinedMarkupOutputFormat

    public CombinedMarkupOutputFormat​(String name, MarkupOutputFormat outer, MarkupOutputFormat inner)
    Parameters:
      `name` - Maybe `null`, in which case it defaults to `outer.getName() + "{" + inner.getName() + "}"`.

- ## Method Details

  - ### getName

    public String getName()
    Description copied from class: `OutputFormat`
    The short name used to refer to this format (like in the `#ftl` header).
    Specified by:
      `getName` in class `OutputFormat`

  - ### getMimeType

    public String getMimeType()
    Description copied from class: `OutputFormat`
    Returns the MIME type of the output format. This might comes handy when generating a HTTP response. `null` `null` if this output format doesn't clearly corresponds to a specific MIME type.
    Specified by:
      `getMimeType` in class `OutputFormat`

  - ### output

    public void output​(String textToEsc, Writer out) throws IOException, TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Equivalent to calling `MarkupOutputFormat.fromPlainTextByEscaping(String)` and then `MarkupOutputFormat.output(TemplateMarkupOutputModel, Writer)`, but the implementation may use a more efficient solution.
    Specified by:
      `output` in class `CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    Throws:
      `IOException`
      `TemplateModelException`

  - ### outputForeign

    public <MO2 extends TemplateMarkupOutputModel<MO2>> void outputForeign​(MO2 mo, Writer out) throws IOException, TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Outputs a value from a foreign output format; only used if `OutputFormat.isOutputFormatMixingAllowed()` return `true`. The default implementation in `MarkupOutputFormat` will just let the other `OutputFormat` to output value, but it can be overridden to support more nuanced conversions, or to check if outputting without conversion should be allowed.
    Overrides:
      `outputForeign` in class `MarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    Throws:
      `IOException`
      `TemplateModelException`

  - ### escapePlainText

    public String escapePlainText​(String plainTextContent) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Should give the same result as `MarkupOutputFormat.fromPlainTextByEscaping(String)` and then `MarkupOutputFormat.getMarkupString(TemplateMarkupOutputModel)`, but the implementation may use a more efficient solution.
    Specified by:
      `escapePlainText` in class `MarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### isLegacyBuiltInBypassed

    public boolean isLegacyBuiltInBypassed​(String builtInName) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Tells if a string built-in that can't handle a `TemplateMarkupOutputModel` left hand operand can bypass this object as is. A typical such case would be when a `TemplateHTMLOutputModel` of "HTML" format bypasses `?html`.
    Specified by:
      `isLegacyBuiltInBypassed` in class `MarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### isAutoEscapedByDefault

    public boolean isAutoEscapedByDefault()
    Description copied from class: `MarkupOutputFormat`
    Tells if by default auto-escaping should be on for this format. It should be `true` if you need to escape on most of the places where you insert values.
    Overrides:
      `isAutoEscapedByDefault` in class `CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    See Also:
      `Configuration.setAutoEscapingPolicy(int)`

  - ### isOutputFormatMixingAllowed

    public boolean isOutputFormatMixingAllowed()
    Description copied from class: `OutputFormat`
    Tells if this output format allows inserting `TemplateMarkupOutputModel`-s of another output formats into it.

    If `true`, the foreign `TemplateMarkupOutputModel` will be inserted into the output. If the current output format is a `MarkupOutputFormat` this is done using the `MarkupOutputFormat.outputForeign(TemplateMarkupOutputModel, Writer)` method, which can implement smart conversions. The default behavior (and the only behavior for non-markup outputs) is to behave as if the surrounding output format was the same; this is usually a bad idea to allow, as such an event could indicate application bugs.

    If this method returns `false` (recommended), then FreeMarker will try to assimilate the inserted value by converting its format to this format, which will currently (2.3.24) cause exception, unless the inserted value is made by escaping plain text and the target format is non-escaping, in which case format conversion is trivially possible. (It's not impossible that conversions will be extended beyond this, if there will be demand for that.)

    `true` value is used by `UndefinedOutputFormat`.

    Overrides:
      `isOutputFormatMixingAllowed` in class `CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>`

  - ### getOuterOutputFormat

    public MarkupOutputFormat getOuterOutputFormat()

  - ### getInnerOutputFormat

    public MarkupOutputFormat getInnerOutputFormat()

  - ### newTemplateMarkupOutputModel

    protected TemplateCombinedMarkupOutputModel newTemplateMarkupOutputModel​(String plainTextContent, String markupContent)
    Description copied from class: `CommonMarkupOutputFormat`
    Creates a new `CommonTemplateMarkupOutputModel` that's bound to this `OutputFormat` instance. When this is called from `CommonMarkupOutputFormat`, exactly one of the parameters will be non-`null`.
    Specified by:
      `newTemplateMarkupOutputModel` in class `CommonMarkupOutputFormat<TemplateCombinedMarkupOutputModel>`
    Parameters:
      `plainTextContent` - `null` if the content is markup that possibly can be described as plain text without loss.
      `markupContent` - Typically will be `null` if `plainTextContent` is not `null`. While the plain text always can be converted to markup via `MarkupOutputFormat.escapePlainText(String)`, it's up to the implementation if it wants to do that now and store the markup, or later on demand (like each time when `CommonMarkupOutputFormat.getMarkupString(CommonTemplateMarkupOutputModel)` is called).