Package hudson.markup

Class MarkupFormatter

java.lang.Object

hudson.model.AbstractDescribableImpl<MarkupFormatter>

hudson.markup.MarkupFormatter

All Implemented Interfaces:

ExtensionPoint, Describable<MarkupFormatter>

Direct Known Subclasses:

EscapedMarkupFormatter

public abstract class MarkupFormatter
extends AbstractDescribableImpl<MarkupFormatter>
implements ExtensionPoint

Generalization of a function that takes text with some markup and converts that to HTML. Such markup is often associated with Wiki.

Use of markup, as opposed to using raw HTML, ensures certain degree of security.

This is an extension point in Hudson, allowing plugins to implement different markup formatters.

Implement the following methods to enable and control CodeMirror syntax highlighting public String getCodeMirrorMode() // return null to disable CodeMirror dynamically public String getCodeMirrorConfig()

Views

This extension point must have a valid config.jelly that feeds the constructor. TODO: allow MarkupFormatter to control the UI that the user uses to edit.

Since:

1.391

Author:

Kohsuke Kawaguchi

See Also:

Jenkins.getMarkupFormatter()

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
MarkupFormatter()

Method Summary

Modifier and Type	Method	Description
org.kohsuke.stapler.HttpResponse	doPreviewDescription(String text)	Generate HTML for preview, using markup formatter.
MarkupFormatterDescriptor	getDescriptor()	By default looks for a nested class (conventionally named DescriptorImpl) implementing Descriptor and marked with Extension.
String	getHelpUrl()	Gets the URL of the help file.
org.kohsuke.stapler.HttpResponse	previewsNowNeedPostForSecurity2153(String text, org.kohsuke.stapler.StaplerRequest req)	Handle GET requests sent to the /previewDescription URL.
String	translate(String markup)
abstract void	translate(String markup, Writer output)	Given the text, converts that to HTML according to whatever markup rules implicit in the implementation class.

Methods inherited from class java.lang.Object

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

Constructor Detail

MarkupFormatter

public MarkupFormatter()

Method Detail

translate

public abstract void translate(@CheckForNull
                               String markup,
                               @NonNull
                               Writer output)
                        throws IOException

Given the text, converts that to HTML according to whatever markup rules implicit in the implementation class.

Multiple threads can call this method concurrently with different inputs.

Parameters:

output - Formatted HTML should be sent to this output.

Throws:

IOException

translate

@NonNull
public final String translate(@CheckForNull
                              String markup)
                       throws IOException

Throws:

IOException

getHelpUrl

public String getHelpUrl()

Gets the URL of the help file. This help will shown next to the text area of the description, and is ideal of describing what the allowed syntax is. By default, we look for colocated help-syntax.html.

Returns:

null If there's no help file.

Since:

1.398

getDescriptor

public MarkupFormatterDescriptor getDescriptor()

Description copied from class: AbstractDescribableImpl

By default looks for a nested class (conventionally named DescriptorImpl) implementing Descriptor and marked with Extension.

Gets the descriptor for this instance.

Descriptor is a singleton for every concrete Describable implementation, so if a.getClass() == b.getClass() then by default a.getDescriptor() == b.getDescriptor() as well. (In rare cases a single implementation class may be used for instances with distinct descriptors.)

Specified by:

getDescriptor in interface Describable<MarkupFormatter>

Overrides:

getDescriptor in class AbstractDescribableImpl<MarkupFormatter>

doPreviewDescription

@POST
public org.kohsuke.stapler.HttpResponse doPreviewDescription(@QueryParameter
                                                             String text)
                                                      throws IOException

Generate HTML for preview, using markup formatter. Can be called from other views.

Throws:

IOException

previewsNowNeedPostForSecurity2153

@GET
@WebMethod(name="previewDescription")
@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
public org.kohsuke.stapler.HttpResponse previewsNowNeedPostForSecurity2153(@QueryParameter
                                                                           String text,
                                                                           org.kohsuke.stapler.StaplerRequest req)
                                                                    throws IOException

Handle GET requests sent to the /previewDescription URL.

Returns:

an HTTP response informing users that requests need to be sent via POST

Throws:

IOException