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}