Package hudson.markup

Class MarkupFormatter

java.lang.Object
hudson.markup.MarkupFormatter
All Implemented Interfaces:
ExtensionPoint, Describable<MarkupFormatter>
Direct Known Subclasses:
EscapedMarkupFormatter
public abstract class MarkupFormatter extends Object implements Describable<MarkupFormatter>, 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() (JSON snippet without surrounding curly braces, e.g., "mode": "text/css". Historically this allowed invalid JSON, but since TODO it needs to be properly quoted etc.

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:

  • Constructor Details

    • MarkupFormatter

      public MarkupFormatter()

  • Method Details

    • 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 interface: Describable
      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.)

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

      Specified by:
      getDescriptor in interface Describable<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.StaplerRequest2 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