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

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.CanvasItem
                      extended by com.smartgwt.client.widgets.form.fields.MultiFileItem
All Implemented Interfaces:
com.google.gwt.event.shared.HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers

public class MultiFileItem
extends CanvasItem

The MultiFileItem provides an interface for a user to save one or more files that are related to a DataSource record, where each file is represented by a record in a related DataSource.

Use MultiFileItem when a record may have one or more files associated with it (such as attachments to an email message) where no information about the files needs to be stored other than the files themselves. If you have several fields associated with each file (such as an uploaded document with a version, comments and processes associated with it), consider instead an ordinary DataSource with on field of type "binary", and using the FileItem for upload.

See the Uploading Files overview for more information on upload.

DataSource Setup

In a relationship sometimes called a "master-detail" relationship, the MultiFileItem stores files in a "detail" DataSource which are related to a "master" DataSource record being edited by the form which contains the MultiFileItem.

To use a MultiFileItem:

An example "detail" DataSource for storing files is shown below. This "detail" DataSource assumes a "master" DataSource with ID "masterRecord" and with a primaryKey field "id".
  
    <DataSource ID="uploadedFiles" serverType="sql">
      <fields>
         <field name="fileId" type="sequence" primaryKey="true" hidden="true"/>
         <field name="masterRecordId" type="number" foreignKey="masterRecord.id" hidden="true"/>
         <field name="file" type="binary" title="File"/>
      </fields>
    </DataSource>
  
  

Aside from a single "binary" field, the "detail" DataSource should generally have only hidden fields, as shown above. Additional internal fields (such as a "lastUpdated" field) may be added, but will not be editable via MultiFileItem.

Display

The MultiFileItem appears as a list of files related to the current record. An optional button, the removeButton allows removing files. A second optional button, the editButton, launches a picker for uploading further files.

Saving

In all cases, uploading a new file is an "add" DSRequest against the dataSource.

The MultiFileItem has two modes, according to whether the "master" record is being newly created via an "add" operation or whether the master record is pre-existing ("update" operation).

If the master record is pre-existing, each file added by the user is uploaded as soon as the user exits the picker launched from the edit button, and the list of files shown in the main form reflects the actual list of stored files.

If the master record is being newly created, files are not actually uploaded until after the master record is confirmed saved, and the list of fields shown in the main form reflects files which will be uploaded after the master record is saved.

In both cases, if there are multiple files to upload, they are uploaded one at a time, as a series of separate "add" DSRequests against the dataSource.

Also in both cases, deletion of any file is immediate. In the case of a pre-existing master record, all files shown actually exist as DataSource records, and deletion is performed as a "remove" DSRequest against the dataSource.

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
MultiFileItem()
           
MultiFileItem(com.google.gwt.core.client.JavaScriptObject jsObj)
           
MultiFileItem(java.lang.String name)
           
MultiFileItem(java.lang.String name, java.lang.String title)
           
 
Method Summary
 java.lang.String getEditButtonPrompt()
          The prompt of the edit button.
 java.lang.String getEmptyMessage()
          Empty message to display when there are no files listed.
static MultiFileItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
           
 java.lang.String getPickerAddAnotherFileButtonTitle()
          The contents of the "Add another" file button in the picker launched by the edit button.
 java.lang.String getPickerCancelButtonTitle()
          The title of the cancel button in the picker lauched by the edit button.
 java.lang.String getPickerConstructor()
          MultiFileItems use a MultiFilePicker instance as their picker.
 java.lang.String getPickerUploadButtonInitialTitle()
          The initial title of the upload button in the picker lauched by the edit button that is used before the form is saved.
 java.lang.String getPickerUploadButtonTitle()
          The title of the upload button in the picker lauched by the edit button that is used after the form is saved.
 java.lang.String getPickerUploadProgressLabel()
          Specifies the label of the progress meter in the picker lauched by the edit button.
 java.lang.String getRemoveButtonPrompt()
          The prompt of the remove button.
 void setEditButtonPrompt(java.lang.String editButtonPrompt)
          The prompt of the edit button.
 void setEmptyMessage(java.lang.String emptyMessage)
          Empty message to display when there are no files listed.
 void setPickerAddAnotherFileButtonTitle(java.lang.String pickerAddAnotherFileButtonTitle)
          The contents of the "Add another" file button in the picker launched by the edit button.
 void setPickerCancelButtonTitle(java.lang.String pickerCancelButtonTitle)
          The title of the cancel button in the picker lauched by the edit button.
 void setPickerConstructor(java.lang.String pickerConstructor)
          MultiFileItems use a MultiFilePicker instance as their picker.
 void setPickerUploadButtonInitialTitle(java.lang.String pickerUploadButtonInitialTitle)
          The initial title of the upload button in the picker lauched by the edit button that is used before the form is saved.
 void setPickerUploadButtonTitle(java.lang.String pickerUploadButtonTitle)
          The title of the upload button in the picker lauched by the edit button that is used after the form is saved.
 void setPickerUploadProgressLabel(java.lang.String pickerUploadProgressLabel)
          Specifies the label of the progress meter in the picker lauched by the edit button.
 void setRemoveButtonPrompt(java.lang.String removeButtonPrompt)
          The prompt of the remove button.
 
Methods inherited from class com.smartgwt.client.widgets.form.fields.CanvasItem
addCanEditChangedHandler, addReadOnlyDisplayChangedHandler, addShowValueHandler, changeAutoChildDefaults, changeAutoChildDefaults, changePickerIconDefaults, createCanvas, getApplyPromptToCanvas, getAutoDestroy, getCanvas, getEditCriteriaInInnerForm, getHeight, getHeightAsString, getMultiple, getOverflow, getPrompt, getShouldSaveValue, hasAdvancedCriteria, setApplyPromptToCanvas, setAutoDestroy, setCanEditCriterionPredicate, setCanvas, setCriterionGetter, setCriterionSetter, setDefaultProperties, setEditCriteriaInInnerForm, setHeight, setHeight, setMultiple, setOverflow, setPrompt, setShouldSaveValue, setupCanvasConstructor, storeValue, storeValue, storeValue
 
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, getChangeOnKeypress, 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, getHint, 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, getReadOnlyClipValue, getReadOnlyDisplay, getReadOnlyTextBoxStyle, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRowSpan, getSaveOnEnter, getScClassName, getSelectedRecord, getSelectOnClick, getSelectOnFocus, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowPickerIcon, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStopOnError, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextBoxStyle, 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, getWidth, getWidthAsString, getWrapTitle, 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, setCanFocus, setCellHeight, setCellStyle, setChangeOnKeypress, setClipTitle, setColSpan, setColSpan, setControlStyle, setCriteriaField, setCriterion, 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, 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, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyClipValue, setReadOnlyDisplay, setReadOnlyTextBoxStyle, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRowSpan, setSaveOnEnter, setScClassName, setSelectOnClick, setSelectOnFocus, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowPickerIcon, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStopOnError, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, 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, setWidth, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, show, showIcon, showPicker, stopHover, 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

MultiFileItem

public MultiFileItem()

MultiFileItem

public MultiFileItem(com.google.gwt.core.client.JavaScriptObject jsObj)

MultiFileItem

public MultiFileItem(java.lang.String name)

MultiFileItem

public MultiFileItem(java.lang.String name,
                     java.lang.String title)
Method Detail

getOrCreateRef

public static MultiFileItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

setEditButtonPrompt

public void setEditButtonPrompt(java.lang.String editButtonPrompt)
The prompt of the edit button.

Parameters:
editButtonPrompt - Default value is "Add files"

getEditButtonPrompt

public java.lang.String getEditButtonPrompt()
The prompt of the edit button.

Returns:
String

setEmptyMessage

public void setEmptyMessage(java.lang.String emptyMessage)
Empty message to display when there are no files listed.

Parameters:
emptyMessage - Default value is "Click icon to add..."

getEmptyMessage

public java.lang.String getEmptyMessage()
Empty message to display when there are no files listed.

Returns:
String

setPickerAddAnotherFileButtonTitle

public void setPickerAddAnotherFileButtonTitle(java.lang.String pickerAddAnotherFileButtonTitle)
The contents of the "Add another" file button in the picker launched by the edit button.

Parameters:
pickerAddAnotherFileButtonTitle - See HTMLString . Default value is "Add another"

getPickerAddAnotherFileButtonTitle

public java.lang.String getPickerAddAnotherFileButtonTitle()
The contents of the "Add another" file button in the picker launched by the edit button.

Returns:
See HTMLString

setPickerCancelButtonTitle

public void setPickerCancelButtonTitle(java.lang.String pickerCancelButtonTitle)
The title of the cancel button in the picker lauched by the edit button.

Parameters:
pickerCancelButtonTitle - Default value is "Cancel"

getPickerCancelButtonTitle

public java.lang.String getPickerCancelButtonTitle()
The title of the cancel button in the picker lauched by the edit button.

Returns:
String

setPickerConstructor

public void setPickerConstructor(java.lang.String pickerConstructor)
MultiFileItems use a MultiFilePicker instance as their picker. The generated picker autoChild may be customized via the standard com.smartgwt.client.types.AutoChild pattern.

Parameters:
pickerConstructor - See SCClassName . Default value is "MultiFilePicker"

getPickerConstructor

public java.lang.String getPickerConstructor()
MultiFileItems use a MultiFilePicker instance as their picker. The generated picker autoChild may be customized via the standard com.smartgwt.client.types.AutoChild pattern.

Returns:
See SCClassName

setPickerUploadButtonInitialTitle

public void setPickerUploadButtonInitialTitle(java.lang.String pickerUploadButtonInitialTitle)
The initial title of the upload button in the picker lauched by the edit button that is used before the form is saved.

Parameters:
pickerUploadButtonInitialTitle - Default value is "OK"
See Also:
setPickerUploadButtonTitle(java.lang.String)

getPickerUploadButtonInitialTitle

public java.lang.String getPickerUploadButtonInitialTitle()
The initial title of the upload button in the picker lauched by the edit button that is used before the form is saved.

Returns:
String
See Also:
getPickerUploadButtonTitle()

setPickerUploadButtonTitle

public void setPickerUploadButtonTitle(java.lang.String pickerUploadButtonTitle)
The title of the upload button in the picker lauched by the edit button that is used after the form is saved.

Parameters:
pickerUploadButtonTitle - Default value is "Save"
See Also:
setPickerUploadButtonInitialTitle(java.lang.String)

getPickerUploadButtonTitle

public java.lang.String getPickerUploadButtonTitle()
The title of the upload button in the picker lauched by the edit button that is used after the form is saved.

Returns:
String
See Also:
getPickerUploadButtonInitialTitle()

setPickerUploadProgressLabel

public void setPickerUploadProgressLabel(java.lang.String pickerUploadProgressLabel)
Specifies the label of the progress meter in the picker lauched by the edit button. This property is a dynamic string, similar to the dynamicContents feature, with the variables fileName and formattedFileSize.

Parameters:
pickerUploadProgressLabel - See HTMLString . Default value is "Saving \${fileName} \${formattedFileSize}"

getPickerUploadProgressLabel

public java.lang.String getPickerUploadProgressLabel()
Specifies the label of the progress meter in the picker lauched by the edit button. This property is a dynamic string, similar to the dynamicContents feature, with the variables fileName and formattedFileSize.

Returns:
See HTMLString

setRemoveButtonPrompt

public void setRemoveButtonPrompt(java.lang.String removeButtonPrompt)
The prompt of the remove button.

Parameters:
removeButtonPrompt - Default value is "Remove selected files"

getRemoveButtonPrompt

public java.lang.String getRemoveButtonPrompt()
The prompt of the remove button.

Returns:
String