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: WidgetDefinition.java 28498 2008-01-05 11:46:25Z sfermigier $ 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 definition interface. 028 * <p> 029 * A widget knows how to render itself in a given mode. 030 * 031 * @author <a href="mailto:at@nuxeo.com">Anahide Tchertchian</a> 032 */ 033public interface WidgetDefinition extends Serializable { 034 035 String RENDERED_PROPERTY_NAME = "rendered"; 036 037 String REQUIRED_PROPERTY_NAME = "required"; 038 039 /** 040 * Returns the widget name used to identify it within a layout. 041 */ 042 String getName(); 043 044 /** 045 * @since 5.5 046 */ 047 void setName(String name); 048 049 /** 050 * Returns the widget type used to render it. 051 */ 052 String getType(); 053 054 /** 055 * @since 5.5 056 */ 057 void setType(String type); 058 059 /** 060 * Returns the type category to use when retrieving the corresponding widget type. 061 * 062 * @since 5.7.3 063 */ 064 String getTypeCategory(); 065 066 /** 067 * Sets the type category to use when retrieving the corresponding widget type. 068 * 069 * @since 5.7.3 070 */ 071 void setTypeCategory(String typeCat); 072 073 /** 074 * Returns the list of fields managed by this widget. 075 */ 076 FieldDefinition[] getFieldDefinitions(); 077 078 /** 079 * @since 5.5 080 */ 081 void setFieldDefinitions(FieldDefinition[] fieldDefinitions); 082 083 /** 084 * Returns the optional mode used to override the layout mode. 085 * <p> 086 * Can be a string or an EL ValueExpression. 087 * 088 * @param layoutMode the layout (or parent widget) mode 089 * @return the overriding widget mode or null if none is defined. 090 */ 091 String getMode(String layoutMode); 092 093 Map<String, String> getModes(); 094 095 /** 096 * @since 5.5 097 */ 098 void setModes(Map<String, String> modes); 099 100 /** 101 * Returns an EL expression evaluating to true if the widget is required in given mode. 102 * <p> 103 * This value is computed from the property "required" in given mode. and can be a string or an EL ValueExpression. 104 * Defaults to "false". 105 */ 106 String getRequired(String layoutMode, String mode); 107 108 /** 109 * Returns the label to use in a given mode. 110 */ 111 String getLabel(String mode); 112 113 /** 114 * Returns labels by mode. 115 */ 116 Map<String, String> getLabels(); 117 118 /** 119 * @since 5.5 120 */ 121 void setLabels(Map<String, String> labels); 122 123 /** 124 * Returns the help label to use in a given mode. 125 */ 126 String getHelpLabel(String mode); 127 128 /** 129 * Returns help labels by mode. 130 */ 131 Map<String, String> getHelpLabels(); 132 133 /** 134 * @since 5.5 135 */ 136 void setHelpLabels(Map<String, String> helpLabels); 137 138 /** 139 * Returns true if all labels are messages that need to be translated. 140 * <p> 141 * Defaults to true. 142 */ 143 boolean isTranslated(); 144 145 /** 146 * @since 5.5 147 * @see #isTranslated() 148 */ 149 void setTranslated(boolean translated); 150 151 /** 152 * Returns true if the widget is handling his own labels display (usual label and help label). This can be checked 153 * by the layout template to render the widget using both label and widget usual places. 154 * <p> 155 * Defaults to false. 156 * 157 * @since 5.6 158 * @deprecated since 5.7: this was added prematurely, see {@link #getControls()} for a more generic management of 159 * rendering controls 160 */ 161 @Deprecated 162 boolean isHandlingLabels(); 163 164 /** 165 * @since 5.6 166 * @see #isHandlingLabels() 167 * @deprecated since 5.7: this was added prematurely, see {@link #setControls()} for a more generic management of 168 * rendering controls 169 */ 170 @Deprecated 171 void setHandlingLabels(boolean handlingLabels); 172 173 /** 174 * Returns a map of properties to use in a given mode. 175 * <p> 176 * A property value can be a string or an EL ValueExpression. 177 * <p> 178 * The way that properties will be mapped to rendered components is managed by the widget type. 179 */ 180 Map<String, Serializable> getProperties(String layoutMode, String mode); 181 182 /** 183 * Returns properties by mode. 184 */ 185 Map<String, Map<String, Serializable>> getProperties(); 186 187 /** 188 * @since 5.5 189 */ 190 void setProperties(Map<String, Map<String, Serializable>> properties); 191 192 /** 193 * Returns properties by widget mode. 194 */ 195 Map<String, Map<String, Serializable>> getWidgetModeProperties(); 196 197 /** 198 * @since 5.5 199 */ 200 void setWidgetModeProperties(Map<String, Map<String, Serializable>> properties); 201 202 /** 203 * Returns controls for given mode. 204 * 205 * @since 5.7 206 * @see #getControls() 207 */ 208 Map<String, Serializable> getControls(String layoutMode, String mode); 209 210 /** 211 * Returns controls by mode. 212 * <p> 213 * Controls are property-like markers on widget instances, expect these are not forwarded to the underlying 214 * rendering object (like the JSF component attributes). 215 * <p> 216 * This makes it possible to keep "flags" on widgets that can be checked by parent widget or layout, for instance 217 * "addForm" or "handlingLabels" markers. 218 * 219 * @since 5.7 220 */ 221 Map<String, Map<String, Serializable>> getControls(); 222 223 /** 224 * Sets controls by mode on widget definition. 225 * 226 * @since 5.7 227 */ 228 void setControls(Map<String, Map<String, Serializable>> controls); 229 230 /** 231 * Returns sub widget definitions. 232 */ 233 WidgetDefinition[] getSubWidgetDefinitions(); 234 235 /** 236 * @since 5.5 237 */ 238 void setSubWidgetDefinitions(WidgetDefinition[] subWidgets); 239 240 /** 241 * Returns sub widget definitions references. 242 * 243 * @since 5.6 244 */ 245 WidgetReference[] getSubWidgetReferences(); 246 247 /** 248 * @since 5.6 249 */ 250 void setSubWidgetReferences(WidgetReference[] subWidgets); 251 252 /** 253 * Returns the select options for this widget. 254 * 255 * @since 5.4.2 256 */ 257 WidgetSelectOption[] getSelectOptions(); 258 259 /** 260 * @since 5.5 261 */ 262 void setSelectOptions(WidgetSelectOption[] selectOptions); 263 264 /** 265 * Returns the map of rendering information per mode. 266 * <p> 267 * Useful for preview management where some configuration needs to be changed: what's changed can be set as 268 * rendering information here to be displayed. 269 * 270 * @since 5.5 271 */ 272 Map<String, List<RenderingInfo>> getRenderingInfos(); 273 274 /** 275 * Returns the list of rendering information for given mode. 276 * 277 * @since 5.5 278 */ 279 List<RenderingInfo> getRenderingInfos(String mode); 280 281 /** 282 * @since 5.5 283 */ 284 void setRenderingInfos(Map<String, List<RenderingInfo>> renderingInfos); 285 286 /** 287 * Return alias names for this widget definition (useful for compatibility on old widget names). 288 * 289 * @since 6.0 290 */ 291 List<String> getAliases(); 292 293 /** 294 * Returns true if the widget is defined globally (as opposed to being held by a layout definition). 295 * 296 * @since 6.0 297 */ 298 boolean isGlobal(); 299 300 /** 301 * Sets the global status on this definition, depending on how it's been retrievd by the service. 302 * 303 * @since 6.0 304 */ 305 void setGlobal(boolean global); 306 307 /** 308 * Returns true if this widget was generated from configuration on a service, and not generated on-the-fly using 309 * dynamic behaviors. 310 * 311 * @since 6.0 312 */ 313 boolean isDynamic(); 314 315 /** 316 * Returns a clone instance of this widget definition. 317 * <p> 318 * Useful for conversion of widget definition during export. 319 * 320 * @since 5.5 321 */ 322 WidgetDefinition clone(); 323 324}