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: Widget.java 26808 2007-11-05 12:00:39Z atchertchian $
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 interface.
030 * <p>
031 * A widget is built from a {@link WidgetDefinition} in a given mode.
032 *
033 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
034 */
035public interface Widget extends Serializable {
036
037    /**
038     * Returns the widget id, unique within the facelet context.
039     */
040    String getId();
041
042    /**
043     * Returns the unique identifier of this widget to be used in tag configuration.
044     *
045     * @since 5.4.2
046     * @see {@link Layout#getTagConfigId()}.
047     */
048    String getTagConfigId();
049
050    /**
051     * Sets the widget id, unique within the facelet context.
052     */
053    void setId(String id);
054
055    /**
056     * Returns the widget name used to identify it within a layout.
057     */
058    String getName();
059
060    /**
061     * Returns the layout name.
062     */
063    String getLayoutName();
064
065    /**
066     * Returns the widget type used to render it.
067     */
068    String getType();
069
070    /**
071     * Returns the widget type category.
072     *
073     * @since 5.7.3
074     */
075    String getTypeCategory();
076
077    /**
078     * Gets the value name used to compute tag attributes.
079     */
080    String getValueName();
081
082    /**
083     * Sets the value name used to compute tag attributes.
084     */
085    void setValueName(String valueName);
086
087    /**
088     * Returns the list of fields managed by this widget.
089     */
090    FieldDefinition[] getFieldDefinitions();
091
092    /**
093     * Returns the widget mode.
094     * <p>
095     * This mode can be different from the layout mode.
096     */
097    String getMode();
098
099    /**
100     * Returns the label to use in this mode.
101     */
102    String getLabel();
103
104    /**
105     * Return the help label to use in this mode.
106     */
107    String getHelpLabel();
108
109    /**
110     * Returns true if all labels are messages that need to be translated.
111     * <p>
112     * Defaults to false.
113     */
114    boolean isTranslated();
115
116    /**
117     * Returns true if the widget is handling his own labels display (usual label and help label). This can be checked
118     * by the layout template to render the widget using both label and widget usual places.
119     * <p>
120     * Defaults to false.
121     *
122     * @since 5.6
123     */
124    boolean isHandlingLabels();
125
126    /**
127     * Get properties to use in this mode.
128     * <p>
129     * The way that properties will be mapped to rendered components is managed by the widget type.
130     */
131    Map<String, Serializable> getProperties();
132
133    /**
134     * Returns property with given name in this mode.
135     *
136     * @param name the property name.
137     * @return the property value or null if not found.
138     */
139    Serializable getProperty(String name);
140
141    /**
142     * Sets property with given name on the layout. If there is already a property with this name on the widget, it will
143     * be overridden.
144     *
145     * @param name the property name.
146     * @param value the property value or null if not found.
147     * @since 5.3.2
148     */
149    void setProperty(String name, Serializable value);
150
151    /**
152     * Returns controls on this widget.
153     *
154     * @since 5.7
155     * @see WidgetDefinition#getControls()
156     */
157    Map<String, Serializable> getControls();
158
159    /**
160     * Returns control with given name.
161     *
162     * @since 5.7
163     * @see WidgetDefinition#getControls()
164     */
165    Serializable getControl(String name);
166
167    /**
168     * Sets control with given name and value.
169     *
170     * @since 5.7
171     * @see WidgetDefinition#getControls()
172     */
173    void setControl(String name, Serializable value);
174
175    /**
176     * Returns true if the widget is required.
177     * <p>
178     * This is a short link for the "required" property, already evaluated from an EL expression (if needed). Defaults
179     * to false.
180     */
181    boolean isRequired();
182
183    /**
184     * Returns sub widgets.
185     */
186    Widget[] getSubWidgets();
187
188    /**
189     * Returns the widget level in the widget hierarchy.
190     * <p>
191     * For instance a standard widget will have a level of 0, and its potential subwidgets will have a level of 1.
192     */
193    int getLevel();
194
195    /**
196     * Returns the select options for this widget.
197     *
198     * @since 5.4.2
199     */
200    WidgetSelectOption[] getSelectOptions();
201
202    /**
203     * Returns the list of rendering information.
204     * <p>
205     * Useful for preview management where some configuration needs to be changed: what's changed can be set as
206     * rendering information here to be displayed.
207     *
208     * @since 5.5
209     */
210    List<RenderingInfo> getRenderingInfos();
211
212    /**
213     * Returns true if the widget is defined globally (as opposed to being held by a layout definition).
214     *
215     * @since 6.0
216     */
217    boolean isGlobal();
218
219    /**
220     * Returns true if this widget was generated from configuration on a service, and not generated on-the-fly using
221     * dynamic behaviors.
222     *
223     * @since 6.0
224     */
225    boolean isDynamic();
226
227    /**
228     * Returns the definition from which this widget instance was generated.
229     * <p>
230     * Useful in dev mode to show the corresponding configuration in the UI.
231     *
232     * @since 6.0
233     */
234    WidgetDefinition getDefinition();
235
236}