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

An `OutputFormat` 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
`protected` `MarkupOutputFormat()`

### Method Summary

All Methods Instance Methods Abstract Methods
`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 uses 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(MO mo, Writer out)` Prints the parameter model to the output.
`abstract void` `output(String textToEsc, Writer out)` Equivalent to calling `fromPlainTextByEscaping(String)` and then `output(TemplateMarkupOutputModel, Writer)`, but the implementation may uses a more efficient solution.

### 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 Detail

#### MarkupOutputFormat

    protected MarkupOutputFormat()

### Method Detail

#### 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 uses a more efficient solution.

Throws:
  `IOException`
  `TemplateModelException`

#### 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 returns 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 uses 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)`