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}