    001/*
    002    Licensed to the Apache Software Foundation (ASF) under one
    003    or more contributor license agreements.  See the NOTICE file
    004    distributed with this work for additional information
    005    regarding copyright ownership.  The ASF licenses this file
    006    to you under the Apache License, Version 2.0 (the
    007    "License"); you may not use this file except in compliance
    008    with the License.  You may obtain a copy of the License at
    009
    010       http://www.apache.org/licenses/LICENSE-2.0
    011
    012    Unless required by applicable law or agreed to in writing,
    013    software distributed under the License is distributed on an
    014    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    015    KIND, either express or implied.  See the License for the
    016    specific language governing permissions and limitations
    017    under the License.
    018 */
    019package org.apache.wiki.render;
    020
    021import org.apache.logging.log4j.LogManager;
    022import org.apache.wiki.StringTransmutator;
    023import org.apache.wiki.api.core.Context;
    024import org.apache.wiki.api.core.Page;
    025import org.apache.wiki.api.engine.Initializable;
    026import org.apache.wiki.api.engine.RenderApi;
    027import org.apache.wiki.api.providers.PageProvider;
    028import org.apache.wiki.event.WikiEventListener;
    029import org.apache.wiki.modules.InternalModule;
    030import org.apache.wiki.parser.MarkupParser;
    031import org.apache.wiki.parser.WikiDocument;
    032
    033import java.io.IOException;
    034
    035
    036/**
    037 *  This class provides a facade towards the differing rendering routines.  You should use the routines in this manager
    038 *  instead of the ones in Engine, if you don't want the different side effects to occur - such as WikiFilters.
    039 *  <p>
    040 *  This class also manages a rendering cache, i.e. documents are stored between calls. You may control the cache by
    041 *  tweaking the ehcache-jspwiki.xml file.
    042 *  <p>
    043 *
    044 *  @since  2.4
    045 */
    046public interface RenderingManager extends RenderApi, WikiEventListener, InternalModule, Initializable {
    047
    048    /** markup parser property. */
    049    String PROP_PARSER = "jspwiki.renderingManager.markupParser";
    050
    051    /** default renderer property. */
    052    String PROP_RENDERER = "jspwiki.renderingManager.renderer";
    053
    054    /** default wysiwyg renderer property. */
    055    String PROP_WYSIWYG_RENDERER = "jspwiki.renderingManager.renderer.wysiwyg";
    056
    057    String PROP_BEAUTIFYTITLE = "jspwiki.breakTitleWithSpaces";
    058
    059    /**
    060     *  Beautifies the title of the page by appending spaces in suitable places, if the user has so decreed in the properties when
    061     *  constructing this Engine.  However, attachment names are only beautified by the name.
    062     *
    063     *  @param title The title to beautify
    064     *  @return A beautified title (or, if beautification is off, returns the title without modification)
    065     *  @since 1.7.11, moved to PageManager on 2.11.0
    066     */
    067    String beautifyTitle( String title );
    068
    069    /**
    070     *  Beautifies the title of the page by appending non-breaking spaces in suitable places.  This is really suitable only for HTML output,
    071     *  as it uses the &amp;nbsp; -character.
    072     *
    073     *  @param title The title to beautify
    074     *  @return A beautified title.
    075     *  @since 2.1.127
    076     */
    077    String beautifyTitleNoBreak( String title );
    078
    079    /**
    080     *  Returns the wiki Parser
    081     *  @param pagedata the page data
    082     *  @return A MarkupParser instance.
    083     */
    084    MarkupParser getParser( Context context, String pagedata );
    085
    086    /**
    087     *  Returns a cached document, if one is found.
    088     *
    089     * @param context the wiki context
    090     * @param pagedata the page data
    091     * @return the rendered wiki document
    092     */
    093    WikiDocument getRenderedDocument( Context context, String pagedata );
    094
    095    /**
    096     * Returns a WikiRenderer instance, initialized with the given context and doc. The object is an XHTMLRenderer,
    097     * unless overridden in jspwiki.properties with PROP_RENDERER.
    098     *
    099     * @param context The WikiContext
    100     * @param doc The document to render
    101     * @return A WikiRenderer for this document, or null, if no such renderer could be instantiated.
    102     */
    103    WikiRenderer getRenderer( Context context, WikiDocument doc );
    104
    105    /**
    106     * Returns a WikiRenderer instance meant for WYSIWYG editing, initialized with the given
    107     * context and doc. The object is an WysiwygEditingRenderer, unless overridden
    108     * in jspwiki.properties with PROP_WYSIWYG_RENDERER.
    109     *
    110     * @param context The WikiContext
    111     * @param doc The document to render
    112     * @return A WikiRenderer instance meant for WYSIWYG editing, for this document, or null, if no such renderer could be instantiated.
    113     */
    114    WikiRenderer getWysiwygRenderer( Context context, WikiDocument doc );
    115
    116    /**
    117     *  Simply renders a WikiDocument to a String.  This version does not get the document from the cache - in fact, it does
    118     *  not cache the document at all.  This is very useful, if you have something that you want to render outside the caching
    119     *  routines.  Because the cache is based on full pages, and the cache keys are based on names, use this routine if you're
    120     *  rendering anything for yourself.
    121     *
    122     *  @param context The WikiContext to render in
    123     *  @param doc A proper WikiDocument
    124     *  @return Rendered HTML.
    125     *  @throws IOException If the WikiDocument is poorly formed.
    126     */
    127    String getHTML( Context context, WikiDocument doc ) throws IOException;
    128
    129    /**
    130     *  Returns the converted HTML of the page using a different context than the default context.
    131     *
    132     *  @param  context A WikiContext in which you wish to render this page in.
    133     *  @param  page WikiPage reference.
    134     *  @return HTML-rendered version of the page.
    135     */
    136    String getHTML( Context context, Page page );
    137
    138    /**
    139     *  Returns the converted HTML of the page's specific version. The version must be a positive integer, otherwise the current
    140     *  version is returned.
    141     *
    142     *  @param pagename WikiName of the page to convert.
    143     *  @param version Version number to fetch
    144     *  @return HTML-rendered page text.
    145     */
    146    String getHTML( String pagename, int version );
    147
    148    /**
    149     *   Convenience method for rendering, using the default parser and renderer.  Note that you can't use this method
    150     *   to do any arbitrary rendering, as the pagedata MUST be the data from the that the WikiContext refers to - this
    151     *   method caches the HTML internally, and will return the cached version.  If the pagedata is different from what
    152     *   was cached, will re-render and store the pagedata into the internal cache.
    153     *
    154     *   @param context the wiki context
    155     *   @param pagedata the page data
    156     *   @return XHTML data.
    157     */
    158    default String getHTML( final Context context, final String pagedata ) {
    159        try {
    160            final WikiDocument doc = getRenderedDocument( context, pagedata );
    161            return getHTML( context, doc );
    162        } catch( final IOException e ) {
    163            LogManager.getLogger( RenderingManager.class ).error("Unable to parse", e );
    164        }
    165
    166        return null;
    167    }
    168
    169    /**
    170     *  Returns the converted HTML of the page.
    171     *
    172     *  @param page WikiName of the page to convert.
    173     *  @return HTML-rendered version of the page.
    174     */
    175    default String getHTML( final String page ) {
    176        return getHTML( page, PageProvider.LATEST_VERSION );
    177    }
    178
    179    /**
    180     *  Helper method for doing the HTML translation.
    181     *
    182     *  @param context The WikiContext in which to do the conversion
    183     *  @param pagedata The data to render
    184     *  @param localLinkHook Is called whenever a wiki link is found
    185     *  @param extLinkHook   Is called whenever an external link is found
    186     *  @param parseAccessRules Parse the access rules if we encounter them
    187     *  @param justParse Just parses the pagedata, does not actually render.  In this case, this methods an empty string.
    188     *  @return HTML-rendered page text.
    189     */
    190    String textToHTML( Context context,
    191                       String pagedata,
    192                       StringTransmutator localLinkHook,
    193                       StringTransmutator extLinkHook,
    194                       StringTransmutator attLinkHook,
    195                       boolean parseAccessRules,
    196                       boolean justParse );
    197
    198    /**
    199     *  Just convert WikiText to HTML.
    200     *
    201     *  @param context The WikiContext in which to do the conversion
    202     *  @param pagedata The data to render
    203     *  @param localLinkHook Is called whenever a wiki link is found
    204     *  @param extLinkHook   Is called whenever an external link is found
    205     *
    206     *  @return HTML-rendered page text.
    207     */
    208    default String textToHTML( final Context context,
    209                               final String pagedata,
    210                               final StringTransmutator localLinkHook,
    211                               final StringTransmutator extLinkHook ) {
    212        return textToHTML( context, pagedata, localLinkHook, extLinkHook, null, true, false );
    213    }
    214
    215    /**
    216     *  Just convert WikiText to HTML.
    217     *
    218     *  @param context The WikiContext in which to do the conversion
    219     *  @param pagedata The data to render
    220     *  @param localLinkHook Is called whenever a wiki link is found
    221     *  @param extLinkHook   Is called whenever an external link is found
    222     *  @param attLinkHook   Is called whenever an attachment link is found
    223     *  @return HTML-rendered page text.
    224     */
    225    default String textToHTML( final Context context,
    226                               final String pagedata,
    227                               final StringTransmutator localLinkHook,
    228                               final StringTransmutator extLinkHook,
    229                               final StringTransmutator attLinkHook ) {
    230        return textToHTML( context, pagedata, localLinkHook, extLinkHook, attLinkHook, true, false );
    231    }
    232
    233}