Package com.jbstrap.ui.components.form.items.fileitem

Class FileItem

java.lang.Object
com.jbstrap.core.messagebus.MessageBus
com.jbstrap.ui.Component<E>
com.jbstrap.ui.components.form.FormItem<List<JBFile>,FileItem>
com.jbstrap.ui.components.form.items.fileitem.FileItem
All Implemented Interfaces:
Animatable<FileItem>, CanDrop<FileItem>, Draggable<FileItem>, Focusable<FileItem>, HandleHotKey<FileItem>, HandleMouseEvents<FileItem>, FileValueFormItem<FileItem>
public class FileItem extends FormItem<List<JBFile>,FileItem> implements FileValueFormItem<FileItem>, Animatable<FileItem>, Focusable<FileItem>, HandleMouseEvents<FileItem>, HandleHotKey<FileItem>, CanDrop<FileItem>, Draggable<FileItem>

File item

The component is used for file handling. The file item component enables the user to upload files to the server and also to display previously uploaded files. The file item component updates previously updates files: files can be deleted and new ones can be uploaded.

This component is a form item and is the part of a Form. The form item value is one or more JBFile objects representing uploaded files. The uploaded file is stored in a temporary file store on the server. Multiple file uploads are executed simultaneously. The upload progress is displayed on a progress bar. If the component displays a previously uploaded file or the current file upload is finished, the progress bar under the file name disappears and a delete button is shown next to the file name. The file can be deleted using this button.

If the component displays a previously uploaded file, the user is able to download it by clicking on the file name.

If the file item component is used as part of a Form, the Form.save() synchronizes the file with the one stored on the server. Uploaded files are saved and deleted files are removed. The form is saved using the DAO layer. File handling methods are executed by the specified JBStrapParamType.FILE_HANDLER. If the component is not a part of a Form, uploaded files must be saved by an own code implementation.

Supported events:

AnimationStart AnimationEnd, Focus FocusOut FocusIn LosesFocus MouseDown, MouseDown, MouseLeave, MouseMove, MouseOver, MouseOut, MouseUp, Wheel, Drop, DragStart, DragEnd HotKey

Since:
4.0
Author:
JBStrap
See Also:

  • Constructor Details

    • FileItem

      public FileItem(String name, String label)
      Creates a file item with the specified name and label.
      Parameters:
      name - File item name
      label - File item label If null is specified, no label is displayed for the file item.
      Throws:
      NullPointerException - Thrown if the specified name is null

    • FileItem

      public FileItem(String name, String label, String language)
      Creates a file item with the specified name and label according to the language code.
      Parameters:
      name - File item name
      label - File item label If null is specified, no label is displayed for the file item.
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the specified name is null

    • FileItem

      public FileItem(String name, String label, String fileStoreName, String language)
      Creates a file item with the specified name and label and sets the file store name where files are stored. Also specifies the language code according to which the component is created. Creates a file item with specified name and label.
      Parameters:
      name - File item name
      label - File item label If null is specified, no label is displayed for the file item.
      fileStoreName - The name of the file store used to save the files
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the specified name is null
      See Also:

    • FileItem

      public FileItem(DataDescriptorColumn column)

      Creates a file item based on the specified DataDescriptor column.

      The method creates and sets the file item component based on the specified DataDescriptor column. The following parameters of the DataDescriptor are used:

      • DataDescriptorColumn.getTitle - The field label is the one specified for the DataDescriptor column
      • DataDescriptorColumn.isNullable() - If the field gets a value of null, it is not designated as mandatory. If the field value is not set to null, it is designated as a mandatory field.
      • MetaParamName.MULTIPLE - This parameter specifies if multiple files can be uploaded to the component. By default, only one file can be uploaded to the component. If true is specified, multiple components can be uploaded to the component and displayed in a list.
      • MetaParamName.DRAGABLE - This parameter specifies if drag&drop is enabled. By default the drag&drop file upload is disabled. If true is specified, the component accepts files with drag&drop file upload. The client browser must also support this.
      • MetaParamName.FILE_STORE_NAME - This parameter specifies the file store name. If the parameter is not specified, the file store name must be set from code in the JBFile classes. If no parameter is set, the component automatically sets the file store name in the JBFile objects.
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the input field. This text is displayed if no other text is entered into the input field.
      • MetaParamName.SIZE - The input field size is set from the value specified here. (Available values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The input field state is set from these values. (Available values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here is set as the input field’s default value. The value must be specified based on the field’s data type, in this case it must be a text value.
      • MetaParamName.READ_ONLY - If true is set, the field is created as a read-only field. Otherwise, the field is created as writable and the user can freely modify its content.
      • MetaParamName.ENABLED - If false is specified, the field is created as disabled. Otherwise the field is created as enabled.
      • MetaParamName.HELP - If this parameter is specified, an icon is displayed next to the input field and the text specified here appears as a help text if the user moves the mouse over it.
      • MetaParamName.HELP_ICON - If an icon name is specified in the parameter, also listed in the enum Icon, the default help text is changed to the icon.
      • MetaParamName.DESCRIPTION - The text specified here will appear below the field, in a smaller, italic font.
      • MetaParamName.TAB_INDEX - The input focus follows the value specified here if the user presses the Tab button. The smaller the value is, the sooner the field receives focus. The greater the value is, the later the field gets focus. If the parameter is not specified, the field’s tab index receives the value of the field’s position in a sequence as specified in the DataDescriptor. If that is not specified either, the order of data entries in the DataDescriptor is used to focus the component.

      Parameters:
      column - DataDescriptor instance used to create the component
      Throws:
      NullPointerException - Thrown if the specified DataDescriptor column is set to null

    • FileItem

      public FileItem(DataDescriptorColumn column, String language)

      Creates a file item based on the specified DataDescriptor column according to the language code.

      The method creates and sets the file item component based on the specified DataDescriptor column. The following parameters of the DataDescriptor are used:

      • DataDescriptorColumn.getTitle - The field label is the one specified for the DataDescriptor column
      • DataDescriptorColumn.isNullable() - If the field gets a value of null, it is not designated as mandatory. If the field value is not set to null, it is designated as a mandatory field.
      • MetaParamName.MULTIPLE - This parameter specifies if multiple files can be uploaded to the component. By default, only one file can be uploaded to the component. If true is specified, multiple components can be uploaded to the component and displayed in a list.
      • MetaParamName.DRAGABLE - This parameter specifies if drag&drop is enabled. By default the drag&drop file upload is disabled. If true is specified, the component accepts files with drag&drop file upload. The client browser must also support this.
      • MetaParamName.FILE_STORE_NAME - This parameter specifies the file store name. If the parameter is not specified, the file store name must be set from code in the JBFile classes. If no parameter is set, the component automatically sets the file store name in the JBFile objects.
      • MetaParamName.PLACEHOLDER - Placeholder text to be used in the input field. This text is displayed if no other text is entered into the input field.
      • MetaParamName.SIZE - The input field size is set from the value specified here. (Available values: SMALL, MEDIUM, LARGE)
      • MetaParamName.STATE - The input field state is set from these values. (Available values: DEFAULT, ERROR, WARNING, SUCCESS, INFO)
      • MetaParamName.DEFAULT_VALUE - The value specified here is set as the input field’s default value. The value must be specified based on the field’s data type, in this case it must be a text value.
      • MetaParamName.READ_ONLY - If true is set, the field is created as a read-only field. Otherwise, the field is created as writable and the user can freely modify its content.
      • MetaParamName.ENABLED - If false is specified, the field is created as disabled. Otherwise the field is created as enabled.
      • MetaParamName.HELP - If this parameter is specified, an icon is displayed next to the input field and the text specified here appears as a help text if the user moves the mouse over it.
      • MetaParamName.HELP_ICON - If an icon name is specified in the parameter, also listed in the enum Icon, the default help text is changed to the icon.
      • MetaParamName.DESCRIPTION - The text specified here will appear below the field, in a smaller, italic font.
      • MetaParamName.TAB_INDEX - The input focus follows the value specified here if the user presses the Tab button. The smaller the value is, the sooner the field receives focus. The greater the value is, the later the field gets focus. If the parameter is not specified, the field’s tab index receives the value of the field’s position in a sequence as specified in the DataDescriptor. If that is not specified either, the order of data entries in the DataDescriptor is used to focus the component.

      Parameters:
      column - DataDescriptor instance used to create the component
      language - Language code according to which the component is created If not specified or null is set, the framework’s default language code is used. The default language of the framework is set via the JBStrap parameter JBStrapParamType.DEFAULT_LANGUAGE.
      Throws:
      NullPointerException - Thrown if the specified DataDescriptor column is set to null

  • Method Details

    • setFileStoreName

      public final FileItem setFileStoreName(String fileStoreName)
      Sets the file store where the uploaded files are stored.
      Parameters:
      fileStoreName - The name of the file store used to save the files
      Returns:
      File item component
      See Also:

    • getFileStoreName

      public String getFileStoreName()
      Gets the file store name where uploaded files are stored.
      Returns:
      The name of the file store where uploaded files are stored or null if the file store name is not stored

    • setMultiple

      public final FileItem setMultiple(boolean multiple)
      Sets if the multiple file upload option. By default only one file is uploaded at a time. If the multiple file upload option is enabled, the user is able to upload several files simultaneously or consecutively to the file item.
      Parameters:
      multiple - If true is specified, the multiple file upload is enabled; otherwise only one file is uploaded at a time
      Returns:
      File item component

    • isMultiple

      public final boolean isMultiple()
      Sets if the user is allowed to upload multiple files to the component.
      Returns:
      If true, the multiple upload option is enabled

    • setDraggable

      public final FileItem setDraggable(boolean dragable)
      Sets if drag&drop upload is enabled in the component. By default the drag&drop file upload is disabled. If the option is enabled, the user is allowed to upload files to the server by dragging them on the component. For the full functionality of the component, the operation system and browser must support drag&drop upload.
      Specified by:
      setDraggable in interface Draggable<FileItem>
      Parameters:
      dragable - If true is specified, the component accepts files uploaded using drag&drop
      Returns:
      File item component

    • isDraggable

      public boolean isDraggable()
      Checks if drag&drop is allowed.
      Returns:
      If true, the user is allowed to upload files using drag&drop Otherwise drag&drop is not allowed.

    • afterDraw

      public void afterDraw()
      Description copied from class: Component
      The operations to be executed after the drawing of the component

      By default, this is an empty method. It has to be overwritten on a component or page if additional operations have to be executed after the drawing process. One such operation is data retrieval, which shouldn't run in constructors so that the user could see results of an operation or navigation process.

      Overrides:
      afterDraw in class FormItem<List<JBFile>,FileItem>

    • setValue

      public FileItem setValue(List<JBFile> value)
      Sets the current value of the component.
      Overrides:
      setValue in class FormItem<List<JBFile>,FileItem>
      Parameters:
      value - A list of JBFile instances that specify the file item’s current value These files are specified as the component’s current value.
      Returns:
      Form item component

    • getValue

      public List<JBFile> getValue()
      Gets the file item’s current value.
      Overrides:
      getValue in class FormItem<List<JBFile>,FileItem>
      Returns:
      The current value of the component, that is, null if no files are included in the component or a list of JBFile instances representing files in the component

    • drawEditor

      public void drawEditor(StringWriter writer)
      Description copied from class: FormItem

      Draws the editor component.

      You do not need to use this method during development, but all components extending the form item must implement it. Use the method to generate the input field’s HTML code. This code is then inserted into the corresponding DOM code when drawing the form item.

      Specified by:
      drawEditor in class FormItem<List<JBFile>,FileItem>
      Parameters:
      writer - The HTML string writer class instance; write here the HTML code for the input field

    • setDefaultValue

      public FileItem setDefaultValue(Object defaultValue)
      No default value can be set for the file item. The method does nothing.
      Specified by:
      setDefaultValue in class FormItem<List<JBFile>,FileItem>
      Parameters:
      defaultValue - Not used
      Returns:
      Form item component

    • clearValue

      public final FileItem clearValue()
      Clears the component value (removes files from the component).
      Overrides:
      clearValue in class FormItem<List<JBFile>,FileItem>
      Returns:
      File item component

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable

    • addErrorHandler

      public FileItem addErrorHandler(FileItemErrorHandler handler)
      Specifies the error handler implementation. If no error handling implementation is specified, the error text is displayed to the user.
      Parameters:
      handler - Error handler implementation
      Returns:
      File item component

    • getFileCount

      public int getFileCount()
      Gets the file count from the component.
      Returns:
      File count

    • onFormItemValueChanged

      public void onFormItemValueChanged(FormItemChangeEvent event)
      Default change event handler.
      Overrides:
      onFormItemValueChanged in class FormItem<List<JBFile>,FileItem>
      Parameters:
      event - Form item value change event handler

    • addComponent

      public FileItem addComponent(Component<?> component)
      You cannot add further components to the file item component.
      Overrides:
      addComponent in class FormItem<List<JBFile>,FileItem>
      Parameters:
      component - The component to be added
      Returns:
      The component
      Throws:
      UnsupportedOperationException - Thrown every time the method is called

    • onUploadStart

      public void onUploadStart(FileItemUploadStartEvent event)

    • onUploadDone

      public void onUploadDone(FileItemDoneEvent event)

    • setFileUploadedPercent

      public FileItem setFileUploadedPercent(JBFile file, long chunkSize)
      Description copied from interface: FileValueFormItem
      Event handler for the �file upload status changed� event.
      The method is called if the file upload status has changed, that is, a new file packet has been transferred to the server.
      Specified by:
      setFileUploadedPercent in interface FileValueFormItem<FileItem>
      Parameters:
      file - File
      chunkSize - The current chunk size
      Returns:
      File item component

    • removeFileElement

      protected void removeFileElement(com.jbstrap.ui.components.form.items.fileitem.FileElement fileElement)
      Parameters:
      fileElement - File component to be removed

    • setFileListSize

      public FileItem setFileListSize(int fileCount)
      Sets file list size. The specified number of files will be displayed in the component without scrolling if the multiple file option is enabled. If the component contains more files than the file count specified here, the file list is scrollable. By default 3 files are displayed before the file list becomes scrollable.
      Parameters:
      fileCount - Number of files displayed without scrolling
      Returns:
      File item component

    • getFileListSize

      public int getFileListSize()
      Gets the number of files that can be displayed before the list becomes scrollable.
      Returns:
      Number of files displayed without scrolling

    • setReadOnly

      public FileItem setReadOnly(boolean readOnly)
      Specifies if the file item is displayed in read-only mode. By default the component can be modified and the users are allowed to update the files in the component. If the component is set to read-only mode, the user is not allowed to modify the component value (the files), but is allowed to download previously uploaded files.
      Overrides:
      setReadOnly in class FormItem<List<JBFile>,FileItem>
      Parameters:
      readOnly - If true is specified, read-only mode is disabled. If false is set, the component can be modified and the user is not allowed to modify the files.
      Returns:
      File item component

    • getDeletedFiles

      public List<JBFile> getDeletedFiles()
      Gets deleted, but previously uploaded files from the server.
      Returns:
      A list of files currently deleted from the component, but stored on the server

    • onUploadError

      public void onUploadError(FileItemErrorEvent event)

    • addFileUploadStartHandler

      public FileItem addFileUploadStartHandler(FileItemUploadStartHandler handler)

    • addFileUploadDoneHandler

      public FileItem addFileUploadDoneHandler(FileItemDoneHandler handler)

    • setEnabled

      public FileItem setEnabled(boolean enabled)
      Description copied from class: Component
      Sets the component to be enabled. Defaults to true
      Overrides:
      setEnabled in class FormItem<List<JBFile>,FileItem>
      Parameters:
      enabled - true, the component is enabled, otherwise it's disabled
      Returns:
      The component

    • getFileByName

      public JBFile getFileByName(String filename)
      Description copied from interface: FileValueFormItem
      Uses the file name to gets the JBFile that was uploaded to the component with the file type.
      Specified by:
      getFileByName in interface FileValueFormItem<FileItem>
      Parameters:
      filename - File name in the JBFile
      Returns:
      The JBFile with the #getFileName() identical to the one in the parameter

    • setFileDeleteHandler

      public FileItem setFileDeleteHandler(FileDeleteHandler fileDeleteHandler)
      Description copied from interface: FileValueFormItem
      Specifies the handler used to delete a file. The handler must implement the FileDeleteHandler interface.
      Specified by:
      setFileDeleteHandler in interface FileValueFormItem<FileItem>
      Parameters:
      fileDeleteHandler - The file delete handler
      Returns:
      The component