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