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.kernel.json.JSONObject;
018    import com.liferay.portal.theme.ThemeDisplay;
019    import com.liferay.portlet.RequestBackedPortletURLFactory;
020    
021    import java.util.Map;
022    
023    /**
024     * Provides an interface for setting the editor's configuration. Editor options
025     * can be set using {@link EditorOptionsContributor}.
026     *
027     * <p>
028     * Implementations of this interface are typically specific to a particular
029     * editor, since the configuration JSON object updated here can differ from
030     * those of other editors.
031     * </p>
032     *
033     * <p>
034     * Implementations of this class must be OSGi components that are registered in
035     * the OSGi Registry.
036     * </p>
037     *
038     * <p>
039     * The configuration can be targeted to specific editors, based on three
040     * criteria: portlet name, editor config key, and editor name. These criteria
041     * can be defined as OSGi properties with the following names:
042     * </p>
043     *
044     * <ul>
045     * <li>
046     * <code>javax.portlet.name</code>: The portlet name. If specified, the
047     * configuration populated in the JSON object is applied to every editor used
048     * in that portlet.
049     * </li>
050     * <li>
051     * <code>editor.config.key</code>: The key used to identify the editor (the
052     * <code>input-editor</code> taglib tag's <code>configKey</code> attribute
053     * value). If specified, the configuration populated in the JSON object is
054     * applied to every editor with the specified <code>configKey</code>.
055     * </li>
056     * <li>
057     * <code>editor.name</code>: The name of the editor (the
058     * <code>input-editor</code> taglib tag's <code>editorName</code> attribute
059     * value: <code>ckeditor</code>, <code>ckeditor_bbcode</code>,
060     * <code>alloyeditor</code>, etc.). If specified, the configuration populated in
061     * the JSON object is applied to every editor with that name.
062     * </li>
063     * </ul>
064     *
065     * <p>
066     * In case there's more than one configuration, they're prioritized by the
067     * following criteria combinations (the lower the criteria's number, the higher
068     * it's prioritized):
069     * </p>
070     *
071     * <ol>
072     * <li>
073     * portlet name, editor config key, editor name
074     * </li>
075     * <li>
076     * portlet name, editor config key
077     * </li>
078     * <li>
079     * editor config key, editor name
080     * </li>
081     * <li>
082     * portlet name, editor name
083     * </li>
084     * <li>
085     * editor config key
086     * </li>
087     * <li>
088     * portlet name
089     * </li>
090     * <li>
091     * editor name
092     * </li>
093     * <li>
094     * empty
095     * </li>
096     * </ol>
097     *
098     * <p>
099     * If there are multiple configurations with the same criteria elements, they're
100     * prioritized by service rank.
101     * </p>
102     *
103     * @author Sergio Gonz??lez
104     */
105    public interface EditorConfigContributor {
106    
107            /**
108             * Updates the original configuration JSON object with some new
109             * configuration. It can even update or delete the original configuration,
110             * or any other configuration introduced by any other {@link
111             * EditorConfigContributor}.
112             *
113             * <p>
114             * The configuration object contains the configuration to be directly used
115             * by the editor. The configuration JSON object might, therefore, differ
116             * from other editors.
117             * </p>
118             *
119             * @param jsonObject the original JSON object composed of the entire
120             *        configuration set by {@link EditorConfigContributor} modules
121             * @param inputEditorTaglibAttributes the attributes specified to the input
122             *        taglib tag that renders the editor
123             * @param themeDisplay the theme display
124             */
125            public void populateConfigJSONObject(
126                    JSONObject jsonObject, Map<String, Object> inputEditorTaglibAttributes,
127                    ThemeDisplay themeDisplay,
128                    RequestBackedPortletURLFactory requestBackedPortletURLFactory);
129    
130    }