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