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)