001    /**
002     * Copyright (c) 2000-present Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portal.kernel.editor.configuration;
016    
017    import com.liferay.portal.theme.ThemeDisplay;
018    import com.liferay.portlet.RequestBackedPortletURLFactory;
019    
020    import java.util.Map;
021    
022    /**
023     * Provides an interface for setting the editor's options. Editor configuration
024     * can be set using {@link EditorConfigContributor}.
025     *
026     * <p>
027     * This interface facilitates configuring options at a higher level than using
028     * {@link EditorConfigContributor}. The former requires knowledge about the
029     * editor internals, while the latter is more versatile in terms of
030     * customization.
031     * </p>
032     *
033     * <p>
034     * The options specified through this interface are not tied to any particular
035     * editor implementation. A {@link EditorConfigTransformer} transforms these
036     * high level options to a low level configuration object.
037     * </p>
038     *
039     * <p>
040     * Implementations must be OSGi components that are registered in the OSGi
041     * Registry.
042     * </p>
043     *
044     * <p>
045     * The options can be targeted for specific editors, based on three criteria:
046     * portlet name, editor config key, and editor name. These criteria can be
047     * defined as OSGi properties with the following names:
048     * </p>
049     *
050     * <ul>
051     * <li>
052     * <code>javax.portlet.name</code>: The portlet name. If specified, the
053     * options are applied to every editor used in that portlet.
054     * </li>
055     * <li>
056     * <code>editor.config.key</code>: The key used to identify the editor (the
057     * <code>input-editor</code> taglib tag's <code>configKey</code> attribute
058     * value). If specified, the options are applied to every editor with the
059     * specified <code>configKey</code>.
060     * </li>
061     * <li>
062     * <code>editor.name</code>: The name of the editor (the
063     * <code>input-editor</code> taglib tag's <code>editorName</code> attribute
064     * value: <code>ckeditor</code>, <code>ckeditor_bbcode</code>,
065     * <code>alloyeditor</code>, etc.). If specified, the options are applied to
066     * every editor with that name.
067     * </li>
068     * </ul>
069     *
070     * <p>
071     * In case there's more than one options contributor, they're prioritized by the
072     * following criteria combinations (the lower the criteria's number, the higher
073     * it's prioritized):
074     * </p>
075     *
076     * <ol>
077     * <li>
078     * portlet name, editor config key, editor name
079     * </li>
080     * <li>
081     * portlet name, editor config key
082     * </li>
083     * <li>
084     * editor config key, editor name
085     * </li>
086     * <li>
087     * portlet name, editor name
088     * </li>
089     * <li>
090     * editor config key
091     * </li>
092     * <li>
093     * portlet name
094     * </li>
095     * <li>
096     * editor name
097     * </li>
098     * <li>
099     * empty
100     * </li>
101     * </ol>
102     *
103     * <p>
104     * If there are multiple contributors with the same criteria elements, they're
105     * prioritized by service rank.
106     * </p>
107     *
108     * @author Sergio Gonz??lez
109     */
110    public interface EditorOptionsContributor {
111    
112            /**
113             * Updates the original {@link EditorOptions} object with new options. It
114             * can even update or delete the original options, or any other options
115             * introduced by any other {@link EditorOptionsContributor}.
116             *
117             * <p>
118             * The editor options object contains the options to be transformed by the
119             * Editor Config Transformer to a configuration JSON object.
120             * </p>
121             *
122             * @param editorOptions the original {@link EditorOptions} object containing
123             *        the options set by {@link EditorOptionsContributor} modules
124             * @param inputEditorTaglibAttributes the attributes specified to the input
125             *        taglib tag that renders the editor
126             * @param themeDisplay the theme display
127             */
128            public void populateEditorOptions(
129                    EditorOptions editorOptions,
130                    Map<String, Object> inputEditorTaglibAttributes,
131                    ThemeDisplay themeDisplay,
132                    RequestBackedPortletURLFactory requestBackedPortletURLFactory);
133    
134    }