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