Concept - File Upload

Target

Reach the following state : Media upload field

In order to reach the previous requirement, we will perform a two step approach.

1. Review the BasicUpload field
2. Create a MediaUpload field

Basic Upload Field

Requirements

The basic upload field will have to: 

• Support the following configuration:
  
  • Maximum File Size
  • File Type (based on mimeType)
  • Label displayed (Actions/FileDetail/...)
• Display File Type as Thumbnail Icon (no image preview)
• Display Notification message
  • Upload completed (Confirmation Message)
  • Upload interrupted (Warn Message)
  • Upload Failed (Error Message)

Basic Views

Views 

(1) Empty 

No File are yet stored. Only display a Upload Button (Opening a selection Field) and a Libel inviting to drag and drop a file.

(2) In progress 

A file was selected or dropped, and the upload is ongoing.
Display

• progress bar and ratio.
• action  to cancel the current download. In this case the previous state is displayed Empty View (1) or Completed View (2)

(3) Completed

A file was already downloaded or stored.
Display

• an File Icon representation file
• file detail
  • By configuration the FileName and Format can be editable (As an Input Field).
• actions
  
  • Upload a new file
  • Remove the current file. In this case, display the Empty View (1)

Technical overview

Components and Interaction

BasicUploadFieldBuilder (info.magnolia.ui.form.field.builder.BasicUploadFieldBuilder)


Based on the BasicUploadFieldDefinition,  Configure the BasicUploadFiel  (set captions, define the max upload size...)
Based on the Input Item  get or create the sub Item (ContentItem) that contains the binary and File information's.
Based on the ContentItem Initialize a FileItemWrapper. FileItemWrapper perform the bridge between the original Item (keep a reference of this Item) and the UploadReceiver.  UploadReceiver contains the Dropped file.     

AbstractUploadField (info.magnolia.ui.form.field.upload.AbstractUploadField<D>)


Handle all Drop events coming from the Upload Vaadin component or from the Drop zone.

Create and handle the Drop Zone.
Create and handle the basic Upload mechanism to get a file from a folder.
Initialize and handle the View transition (Empty / In progress / Completed) based on the events (UploadeStarted/ UploadComplete...) and actions (Upload new, Cancel,...). .
Handle the Display on the Note.
Populate  the FileItemWrapper  based on the UploadReceiver.

BasicUploadField (info.magnolia.ui.form.field.upload.basic.BasicUploadField<D>)


Create the Views Use for the the Empty, In progress and Completed state .

BasicUploadFieldDefinition (info.magnolia.ui.form.field.definition.BasicUploadFieldDefinition)


Configuration of the Upload Field.

FileItemWrapper (info.magnolia.ui.form.field.upload.FileItemWrapper)


Initialized based on an Item by  the BasicUploadBuilder class. Used by BasicUploadFiel in order to display File information's (File Name/Size).
Updated by AbstractUploadField  based on upload events (populate when an upload was performed, clear on remove action...).

Basic Upload Jcr Note structure

Once a File is uploaded and the related Dialog/Form saved, the following node structure is created under the Dialog/Form parent node.

• dialog/form parent Node 
  
  • binaryNodeName (Primary node type should extend nt:resource)  
    
    • jcr:data (type="Binary") : Contains the File Binary
    • fileName: Name of the File
    • jcr:mimeType: mimeType of the File
    • jcr:lastModified: Last modification date of the File
    • size: File Size in Bites.
    • extension: File Extension (zip, xml....)

Basic Upload Field Definition

Class: info.magnolia.ui.form.field.definition.BasicUploadFieldDefinition

Tasks

Unable to locate Jira server for this macro. It may be due to Application Link configuration.

Multi-Media Upload Field

Requirement

The Multi-Media-Upload Field is an extension of the Basic Upload Field. (target: Media upload field)

Supported new Features:

• Different display depending of the Media Type
  
  • Image
  • Video
  • Sound
  • Application
  • Document
• Display Notification messages
  
  • A success confirmation note
  • A cancel confirmation note
  • An error alert signals a problem and requires the user to manually acknowledge it.
• For Image 
  • Thumbnail image.
  • Edition actions :
    
    • Preview Image (image Editor)
    • Work on the Image (crop/rotate...)
• For Video
  
  • Thumbnail image (not yet implemented).
  • Edit action :
    
    • Open a Basic videoPlayer  (not yet implemented).
• For Audio
  • Thumbnail Icon
  • Edit action
    
    • Open a basic soundPlayer (not yet implemented).
• For document and Application
  • Thumbnail Icon
  • No specific actions.

Open question:

• How/Who to perform the Thumbnail generation
  
  • for images
  • for video

View

The views and flow are the same as for the Basic Upload field. The only difference is on the Completed view. This view add additional optional actions and preview based on the media type.

Technical overview

Components and Interaction

The multimedia upload file is an extension of the Basic upload file. This field used the MediaType configuration in order to

• link a uploaded file mimeType to a mediaType
• configure the specific actions (open mediaEditor, ...) based on the mimeType.

Sequence

A new File is uploaded (or a stored file is handled by the upload file)

1. Get the File mimeType property
2. Based on the mimeType use DamModul.getMediaTypeForMimeType(String mimeType) in order to determine the related  MediaType. MediaType use the Voter  in order to link them to mimeType.
3. Based on the MediaType.UploadConfig define the action and thumbnail component to display in the Completed view.

MediaType configuration

• MediaType 
  
  • Voter:  Voter's used to link a file mimeType to a MediaType.
  • Class<? extends AssetRenderer>: Define the AssetRenderer linked to a MediaType . This is used to render a specific Asset in pages (See DamApi 1.x documentation).
  • UploadConfig  (Specific UploadField Configuration)
    
    • PreviewConfiguration  (Configure the preview Action)
      
      • iconStyleName:  Icon Style used to display the specific action.
      • Class<? extends PreviewComponentProvider> : Preview Provider
    • EditConfiguration  (Configure the edit in MediaEditor Action)
      
      • iconStyleName:  Icon Style used to display the specific action.
      • mediaEditorId : Preview Provider
    • Class<? extends ThumbnailComponentProvider>: Provider used to generate the Thumbnail.

Class Diagram

DamUploadFieldBuilder (info.magnolia.dam.asset.field.builder.DamUploadFieldBuilder)


Based on the DamUploadFieldDefinition,  Configure the DamUploadFiel  (set captions, define the max upload size...)
Based on the Input Item  get or create the sub Item (ContentItem) that contains the binary and File information's.
Based on the ContentItem Initialize a DamFileItemWrapper. DamFileItemWrapper perform the bridge between the original Item (keep a reference of this Item) and the UploadReceiver.  UploadReceiver contains the Dropped file.
DamFileItemWrapper  uses DamModule in order to define the MediaType related to an uploaded media.     

DamFileItemWrapper (info.magnolia.dam.asset.field.DamFileItemWrapper) extend BasicFileItemWrapper


Initialized based on an Item by  the DamUploadFieldBuilder class. Used by DamUploadField in order to
 - display File information's (File Name/Size).
 - define the related File MediaType and expose the UploadConfig to the DamUploadField
Updated by AbstractUploadField  based on upload events (populate when an upload was performed, clear on remove action...).

DamUploadField (info.magnolia.dam.asset.field.DamUploadField<D>) extend BasicUploadField

Based on the UploadConfig  linked to MediaType, configure and build the completed view.

Caption specific handling based on the MediaType:
Some captions are dynamically updated based on the MediaType id.  This id is added at the end of the i18n reference key (message bundle). For example:
field.upload.select.new = Select a file to upload...
Is the default caption used in the completed view. If the current File is linked to a MediaType of type 'image', the caption displayed is:
field.upload.select.new.image = Select an image to upload...

MultiMedia Upload Jcr Note structure

Once a File is uploaded and the related Dialog/Form saved, the following node structure is created under the Dialog/Form parent node.

• dialog/form parent Node 
  
  • binaryNodeName (Primary node type should extend nt:resource)  
    
    • jcr:data (type="Binary") : Contains the File Binary
    • fileName: Name of the File
    • jcr:mimeType: mimeType of the File
    • jcr:lastModified: Last modification date of the File
    • size: File Size in Bites.
    • extension: File Extension (zip, xml....)
    • mediaType: Related Media Type
    • height: In case of Image, height of the image
    • width: In case of Image, width of the image
    • duration: In case of video or audio, related duration

MultiMedia Upload Field Definition

Class: info.magnolia.dam.asset.field.definition.DamUploadFieldDefinition

Inherit all configuration of BasicUploadFieldDefinition and define in addition:

The following i18n keys have a related definition for each defined MediaType:
editFileCaption, selectNewCaption, selectAnotherCaption, dropZoneCaption, fileDetailHeaderCaption, successNoteCaption, warningNoteCaption, errorNoteCaption. For example:
field.upload.select.edit is defined for  , so in your resource i18n property file has to have for every configured MediaType id an entry key:
field.upload.select.edit = Edit file...
field.upload.select.edit.image = Edit image..
field.upload.select.edit.video = Edit video...
...

Tech solutions:

Create a Preview image from a Video:

• http://wiki.xuggle.com/MediaTool_Introduction

Links

http://wordpress.org/extend/plugins/video-embed-thumbnail-generator/screenshots/

Open Issue / To Implement

Specific Preview implementation of PreviewComponentProvider

• Video (http://videojs.com/)
• Audio
• Document

Specific ThumbnailComponentProvider  implementation

• Video (Create a thumbnail from a video)

http://www.javacodegeeks.com/2011/02/xuggler-tutorial-transcoding-media.html

http://www.xuggle.com/xuggler

Post mimeType validation

Found a way to extract a mimeType only based on a file.

http://www.rgagnon.com/javadetails/java-0487.html

MimeType extraction

Found a way to extract media metaData properties. Has to be used to extract the duration of a video or audio, and also be extended to automatically extract supported metadata (DC, ...)

http://www.xuggle.com/xuggler and http://code.google.com/p/metadata-extractor/ based o the media format

http://meta-extractor.sourceforge.net/

Generic Field listener mechanism and configuration

We have to have a generic field property change listener in order to be able to:

• be notified when a Field property has changed
• take a specific action.

For example, assume that we have a form containing two tabs:

• UserForm
  
  • RequiredTab
    
    • Name
    • ImageResource
    • NickName
  • OptionalTab
    
    • Email
    • Salutation
    • GeneratedKey (hidden field)

NickName is a concatenation of the Name and predefine suffix.
GeneratedKey is calculated based on the ImageResource.fileName and ImageResource.fileSize.

Requirement

• A field property may listen to one or more property changes and call a single action definition
• A field property may be linked (listen) sub field property (ImageResource.fileName)