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

Package freemarker.core

# Class MarkupOutputFormat<MO extends TemplateMarkupOutputModel>

java.lang.Object
freemarker.core.OutputFormat
freemarker.core.MarkupOutputFormat<MO>

Type Parameters:
  `MO` - The `TemplateMarkupOutputModel` class this output format can deal with.

Direct Known Subclasses:
  `CommonMarkupOutputFormat`

public abstract class MarkupOutputFormat<MO extends TemplateMarkupOutputModel> extends OutputFormat
Superclass of `OutputFormat`-s that represent a "markup" format, which is any format where certain character sequences have special meaning, and thus may need escaping. (Escaping is important for FreeMarker, as typically it has to insert non-markup text from the data-model into the output markup. See also: `Configuration.setOutputFormat(OutputFormat)`.)

A `MarkupOutputFormat` subclass always has a corresponding `TemplateMarkupOutputModel` subclass pair (like `HTMLOutputFormat` has `TemplateHTMLOutputModel`). The `OutputFormat` implements the operations related to `TemplateMarkupOutputModel` objects of that kind, while the `TemplateMarkupOutputModel` only encapsulates the data (the actual markup or text).

To implement a custom output format, you may want to extend `CommonMarkupOutputFormat`.

Since:
  2.3.24

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `MarkupOutputFormat()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract MO`
  `concat​(MO mo1, MO mo2)`
  Returns a `TemplateMarkupOutputModel` that contains the content of both `TemplateMarkupOutputModel` objects concatenated.
  `abstract String`
  `escapePlainText​(String plainTextContent)`
  Should give the same result as `fromPlainTextByEscaping(String)` and then `getMarkupString(TemplateMarkupOutputModel)`, but the implementation may use a more efficient solution.
  `abstract MO`
  `fromMarkup​(String markupText)`
  Wraps a `String` that's already markup to `TemplateMarkupOutputModel` interface, to indicate its format.
  `abstract MO`
  `fromPlainTextByEscaping​(String textToEsc)`
  Converts a `String` that's assumed to be plain text to `TemplateMarkupOutputModel`, by escaping any special characters in the plain text.
  `abstract String`
  `getMarkupString​(MO mo)`
  Returns the content as markup text; never `null`.
  `abstract String`
  `getSourcePlainText​(MO mo)`
  If this `TemplateMarkupOutputModel` was created with `fromPlainTextByEscaping(String)`, it returns the original plain text, otherwise it returns `null`.
  `abstract boolean`
  `isAutoEscapedByDefault()`
  Tells if by default auto-escaping should be on for this format.
  `abstract boolean`
  `isEmpty​(MO mo)`
  Returns if the markup is empty (0 length).
  `abstract 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.
  `abstract void`
  `output​(String textToEsc, Writer out)`
  Equivalent to calling `fromPlainTextByEscaping(String)` and then `output(TemplateMarkupOutputModel, Writer)`, but the implementation may use a more efficient solution.
  `abstract void`
  `output​(MO mo, Writer out)`
  Prints the parameter model to the output.
  `<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.OutputFormat

  `getMimeType, getName, isOutputFormatMixingAllowed, toString, toStringExtraProperties`

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

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

- ## Constructor Details

  - ### MarkupOutputFormat

    protected MarkupOutputFormat()

- ## Method Details

  - ### fromPlainTextByEscaping

    public abstract MO fromPlainTextByEscaping​(String textToEsc) throws TemplateModelException
    Converts a `String` that's assumed to be plain text to `TemplateMarkupOutputModel`, by escaping any special characters in the plain text. This corresponds to `?esc`, or, to outputting with auto-escaping if that wasn't using `output(String, Writer)` as an optimization.
    Throws:
      `TemplateModelException`
    See Also:
      `escapePlainText(String)`, `getSourcePlainText(TemplateMarkupOutputModel)`

  - ### fromMarkup

    public abstract MO fromMarkup​(String markupText) throws TemplateModelException
    Wraps a `String` that's already markup to `TemplateMarkupOutputModel` interface, to indicate its format. This corresponds to `?noEsc`. (This methods is allowed to throw `TemplateModelException` if the parameter markup text is malformed, but it's unlikely that an implementation chooses to parse the parameter until, and if ever, that becomes necessary.)
    Throws:
      `TemplateModelException`
    See Also:
      `getMarkupString(TemplateMarkupOutputModel)`

  - ### output

    public abstract void output​(MO mo, Writer out) throws IOException, TemplateModelException
    Prints the parameter model to the output.
    Throws:
      `IOException`
      `TemplateModelException`

  - ### output

    public abstract void output​(String textToEsc, Writer out) throws IOException, TemplateModelException
    Equivalent to calling `fromPlainTextByEscaping(String)` and then `output(TemplateMarkupOutputModel, Writer)`, but the implementation may use a more efficient solution.
    Throws:
      `IOException`
      `TemplateModelException`

  - ### outputForeign

    public <MO2 extends TemplateMarkupOutputModel<MO2>> void outputForeign​(MO2 mo, Writer out) throws IOException, TemplateModelException
    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.
    Throws:
      `IOException`
      `TemplateModelException`
    Since:
      2.3.32

  - ### getSourcePlainText

    public abstract String getSourcePlainText​(MO mo) throws TemplateModelException
    If this `TemplateMarkupOutputModel` was created with `fromPlainTextByEscaping(String)`, it returns the original plain text, otherwise it returns `null`. Useful for converting between different types of markups, as if the source format can be converted to plain text without loss, then that just has to be re-escaped with the target format to do the conversion.
    Throws:
      `TemplateModelException`

  - ### getMarkupString

    public abstract String getMarkupString​(MO mo) throws TemplateModelException
    Returns the content as markup text; never `null`. If this `TemplateMarkupOutputModel` was created with `fromMarkup(String)`, it might return the original markup text literally, but this is not required as far as the returned markup means the same. If this `TemplateMarkupOutputModel` wasn't created with `fromMarkup(String)` and it doesn't yet have the markup, it has to generate the markup now.
    Throws:
      `TemplateModelException`

  - ### concat

    public abstract MO concat​(MO mo1, MO mo2) throws TemplateModelException
    Returns a `TemplateMarkupOutputModel` that contains the content of both `TemplateMarkupOutputModel` objects concatenated.
    Throws:
      `TemplateModelException`

  - ### escapePlainText

    public abstract String escapePlainText​(String plainTextContent) throws TemplateModelException
    Should give the same result as `fromPlainTextByEscaping(String)` and then `getMarkupString(TemplateMarkupOutputModel)`, but the implementation may use a more efficient solution.
    Throws:
      `TemplateModelException`

  - ### isEmpty

    public abstract boolean isEmpty​(MO mo) throws TemplateModelException
    Returns if the markup is empty (0 length). This is used by at least `?hasContent`.
    Throws:
      `TemplateModelException`

  - ### isLegacyBuiltInBypassed

    public abstract boolean isLegacyBuiltInBypassed​(String builtInName) throws TemplateModelException
    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`.
    Throws:
      `TemplateModelException`

  - ### isAutoEscapedByDefault

    public abstract boolean isAutoEscapedByDefault()
    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.
    See Also:
      `Configuration.setAutoEscapingPolicy(int)`