com.smartgwt.client.widgets.form.fields
Class UploadItem

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by com.smartgwt.client.core.RefDataClass
              extended by com.smartgwt.client.widgets.form.fields.FormItem
                  extended by com.smartgwt.client.widgets.form.fields.TextItem
                      extended by com.smartgwt.client.widgets.form.fields.UploadItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPickerIconClickHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers

public class UploadItem
extends TextItem

FormItem that creates an HTML <input type="file"> control, with an interface that allows a user to pick a file from his machine to upload to the server.

NOTE: use FileItem, not UploadItem, if you are using the Smart GWT Server framework. FileItem is much easier to use and addresses all the limitations of UploadItem discussed below. See the Uploading Files overview for details.

If a form containing an UploadItem is redrawn (which may happen if other form items are shown or hidden, the form is resized, or other items show validation errors) then the value in the upload item is lost (because an HTML upload field may not be created with a value). For this reason, if you are building a form that combines an UploadItem with other FormItems that could trigger redraw()s, recommended practice is to place each UploadItem in a distinct DynamicForm instance and create the visual appearance of a single logical form via combining the DynamicForms in a Layout.

NOTE: Browser-specific behaviors:

See Also:
Upload overview and related methods

Field Summary
 
Fields inherited from class com.smartgwt.client.widgets.form.fields.FormItem
scClassName
 
Fields inherited from class com.smartgwt.client.core.RefDataClass
id
 
Fields inherited from class com.smartgwt.client.core.JsObject
jsObj
 
Constructor Summary
UploadItem()
           
UploadItem(JavaScriptObject jsObj)
           
UploadItem(String name)
           
UploadItem(String name, String title)
           
 
Method Summary
static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
          Changes the defaults for Canvas AutoChildren named autoChildName.
static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
          Changes the defaults for FormItem AutoChildren named autoChildName.
static void changePickerIconDefaults(FormItemIcon defaults)
           
 String getAccept()
          A comma-separated list of valid MIME types, used as a filter for the file picker window.
 int getHeight()
          Height for this uploadItem.
 Boolean getMultiple()
          When true, allow the file-selection dialog shelled by the browser to select multiple files.
static UploadItem getOrCreateRef(JavaScriptObject jsObj)
           
 int getWidth()
          Width for this uploadItem.
 void setAccept(String accept)
          A comma-separated list of valid MIME types, used as a filter for the file picker window.
static void setDefaultProperties(UploadItem uploadItemProperties)
          Class level method to set the default properties of this class.
 void setHeight(int height)
          Height for this uploadItem.
 void setMultiple(Boolean multiple)
          When true, allow the file-selection dialog shelled by the browser to select multiple files.
 void setValue()
          Attempting to set the value for an upload form item is disallowed for security reasons.
 void setWidth(int width)
          Width for this uploadItem.
 
Methods inherited from class com.smartgwt.client.widgets.form.fields.TextItem
deselectValue, deselectValue, getBrowserAutoCapitalize, getBrowserAutoCorrect, getBrowserInputType, getChangeOnKeypress, getCharacterCasing, getEnteredValue, getFormatOnBlur, getFormatOnFocusChange, getHint, getKeyPressFilter, getLength, getMask, getMaskOverwriteMode, getMaskPadChar, getMaskPromptChar, getMaskSaveLiterals, getPrintFullText, getSaveOnEnter, getSelectionRange, getSelectOnClick, getSelectOnFocus, getShowHintInField, getTextBoxStyle, getValueAsString, selectValue, setBrowserAutoCapitalize, setBrowserAutoCorrect, setBrowserInputType, setChangeOnKeypress, setCharacterCasing, setDefaultProperties, setFormatOnBlur, setFormatOnFocusChange, setKeyPressFilter, setLength, setMask, setMaskOverwriteMode, setMaskPadChar, setMaskPromptChar, setMaskSaveLiterals, setPrintFullText, setSaveOnEnter, setSelectionRange, setSelectOnClick, setSelectOnFocus, setShowHintInField, setTextBoxStyle
 
Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem
_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPickerIconClickHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, asSGWTComponent, blurItem, canEditCriterion, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getBrowserSpellCheck, getCanEdit, getCanFocus, getCanvasAutoChild, getCellHeight, getCellStyle, getClassName, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDisabled, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getExportFormat, getFetchMissingValues, getFieldName, getFilterLocally, getForm, getFormat, getFormItemAutoChild, getFullDataPath, getGlobalTabIndex, getHeightAsString, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIcon, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLoadingDisplayValue, getLocateItemBy, getMultipleValueSeparator, getName, getOperator, getOptionCriteria, getOptionFilterContext, getOptionOperationId, getPageLeft, getPageRect, getPageTop, getPicker, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintTextBoxStyle, getPrintTitleStyle, getPrompt, getReadOnlyClipValue, getReadOnlyDisplay, getReadOnlyTextBoxStyle, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getScClassName, getSelectedRecord, getShouldSaveValue, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowPickerIcon, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStopOnError, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsRecordList, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getVisibleHeight, getVisibleWidth, getWidthAsString, getWrapTitle, hasAdvancedCriteria, hide, hideIcon, invalidateDisplayValueCache, isCreated, isDisabled, isDrawn, isVisible, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setBrowserSpellCheck, setCanEdit, setCanEditCriterionPredicate, setCanFocus, setCellHeight, setCellStyle, setClipTitle, setColSpan, setColSpan, setControlStyle, setCriteriaField, setCriterion, setCriterionGetter, setCriterionSetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisableIconsOnReadOnly, setDisplayField, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setExportFormat, setFetchMissingValues, setFilterLocally, setFormat, setGlobalTabIndex, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setLeft, setLoadingDisplayValue, setLocateItemBy, setMultipleValueSeparator, setName, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setPrompt, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyClipValue, setReadOnlyDisplay, setReadOnlyTextBoxStyle, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setScClassName, setShouldSaveValue, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowPickerIcon, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStopOnError, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueField, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, show, showIcon, showPicker, stopHover, storeValue, storeValue, updateState, validate, valueClipped
 
Methods inherited from class com.smartgwt.client.core.RefDataClass
getRef, getRef, internalSetID
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject
 
Methods inherited from class com.smartgwt.client.core.JsObject
equals, getJsObj, hashCode, setJavaScriptObject, setJsObj
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

UploadItem

public UploadItem()

UploadItem

public UploadItem(JavaScriptObject jsObj)

UploadItem

public UploadItem(String name)

UploadItem

public UploadItem(String name,
                  String title)
Method Detail

getOrCreateRef

public static UploadItem getOrCreateRef(JavaScriptObject jsObj)

changeAutoChildDefaults

public static void changeAutoChildDefaults(String autoChildName,
                                           Canvas defaults)
Changes the defaults for Canvas AutoChildren named autoChildName.

Parameters:
autoChildName - name of an AutoChild to customize the defaults for.
defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties.
See Also:
AutoChildUsage

changeAutoChildDefaults

public static void changeAutoChildDefaults(String autoChildName,
                                           FormItem defaults)
Changes the defaults for FormItem AutoChildren named autoChildName.

Parameters:
autoChildName - name of an AutoChild to customize the defaults for.
defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties.
See Also:
AutoChildUsage

changePickerIconDefaults

public static void changePickerIconDefaults(FormItemIcon defaults)

setAccept

public void setAccept(String accept)
A comma-separated list of valid MIME types, used as a filter for the file picker window.

Parameters:
accept - Default value is null

getAccept

public String getAccept()
A comma-separated list of valid MIME types, used as a filter for the file picker window.

Returns:
String

setHeight

public void setHeight(int height)
Height for this uploadItem. Note that Smart GWT will not apply this size to the native HTML <input ...> element written out by this formItem as this leads to inconsistent appearance across different browsers. The specified height acts as a minimum cell width for the item.

Overrides:
setHeight in class FormItem
Parameters:
height - Default value is 19
See Also:
FormLayout overview and related methods, Filling Example

getHeight

public int getHeight()
Height for this uploadItem. Note that Smart GWT will not apply this size to the native HTML <input ...> element written out by this formItem as this leads to inconsistent appearance across different browsers. The specified height acts as a minimum cell width for the item.

Overrides:
getHeight in class FormItem
Returns:
int
See Also:
FormLayout overview and related methods, Filling Example

setMultiple

public void setMultiple(Boolean multiple)
When true, allow the file-selection dialog shelled by the browser to select multiple files.

Support is not full-cycle at the server - that is, there are server APIs for retrieving each file that was uploaded, but no built-in support for storing multiple files against a single DataSource field. However, you can write custom server DMI code to do something with the files - for instance, you could create multiple new DataSource records for each file via a server DMI like this below:

     String fileNameStr = (String)dsRequest.getValues().get("image_filename").toString();
 
     String[] fileNames = fileNameStr.split(", ");
     List files = dsRequest.getUploadedFiles();
 
     for (int i = 0; i < files.size(); i++) {
         ISCFileItem file = (ISCFileItem)files.get(i);
         InputStream fileData = file.getInputStream();
         DSRequest inner = new DSRequest("mediaLibrary", "add");
         Map values = new HashMap();
         values.put("title", dsRequest.getValues().get("title"));
         values.put("image", fileData);
         values.put("image_filename", fileNames[i]);
         values.put("image_filesize", file.getSize());
         values.put("image_date_created", new Date());
         
         inner.setValues(values);
         inner.execute();
     }
     
     DSResponse dsResponse = new DSResponse();
     
     dsResponse.setStatus(0);
 
     return dsResponse;
  

Parameters:
multiple - Default value is true

getMultiple

public Boolean getMultiple()
When true, allow the file-selection dialog shelled by the browser to select multiple files.

Support is not full-cycle at the server - that is, there are server APIs for retrieving each file that was uploaded, but no built-in support for storing multiple files against a single DataSource field. However, you can write custom server DMI code to do something with the files - for instance, you could create multiple new DataSource records for each file via a server DMI like this below:

     String fileNameStr = (String)dsRequest.getValues().get("image_filename").toString();
 
     String[] fileNames = fileNameStr.split(", ");
     List files = dsRequest.getUploadedFiles();
 
     for (int i = 0; i < files.size(); i++) {
         ISCFileItem file = (ISCFileItem)files.get(i);
         InputStream fileData = file.getInputStream();
         DSRequest inner = new DSRequest("mediaLibrary", "add");
         Map values = new HashMap();
         values.put("title", dsRequest.getValues().get("title"));
         values.put("image", fileData);
         values.put("image_filename", fileNames[i]);
         values.put("image_filesize", file.getSize());
         values.put("image_date_created", new Date());
         
         inner.setValues(values);
         inner.execute();
     }
     
     DSResponse dsResponse = new DSResponse();
     
     dsResponse.setStatus(0);
 
     return dsResponse;
  

Returns:
Boolean

setWidth

public void setWidth(int width)
Width for this uploadItem. Note that Smart GWT will not apply this size to the native HTML <input ...> element written out by this formItem as this leads to inconsistent appearance across different browsers. The specified width acts as a minimum cell width for the item.

Overrides:
setWidth in class FormItem
Parameters:
width - Default value is 150
See Also:
FormLayout overview and related methods, Spanning Example

getWidth

public int getWidth()
Width for this uploadItem. Note that Smart GWT will not apply this size to the native HTML <input ...> element written out by this formItem as this leads to inconsistent appearance across different browsers. The specified width acts as a minimum cell width for the item.

Overrides:
getWidth in class FormItem
Returns:
int
See Also:
FormLayout overview and related methods, Spanning Example

setValue

public void setValue()
Attempting to set the value for an upload form item is disallowed for security reasons. Therefore this method will just log a warning, and not modify the value of the item.


setDefaultProperties

public static void setDefaultProperties(UploadItem uploadItemProperties)
Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

Parameters:
uploadItemProperties - properties that should be used as new defaults when instances of this class are created