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.ui;
020
021import org.apache.wiki.api.core.Context;
022import org.apache.wiki.api.engine.Initializable;
023import org.apache.wiki.modules.ModuleManager;
024
025import javax.servlet.jsp.PageContext;
026
027
028/**
029 *  Defines an editor manager.  An editor can be added by adding a suitable JSP file under templates/default/editors
030 *  If you want your editor to include any scripts or something, you can simply request it by adding the following in your
031 *  {@code ini/jspwiki_module.xml}:
032 *
033 *  <pre>
034 *  &lt;modules>
035 *   &lt;editor name="myeditor">
036 *       &lt;author>Janne Jalkanen&lt;/author>
037 *       &lt;script>foo.js&lt;/script>
038 *       &lt;stylesheet>foo.css&lt;/stylesheet>
039 *       &lt;path>editors/myeditor.jsp&lt;/path>
040 *   &lt;/editor>
041 *  &lt;/modules>
042 *  </pre>
043 *
044 *  @since 2.4
045 */
046public interface EditorManager extends ModuleManager, Initializable {
047
048    /** The property name for setting the editor. Current value is "jspwiki.editor" - not used anymore: replaced by defaultpref.template.editor */
049    String PROP_EDITORTYPE = "jspwiki.editor";
050
051    /** Parameter for changing editors at run-time */
052    String PARA_EDITOR = "editor";
053
054    /** Known name for the plain wikimarkup editor. */
055    String EDITOR_PLAIN = "plain";
056
057    /** Known name for the preview editor component. */
058    String EDITOR_PREVIEW = "preview";
059
060    /** Known attribute name for storing the user edited text inside a HTTP parameter. */
061    String REQ_EDITEDTEXT = "_editedtext";
062
063    /** Known attribute name for storing the user edited text inside a session or a page context */
064    String ATTR_EDITEDTEXT = REQ_EDITEDTEXT;
065
066    /**
067     *  Returns an editor for the current context.  The editor names are matched in a case insensitive manner.  At the moment, the only
068     *  place that this method looks in is the property file, but in the future this will also look at user preferences.
069     *  <p>
070     *  Determines the editor to use by the following order of conditions:
071     *  1. Editor set in User Preferences
072     *  2. Default Editor set in jspwiki.properties
073     *  <p>
074     *  For the PREVIEW context, this method returns the "preview" editor.
075     *
076     * @param context The context that is chosen.
077     * @return The name of the chosen editor. If no match could be found, will revert to the default "plain" editor.
078     */
079    String getEditorName( Context context );
080
081    /**
082     *  Returns a list of editors as Strings of editor names.
083     *
084     *  @return the list of available editors
085     */
086    String[] getEditorList();
087
088    /**
089     *  Convenience method for getting the path to the editor JSP file.
090     *
091     *  @param context WikiContext from where the editor name is retrieved.
092     *  @return e.g. "editors/plain.jsp"
093     */
094    String getEditorPath( Context context );
095
096    /**
097     *  Convenience function which examines the current context and attempts to figure out whether the edited text is in the HTTP
098     *  request parameters or somewhere in the session.
099     *
100     *  @param ctx the JSP page context
101     *  @return the edited text, if present in the session page context or as a parameter
102     */
103    static String getEditedText( final PageContext ctx ) {
104        String usertext = ctx.getRequest().getParameter( REQ_EDITEDTEXT );
105        if( usertext == null ) {
106            usertext = ( String )ctx.findAttribute( ATTR_EDITEDTEXT );
107        }
108
109        return usertext;
110    }
111
112}