    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 jakarta.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}