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