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