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

Package freemarker.core

# Class CommonMarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>

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

Direct Known Subclasses:
  `CombinedMarkupOutputFormat`, `HTMLOutputFormat`, `RTFOutputFormat`, `XMLOutputFormat`

public abstract class CommonMarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel> extends MarkupOutputFormat<MO>
Common superclass for implementing `MarkupOutputFormat`-s that use a `CommonTemplateMarkupOutputModel` subclass.

Since:
  2.3.24

- ## Constructor Summary

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

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MO`
  `concat​(MO mo1, MO mo2)`
  Returns a `TemplateMarkupOutputModel` that contains the content of both `TemplateMarkupOutputModel` objects concatenated.
  `MO`
  `fromMarkup​(String markupText)`
  Wraps a `String` that's already markup to `TemplateMarkupOutputModel` interface, to indicate its format.
  `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.
  `String`
  `getMarkupString​(MO mo)`
  Returns the content as markup text; never `null`.
  `String`
  `getSourcePlainText​(MO mo)`
  If this `TemplateMarkupOutputModel` was created with `MarkupOutputFormat.fromPlainTextByEscaping(String)`, it returns the original plain text, otherwise it returns `null`.
  `boolean`
  `isAutoEscapedByDefault()`
  Tells if by default auto-escaping should be on for this format.
  `boolean`
  `isEmpty​(MO mo)`
  Returns if the markup is empty (0 length).
  `boolean`
  `isOutputFormatMixingAllowed()`
  Tells if this output format allows inserting `TemplateMarkupOutputModel`-s of another output formats into it.
  `protected abstract MO`
  `newTemplateMarkupOutputModel​(String plainTextContent, String markupContent)`
  Creates a new `CommonTemplateMarkupOutputModel` that's bound to this `OutputFormat` instance.
  `abstract 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.
  `void`
  `output​(MO mo, Writer out)`
  Prints the parameter model to the output.

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

  `escapePlainText, isLegacyBuiltInBypassed, outputForeign`

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

  `getMimeType, getName, toString, toStringExtraProperties`

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

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

- ## Constructor Details

  - ### CommonMarkupOutputFormat

    protected CommonMarkupOutputFormat()

- ## Method Details

  - ### fromPlainTextByEscaping

    public final MO fromPlainTextByEscaping​(String textToEsc) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    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 `MarkupOutputFormat.output(String, Writer)` as an optimization.
    Specified by:
      `fromPlainTextByEscaping` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`
    See Also:
      `MarkupOutputFormat.escapePlainText(String)`, `MarkupOutputFormat.getSourcePlainText(TemplateMarkupOutputModel)`

  - ### fromMarkup

    public final MO fromMarkup​(String markupText) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    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.)
    Specified by:
      `fromMarkup` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`
    See Also:
      `MarkupOutputFormat.getMarkupString(TemplateMarkupOutputModel)`

  - ### output

    public final void output​(MO mo, Writer out) throws IOException, TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Prints the parameter model to the output.
    Specified by:
      `output` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `IOException`
      `TemplateModelException`

  - ### output

    public abstract 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 `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `IOException`
      `TemplateModelException`

  - ### getSourcePlainText

    public final String getSourcePlainText​(MO mo) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    If this `TemplateMarkupOutputModel` was created with `MarkupOutputFormat.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.
    Specified by:
      `getSourcePlainText` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### getMarkupString

    public final String getMarkupString​(MO mo) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Returns the content as markup text; never `null`. If this `TemplateMarkupOutputModel` was created with `MarkupOutputFormat.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 `MarkupOutputFormat.fromMarkup(String)` and it doesn't yet have the markup, it has to generate the markup now.
    Specified by:
      `getMarkupString` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### concat

    public final MO concat​(MO mo1, MO mo2) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Returns a `TemplateMarkupOutputModel` that contains the content of both `TemplateMarkupOutputModel` objects concatenated.
    Specified by:
      `concat` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### isEmpty

    public boolean isEmpty​(MO mo) throws TemplateModelException
    Description copied from class: `MarkupOutputFormat`
    Returns if the markup is empty (0 length). This is used by at least `?hasContent`.
    Specified by:
      `isEmpty` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    Throws:
      `TemplateModelException`

  - ### 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`.

    Specified by:
      `isOutputFormatMixingAllowed` in class `OutputFormat`

  - ### 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.
    Specified by:
      `isAutoEscapedByDefault` in class `MarkupOutputFormat<MO extends CommonTemplateMarkupOutputModel>`
    See Also:
      `Configuration.setAutoEscapingPolicy(int)`

  - ### newTemplateMarkupOutputModel

    protected abstract MO newTemplateMarkupOutputModel​(String plainTextContent, String markupContent) throws TemplateModelException
    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`.
    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 `getMarkupString(CommonTemplateMarkupOutputModel)` is called).
    Throws:
      `TemplateModelException`