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