001/*
002 * This library is part of OpenCms -
003 * the Open Source Content Management System
004 *
005 * Copyright (c) Alkacon Software GmbH & Co. KG (http://www.alkacon.com)
006 *
007 * This library is free software; you can redistribute it and/or
008 * modify it under the terms of the GNU Lesser General Public
009 * License as published by the Free Software Foundation; either
010 * version 2.1 of the License, or (at your option) any later version.
011 *
012 * This library is distributed in the hope that it will be useful,
013 * but WITHOUT ANY WARRANTY; without even the implied warranty of
014 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015 * Lesser General Public License for more details.
016 *
017 * For further information about Alkacon Software GmbH & Co. KG, please see the
018 * company website: http://www.alkacon.com
019 *
020 * For further information about OpenCms, please see the
021 * project website: http://www.opencms.org
022 *
023 * You should have received a copy of the GNU Lesser General Public
024 * License along with this library; if not, write to the Free Software
025 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
026 */
027
028package org.opencms.widgets;
029
030import org.opencms.file.CmsObject;
031
032import java.util.Map;
033
034/**
035 * Describes an editor widget for use in the OpenCms workplace.<p>
036 *
037 * @since 6.0.0
038 */
039public interface I_CmsWidget {
040
041    /**
042     * Returns the configuration string.<p>
043     *
044     * This can be used to enable / disable certain widget features that should not always be available,
045     * or to pass specific initialization information to the widget.
046     * It depends on the widget implementation on how this information is used.<p>
047     *
048     * @return the configuration string
049     */
050    String getConfiguration();
051
052    /**
053     * Generates the html to include at the end of the dialog for this widget.<p>
054     *
055     * The "help bubble" text div's are added using this method.<p>
056     *
057     * @param cms the current users OpenCms context
058     * @param widgetDialog the dialog where the widget is used on
059     * @param param the widget parameter to generate the widget for
060     *
061     * @return the html to include at the end of the dialog for this widget
062     */
063    String getDialogHtmlEnd(CmsObject cms, I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter param);
064
065    /**
066     * Generates the necessary JavaScript inclusion code for this widget.<p>
067     *
068     * @param cms the current users OpenCms context
069     * @param widgetDialog the dialog where the widget is used on
070     *
071     * @return the JavaScript inclusion code
072     */
073    String getDialogIncludes(CmsObject cms, I_CmsWidgetDialog widgetDialog);
074
075    /**
076     * Generates the initialisation method JavaScript code for this widget.<p>
077     *
078     * @param cms the current users OpenCms context
079     * @param widgetDialog the dialog where the widget is used on
080     *
081     * @return the initialisation method JavaScript code
082     */
083    String getDialogInitCall(CmsObject cms, I_CmsWidgetDialog widgetDialog);
084
085    /**
086     * Generates the initialization method JavaScript code for this widget.<p>
087     *
088     * @param cms an initialized instance of a CmsObject
089     * @param widgetDialog the dialog where the widget is used on
090     *
091     * @return the initialization method JavaScript code
092     */
093    String getDialogInitMethod(CmsObject cms, I_CmsWidgetDialog widgetDialog);
094
095    /**
096     * Generates the widget HTML for the provided widget parameter.<p>
097     *
098     * @param cms an initialized instance of a CmsObject
099     * @param widgetDialog the dialog where the widget is used on
100     * @param param the widget parameter to generate the widget for
101     *
102     * @return the widget HTML for the provided widget parameter
103     */
104    String getDialogWidget(CmsObject cms, I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter param);
105
106    /**
107     * Creates the HTML code for the help bubble for this widget.<p>
108     *
109     * @param cms the current users OpenCms context
110     * @param widgetDialog the dialog where the widget is used on
111     * @param param the widget parameter to generate the widget for
112     *
113     * @return the HTML code for the help bubble for this widget
114     */
115    String getHelpBubble(CmsObject cms, I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter param);
116
117    /**
118     * Creates a HTML &lt;div&gt; containing the help text for this widget.<p>
119     *
120     * @param widgetDialog the dialog where the widget is used on
121     * @param value the value to create the help bubble for
122     *
123     * @return a HTML &lt;div&gt; containing the help text for this widget
124     */
125    String getHelpText(I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter value);
126
127    /**
128     * Returns the <code>{@link I_CmsWidgetParameter#getStringValue(CmsObject)}</code>
129     * processed according to the output rules of this widget and the given widget dialog.<p>
130     *
131     * @param cms the current users OpenCms context
132     * @param widgetDialog the dialog where the widget is used on
133     * @param param the widget parameter to generate the widget for
134     *
135     * @return the <code>{@link I_CmsWidgetParameter#getStringValue(CmsObject)}</code>
136     *      processed according to the output rules of this widget
137     *
138     * @see I_CmsWidgetParameter#getStringValue(CmsObject)
139     * @see org.opencms.xml.types.I_CmsXmlContentValue#getStringValue(CmsObject)
140     */
141    String getWidgetStringValue(CmsObject cms, I_CmsWidgetDialog widgetDialog, I_CmsWidgetParameter param);
142
143    /**
144     * Returns if the widget is compact view enabled.<p>
145     *
146     * @return <code>true</code> if the widget is compact view enabled
147     */
148    boolean isCompactViewEnabled();
149
150    /**
151     * Creates a duplicate of this widget instance.<p>
152     *
153     * @return a duplicate of this widget instance
154     */
155    I_CmsWidget newInstance();
156
157    /**
158     * Sets the configuration of this widget.<p>
159     *
160     * This can be used to enable / disable certain widget features that should not always be available,
161     * or to pass specific initialization information to the widget.
162     * It depends on the widget implementation on how this information is used.<p>
163     *
164     * @param configuration the configuration to set
165     */
166    void setConfiguration(String configuration);
167
168    /**
169     * Sets the value of in the given widget parameter by reading the "right"
170     * value from the offered map of parameters.<p>
171     *
172     * @param cms the current users OpenCms context
173     * @param formParameters the map of parameters to get the value from
174     * @param widgetDialog the dialog where the widget is used on
175     * @param param the widget parameter to generate the widget for
176     */
177    void setEditorValue(
178        CmsObject cms,
179        Map<String, String[]> formParameters,
180        I_CmsWidgetDialog widgetDialog,
181        I_CmsWidgetParameter param);
182}