001/*
002 * (C) Copyright 2006-2007 Nuxeo SAS (http://nuxeo.com/) and contributors.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the GNU Lesser General Public License
006 * (LGPL) version 2.1 which accompanies this distribution, and is available at
007 * http://www.gnu.org/licenses/lgpl.html
008 *
009 * This library is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012 * Lesser General Public License for more details.
013 *
014 * Contributors:
015 *     <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
016 *
017 * $Id: WidgetDefinition.java 28498 2008-01-05 11:46:25Z sfermigier $
018 */
019
020package org.nuxeo.ecm.platform.forms.layout.api;
021
022import java.io.Serializable;
023import java.util.List;
024import java.util.Map;
025
026/**
027 * Widget definition interface.
028 * <p>
029 * A widget knows how to render itself in a given mode.
030 *
031 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
032 */
033public interface WidgetDefinition extends Serializable {
034
035    String RENDERED_PROPERTY_NAME = "rendered";
036
037    String REQUIRED_PROPERTY_NAME = "required";
038
039    /**
040     * Returns the widget name used to identify it within a layout.
041     */
042    String getName();
043
044    /**
045     * @since 5.5
046     */
047    void setName(String name);
048
049    /**
050     * Returns the widget type used to render it.
051     */
052    String getType();
053
054    /**
055     * @since 5.5
056     */
057    void setType(String type);
058
059    /**
060     * Returns the type category to use when retrieving the corresponding widget type.
061     *
062     * @since 5.7.3
063     */
064    String getTypeCategory();
065
066    /**
067     * Sets the type category to use when retrieving the corresponding widget type.
068     *
069     * @since 5.7.3
070     */
071    void setTypeCategory(String typeCat);
072
073    /**
074     * Returns the list of fields managed by this widget.
075     */
076    FieldDefinition[] getFieldDefinitions();
077
078    /**
079     * @since 5.5
080     */
081    void setFieldDefinitions(FieldDefinition[] fieldDefinitions);
082
083    /**
084     * Returns the optional mode used to override the layout mode.
085     * <p>
086     * Can be a string or an EL ValueExpression.
087     *
088     * @param layoutMode the layout (or parent widget) mode
089     * @return the overriding widget mode or null if none is defined.
090     */
091    String getMode(String layoutMode);
092
093    Map<String, String> getModes();
094
095    /**
096     * @since 5.5
097     */
098    void setModes(Map<String, String> modes);
099
100    /**
101     * Returns an EL expression evaluating to true if the widget is required in given mode.
102     * <p>
103     * This value is computed from the property "required" in given mode. and can be a string or an EL ValueExpression.
104     * Defaults to "false".
105     */
106    String getRequired(String layoutMode, String mode);
107
108    /**
109     * Returns the label to use in a given mode.
110     */
111    String getLabel(String mode);
112
113    /**
114     * Returns labels by mode.
115     */
116    Map<String, String> getLabels();
117
118    /**
119     * @since 5.5
120     */
121    void setLabels(Map<String, String> labels);
122
123    /**
124     * Returns the help label to use in a given mode.
125     */
126    String getHelpLabel(String mode);
127
128    /**
129     * Returns help labels by mode.
130     */
131    Map<String, String> getHelpLabels();
132
133    /**
134     * @since 5.5
135     */
136    void setHelpLabels(Map<String, String> helpLabels);
137
138    /**
139     * Returns true if all labels are messages that need to be translated.
140     * <p>
141     * Defaults to true.
142     */
143    boolean isTranslated();
144
145    /**
146     * @since 5.5
147     * @see #isTranslated()
148     */
149    void setTranslated(boolean translated);
150
151    /**
152     * Returns true if the widget is handling his own labels display (usual label and help label). This can be checked
153     * by the layout template to render the widget using both label and widget usual places.
154     * <p>
155     * Defaults to false.
156     *
157     * @since 5.6
158     * @deprecated since 5.7: this was added prematurely, see {@link #getControls()} for a more generic management of
159     *             rendering controls
160     */
161    @Deprecated
162    boolean isHandlingLabels();
163
164    /**
165     * @since 5.6
166     * @see #isHandlingLabels()
167     * @deprecated since 5.7: this was added prematurely, see {@link #setControls()} for a more generic management of
168     *             rendering controls
169     */
170    @Deprecated
171    void setHandlingLabels(boolean handlingLabels);
172
173    /**
174     * Returns a map of properties to use in a given mode.
175     * <p>
176     * A property value can be a string or an EL ValueExpression.
177     * <p>
178     * The way that properties will be mapped to rendered components is managed by the widget type.
179     */
180    Map<String, Serializable> getProperties(String layoutMode, String mode);
181
182    /**
183     * Returns properties by mode.
184     */
185    Map<String, Map<String, Serializable>> getProperties();
186
187    /**
188     * @since 5.5
189     */
190    void setProperties(Map<String, Map<String, Serializable>> properties);
191
192    /**
193     * Returns properties by widget mode.
194     */
195    Map<String, Map<String, Serializable>> getWidgetModeProperties();
196
197    /**
198     * @since 5.5
199     */
200    void setWidgetModeProperties(Map<String, Map<String, Serializable>> properties);
201
202    /**
203     * Returns controls for given mode.
204     *
205     * @since 5.7
206     * @see #getControls()
207     */
208    Map<String, Serializable> getControls(String layoutMode, String mode);
209
210    /**
211     * Returns controls by mode.
212     * <p>
213     * Controls are property-like markers on widget instances, expect these are not forwarded to the underlying
214     * rendering object (like the JSF component attributes).
215     * <p>
216     * This makes it possible to keep "flags" on widgets that can be checked by parent widget or layout, for instance
217     * "addForm" or "handlingLabels" markers.
218     *
219     * @since 5.7
220     */
221    Map<String, Map<String, Serializable>> getControls();
222
223    /**
224     * Sets controls by mode on widget definition.
225     *
226     * @since 5.7
227     */
228    void setControls(Map<String, Map<String, Serializable>> controls);
229
230    /**
231     * Returns sub widget definitions.
232     */
233    WidgetDefinition[] getSubWidgetDefinitions();
234
235    /**
236     * @since 5.5
237     */
238    void setSubWidgetDefinitions(WidgetDefinition[] subWidgets);
239
240    /**
241     * Returns sub widget definitions references.
242     *
243     * @since 5.6
244     */
245    WidgetReference[] getSubWidgetReferences();
246
247    /**
248     * @since 5.6
249     */
250    void setSubWidgetReferences(WidgetReference[] subWidgets);
251
252    /**
253     * Returns the select options for this widget.
254     *
255     * @since 5.4.2
256     */
257    WidgetSelectOption[] getSelectOptions();
258
259    /**
260     * @since 5.5
261     */
262    void setSelectOptions(WidgetSelectOption[] selectOptions);
263
264    /**
265     * Returns the map of rendering information per mode.
266     * <p>
267     * Useful for preview management where some configuration needs to be changed: what's changed can be set as
268     * rendering information here to be displayed.
269     *
270     * @since 5.5
271     */
272    Map<String, List<RenderingInfo>> getRenderingInfos();
273
274    /**
275     * Returns the list of rendering information for given mode.
276     *
277     * @since 5.5
278     */
279    List<RenderingInfo> getRenderingInfos(String mode);
280
281    /**
282     * @since 5.5
283     */
284    void setRenderingInfos(Map<String, List<RenderingInfo>> renderingInfos);
285
286    /**
287     * Return alias names for this widget definition (useful for compatibility on old widget names).
288     *
289     * @since 6.0
290     */
291    List<String> getAliases();
292
293    /**
294     * Returns true if the widget is defined globally (as opposed to being held by a layout definition).
295     *
296     * @since 6.0
297     */
298    boolean isGlobal();
299
300    /**
301     * Sets the global status on this definition, depending on how it's been retrievd by the service.
302     *
303     * @since 6.0
304     */
305    void setGlobal(boolean global);
306
307    /**
308     * Returns true if this widget was generated from configuration on a service, and not generated on-the-fly using
309     * dynamic behaviors.
310     *
311     * @since 6.0
312     */
313    boolean isDynamic();
314
315    /**
316     * Returns a clone instance of this widget definition.
317     * <p>
318     * Useful for conversion of widget definition during export.
319     *
320     * @since 5.5
321     */
322    WidgetDefinition clone();
323
324}