com.smartgwt.client.widgets.form.fields

## Class MultiFileItem

- java.lang.Object
- - com.smartgwt.client.core.JsObject
  - - com.smartgwt.client.core.DataClass
    - - com.smartgwt.client.core.RefDataClass
      - - com.smartgwt.client.widgets.form.fields.FormItem
        - - com.smartgwt.client.widgets.form.fields.CanvasItem
          - - com.smartgwt.client.widgets.form.fields.MultiFileItem

- All Implemented Interfaces:
    HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers

      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:

  - declare a "detail" DataSource to store the related files. At a minimum, this DataSource must have:
    - a `primaryKey` field
    - a field declaring a `foreignKey` relationship to the primaryKey of the "master" DataSource
    - a field of type "binary"
  - `bind` a DynamicForm to the "master" DataSource
  - in the DynamicForm bound to the "master" DataSource, declare a field with `editorType`:"MultiFileItem" and a `dataSource` property set to the ID of the "detail" DataSource
  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.DataClass

      `factoryCreated, factoryProperties`

    - ### Fields inherited from class com.smartgwt.client.core.JsObject

      `jsObj`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiFileItem()`
    `MultiFileItem(JavaScriptObject jsObj)`
    `MultiFileItem(java.lang.String name)`
    `MultiFileItem(java.lang.String name, java.lang.String title)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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(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, 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, setShouldDisableCanvasCustomizer, 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, addValueIconClickHandler, asSGWTComponent, blurItem, canEditCriterion, clearValue, disable, enable, error, error, errorIfNotCreated, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanSelectText, getCanvasAutoChild, getCellHeight, getCellStyle, getChangeOnKeypress, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDisabled, getDisableIconsOnReadOnly, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEditProxyConstructor, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getExportFormat, getFetchMissingValues, getFieldName, getFilterLocally, getForeignDisplayField, 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, 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, getStaticHeight, 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, redraw, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setBrowserSpellCheck, setCanEdit, setCanEditOpaqueValues, setCanFocus, setCanSelectText, setCellHeight, setCellStyle, setChangeOnKeypress, setClipStaticValue, 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, setEditProxyConstructor, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setExportFormat, setFetchMissingValues, setFilterLocally, setForeignDisplayField, 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, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, 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, setStaticHeight, 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, shouldStopKeyPressBubbling, 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

      `applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated`

    - ### 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(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(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 "<u>Add&nbsp;another</u>"

    - #### 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