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