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: WebLayoutManager.java 26053 2007-10-16 01:45:43Z atchertchian $
018 */
019
020package org.nuxeo.ecm.platform.forms.layout.service;
021
022import java.io.Serializable;
023import java.util.List;
024import java.util.Map;
025
026import javax.faces.view.facelets.FaceletContext;
027import javax.faces.view.facelets.FaceletHandler;
028import javax.faces.view.facelets.TagConfig;
029
030import org.nuxeo.ecm.platform.forms.layout.api.FieldDefinition;
031import org.nuxeo.ecm.platform.forms.layout.api.Layout;
032import org.nuxeo.ecm.platform.forms.layout.api.LayoutDefinition;
033import org.nuxeo.ecm.platform.forms.layout.api.Widget;
034import org.nuxeo.ecm.platform.forms.layout.api.WidgetDefinition;
035import org.nuxeo.ecm.platform.forms.layout.api.converters.LayoutConversionContext;
036import org.nuxeo.ecm.platform.forms.layout.api.exceptions.WidgetException;
037import org.nuxeo.ecm.platform.forms.layout.api.service.LayoutManager;
038import org.nuxeo.ecm.platform.forms.layout.facelets.WidgetTypeHandler;
039
040/**
041 * Web Layout manager interface.
042 * <p>
043 * It manages registries of layout definitions and widget types and handles the creation of layouts and widgets
044 * instances.
045 *
046 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a>
047 */
048public interface WebLayoutManager extends LayoutManager {
049
050    public static final String JSF_CATEGORY = "jsf";
051
052    /**
053     * Returns the widget type handler for the registered widget type with this type name.
054     * <p>
055     * If the no widget type is found with this name, return null.
056     */
057    WidgetTypeHandler getWidgetTypeHandler(String typeName) throws WidgetException;
058
059    /**
060     * Returns the widget type handler for the registered widget type with this type name and type category.
061     * <p>
062     * If the no widget type is found with this name, return null.
063     *
064     * @since 5.7.3
065     */
066    WidgetTypeHandler getWidgetTypeHandler(String typeCategory, String typeName) throws WidgetException;
067
068    /**
069     * Returns the computed layout for this name and mode in given context, or null if no layout with this name is
070     * found.
071     * <p>
072     * When a widget is configured not to be rendered in this mode, the layout will hold a null value instead. As well,
073     * when a row does not hold any non-null widget in this mode, the layout will not hold it.
074     *
075     * @see #getLayout(FaceletContext, String, String, String, List, boolean)
076     * @param ctx the facelet context this layout will be computed in. If context is null, no expressions can be
077     *            resolved during computing.
078     * @param layoutName the layout definition name.
079     * @param mode the mode.
080     * @param valueName the value name to use when computing tag attributes.
081     * @return a layout computed in this context.
082     */
083    Layout getLayout(FaceletContext ctx, String layoutName, String mode, String valueName);
084
085    /**
086     * Returns the computed layout for this name, mode and list of selected rows in given context, or null if no layout
087     * with this name is found.
088     *
089     * @see LayoutManager#getLayoutDefinition(String)
090     * @see #getLayout(FaceletContext, LayoutDefinition, String, String, List, boolean)
091     * @param layoutName the layout definition name.
092     * @return a layout computed in this context.
093     * @since 5.4
094     */
095    Layout getLayout(FaceletContext ctx, String layoutName, String mode, String valueName, List<String> selectedRows,
096            boolean selectAllRowsByDefault);
097
098    /**
099     * Returns the computed layout for this name, category, mode and list of selected rows in given context, or null if
100     * no layout with this name is found.
101     *
102     * @see LayoutManager#getLayoutDefinition(String)
103     * @see #getLayout(FaceletContext, LayoutDefinition, String, String, List, boolean)
104     * @param layoutName the layout definition name.
105     * @return a layout computed in this context.
106     * @since 5.5
107     */
108    Layout getLayout(FaceletContext ctx, String layoutName, String layoutCategory, String mode, String valueName,
109            List<String> selectedRows, boolean selectAllRowsByDefault);
110
111    /**
112     * Returns the computed layout for this definition, mode and list of selected rows in given context, or null if the
113     * layout definition is null.
114     * <p>
115     * When a widget is configured not to be rendered in this mode, the layout will hold a null value instead. As well,
116     * when a row does not hold any non-null widget in this mode, the layout will not hold it.
117     * <p>
118     * If parameter selectedRows is not null, layout rows will be filtered according to this value. If selectedRows is
119     * null and parameter selectAllRowsByDefault is true, all rows will be taken into account, even rows marked as not
120     * selected by default.
121     *
122     * @param ctx the facelet context this layout will be computed in. If context is null, no expressions can be
123     *            resolved during computing.
124     * @param layoutDef the layout definition instance.
125     * @param mode the mode.
126     * @param valueName the value name to use when computing tag attributes (useful for fields mapping)
127     * @param selectedRows the list of selected rows names
128     * @param selectAllRowsByDefault boolean indicating if all rows should be considered selected by default in case
129     *            parameter selectedRows resolves to null.
130     * @return a layout computed in this context, null if definition is null.
131     * @since 5.4
132     */
133    Layout getLayout(FaceletContext ctx, LayoutDefinition layoutDef, String mode, String valueName,
134            List<String> selectedRows, boolean selectAllRowsByDefault);
135
136    /**
137     * Returns a layout with conversion.
138     *
139     * @since 7.3
140     */
141    Layout getLayout(FaceletContext ctx, LayoutConversionContext lctx, String conversionCat,
142            LayoutDefinition layoutDef, String mode, String valueName, List<String> selectedRows,
143            boolean selectAllRowsByDefault);
144
145    /**
146     * Returns a widget instance given a name and a category, as it would be computed when defined within a layout.
147     *
148     * @since 5.6
149     * @param ctx the facelet context this widget will be computed in. If context is null, no expressions can be
150     *            resolved during computing.
151     * @param widgetName the widget name
152     * @param widgetCategory the widget category
153     * @param layoutMode the pseudo layout mode
154     * @param valueNale the value name to use when computing tag attributes (useful for fields mapping)
155     * @param layoutName the pseudo layout name (if any)
156     * @return the widget instance, or null if widget definition could not be resolved.
157     */
158    Widget getWidget(FaceletContext ctx, String widgetName, String widgetCategory, String layoutMode, String valueName,
159            String layoutName);
160
161    /**
162     * Returns a widget instance given a name and a category, as it would be computed when defined within a layout.
163     *
164     * @since 5.6
165     * @param ctx the facelet context this widget will be computed in. If context is null, no expressions can be
166     *            resolved during computing.
167     * @param widgetDef the widget definition
168     * @param layoutMode the pseudo layout mode
169     * @param valueName the value name to use when computing tag attributes (useful for fields mapping)
170     * @param layoutName the pseudo layout name (if any)
171     * @return the widget instance, or null if the widget definition is null.
172     */
173    Widget getWidget(FaceletContext ctx, WidgetDefinition widgetDef, String layoutMode, String valueName,
174            String layoutName);
175
176    /**
177     * Returns a widget with conversion.
178     *
179     * @since 7.3
180     */
181    Widget getWidget(FaceletContext ctx, LayoutConversionContext lctx, String conversionCat,
182            WidgetDefinition widgetDef, String layoutMode, String valueName, String layoutName);
183
184    /**
185     * Returns the facelet handler for given widget.
186     *
187     * @param ctx the facelet context.
188     * @param config the tag config, used to hook the handler in the jsf tree.
189     * @param widget the computed widget.
190     * @return a facelet handler.
191     * @deprecated since 5.6: use {@link #getFaceletHandler(FaceletContext, TagConfig, Widget, FaceletHandler)} instead
192     */
193    @Deprecated
194    FaceletHandler getFaceletHandler(FaceletContext ctx, TagConfig config, Widget widget);
195
196    /**
197     * Returns the facelet handler for given widget.
198     *
199     * @param ctx the facelet context.
200     * @param config the tag config, used to hook the handler in the jsf tree.
201     * @param widget the computed widget.
202     * @param nextHandler the next handler in the execution chain
203     * @return a facelet handler.
204     * @since 5.6
205     */
206    FaceletHandler getFaceletHandler(FaceletContext ctx, TagConfig config, Widget widget, FaceletHandler nextHandler);
207
208    /**
209     * Returns a widget computed from given information.
210     *
211     * @param ctx the facelet context this layout will be computed in. If context is null, no expressions can be
212     *            resolved during computing.
213     * @param type the widget type name.
214     * @param mode the mode.
215     * @param valueName the value name to use when computing tag attributes.
216     * @param properties optional properties to use when computing the widget.
217     * @param subWidgets optional sub widgets for this widget.
218     * @return a widget computed in this context.
219     * @see #createWidget(FaceletContext, String, String, String, List, String, String, Boolean, Map, Widget[])
220     */
221    @Deprecated
222    Widget createWidget(FaceletContext ctx, String type, String mode, String valueName,
223            Map<String, Serializable> properties, Widget[] subWidgets);
224
225    /**
226     * Returns a widget computed from given information.
227     *
228     * @param ctx the facelet context this layout will be computed in. If context is null, no expressions can be
229     *            resolved during computing.
230     * @param type the widget type name.
231     * @param category the widget type category.
232     * @param mode the mode.
233     * @param valueName the value name to use when computing tag attributes.
234     * @param fieldDefinitions
235     * @param label the widget label
236     * @param helpLabel the widget help label
237     * @param translated if true, the labels will be translated
238     * @param properties optional properties to use when computing the widget.
239     * @param subWidgets optional sub widgets for this widget.
240     * @return a widget computed in this context.
241     * @since 5.4
242     */
243    Widget createWidget(FaceletContext ctx, String type, String mode, String valueName,
244            List<FieldDefinition> fieldDefinitions, String label, String helpLabel, Boolean translated,
245            Map<String, Serializable> properties, Widget[] subWidgets);
246
247    /**
248     * Returns a widget computed from given information.
249     *
250     * @param ctx the facelet context this layout will be computed in. If context is null, no expressions can be
251     *            resolved during computing.
252     * @param type the widget type name.
253     * @param category the widget type category.
254     * @param mode the mode.
255     * @param valueName the value name to use when computing tag attributes.
256     * @param fieldDefinitions
257     * @param widgetName the widget name
258     * @param label the widget label
259     * @param helpLabel the widget help label
260     * @param translated if true, the labels will be translated
261     * @param properties optional properties to use when computing the widget.
262     * @param subWidgets optional sub widgets for this widget.
263     * @return a widget computed in this context.
264     * @since 5.7.3
265     */
266    Widget createWidget(FaceletContext ctx, WidgetDefinition widgetDef, String mode, String valueName,
267            Widget[] subWidgets);
268
269    /**
270     * Returns true if property with given name and value should be referenced as a value expression.
271     * <p>
272     * Assumes the widget type is in category #JSF_CATEGORY for backward compatibility.
273     *
274     * @see #referencePropertyAsExpression(String, Serializable, String, String, String)
275     * @since 5.6
276     * @deprecated since 5.7.3, use
277     *             {@link #referencePropertyAsExpression(String, Serializable, String, String, String, String)} instead
278     */
279    @Deprecated
280    boolean referencePropertyAsExpression(String name, Serializable value, String widgetType, String mode,
281            String template);
282
283    /**
284     * Returns true if property with given name and value should be referenced as a value expression.
285     * <p>
286     * Referencing properties as value expressions makes it possible to resolve this value again when reloading
287     * components in ajax for instance, as literal values kept by JSF components are not evaluated again.
288     * <p>
289     * But some components wait for a literal value and do not evaluate value expressions, so their properties should
290     * not be referenced as value expressions. An extension point on the service makes it possible to declare these
291     * properties: by default other properties will be using references.
292     * <p>
293     * This method returns false if it finds a matching disabled property ref for given criteria. If any of the given
294     * parameters are null, this criterion is ignored, and this looks up any matching (and enabled) contribution.
295     *
296     * @since 5.7.3
297     * @param name the property name
298     * @param value the property value
299     * @param widgetType the widget type if any
300     * @param widgetTypeCategory the widget type category if any
301     * @param mode the widget mode if any
302     * @param template the widget template if any
303     */
304    boolean referencePropertyAsExpression(String name, Serializable value, String widgetType,
305            String widgetTypeCategory, String mode, String template);
306
307}