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