Ready to move to technical documentation.
Target
Reach the following state : Media upload field
In order to reach the previous requirement, we will perform a two step approach.
- Review the BasicUpload field
- 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
based on the FileItemWrapper
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
based on upload events (populate when an upload was performed, clear on remove action...).AbstractUploadField
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)
(type="Binary") : Contains the File Binaryjcr:data
: Name of the FilefileName
: mimeType of the Filejcr:mimeType
: Last modification date of the Filejcr:lastModified
: File Size in Bites.size
: File Extension (zip, xml....)extension
Basic Upload Field Definition
Class: info.magnolia.ui.form.field.definition.BasicUploadFieldDefinition
Property | Description | Default value |
---|---|---|
binaryNodeName | Name of the subNode that will contain the File Binary and related information. | binaryNodeName |
maxUploadSize | Optional. Define the maximum file size in bite. | 263 -1 |
| Optional. Regular expression used to filter uploaded file. If not define upload everything. For example if you just want to upload excel files, used the following regExp | .* |
editFileFormat | Optional. Define if the File Format (Extension) has to be displayed as a Input Field (editFileFormat=true ) or as a simple Label (editFileFormat=false ) . | false |
editFileName | Optional. Define if the File Name has to be displayed as a Input Field ( ) or as a simple Label ( ) . | false |
Caption Configuration section | ||
| Optional. Text displayed as caption on the upload button (Empty View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as caption on the upload button (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as label for dropping invitation (Empty View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as title (In Progress View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file upload ration (In Progress View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file detail header (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file name detail (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file size detail (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file format detail (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as file source detail (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed in the success note. Typically retrieved from a message bundle. | |
| Optional. Text displayed in the warning note. Typically retrieved from a message bundle. | |
| Optional. Text displayed in the error note header. Typically retrieved from a message bundle. | |
| Optional. Text displayed in the warning note reason (File size > maxUploadSize ). Typically retrieved from a message bundle. | |
| Optional. Text displayed in the warning note reason (File type not ). Typically retrieved from a message bundle. | |
| Optional. Text displayed in the warning note reason (User interrupt the upload). Typically retrieved from a message bundle. |
Tasks
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)
- Get the File mimeType property
- Based on the mimeType use
DamModul.getMediaTypeForMimeType(String mimeType)
in order to determine the relatedMediaType
.MediaType
use theVoter
in order to link them to mimeType. - 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 aMediaType
.Class<? extends AssetRenderer>
: Define theAssetRenderer
linked to aMediaType
. This is used to render a specificAsset
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 DamUploadFiel
d in order to
- display File information's (File Name/Size).
- define the related File MediaType
and expose the UploadConfig
to the DamUploadFiel
d
Updated by
based on upload events (populate when an upload was performed, clear on remove action...).AbstractUploadField
DamUploadFiel
d (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)
(type="Binary") : Contains the File Binaryjcr:data
: Name of the FilefileName
: mimeType of the Filejcr:mimeType
: Last modification date of the Filejcr:lastModified
: File Size in Bites.size
: File Extension (zip, xml....)extension
: Related Media TypemediaType
: In case of Image, height of the imageheight
: In case of Image, width of the imagewidth
: In case of video or audio, related durationduration
MultiMedia Upload Field Definition
Class: info.magnolia.dam.asset.field.definition.DamUploadFieldDefinition
Inherit all configuration of BasicUploadFieldDefinition
and define in addition:
Property | Description | Default value |
---|---|---|
| Optional. Text displayed as caption of the preview action (Completed View). Typically retrieved from a message bundle. | |
| Optional. Text displayed as caption of the edit action (Completed View). Typically retrieved from a message bundle. |
The following i18n keys have a related definition for each defined MediaType
:
, editFileCaption
, selectNewCaption
, selectAnotherCaption
, dropZoneCaption
, fileDetailHeaderCaption
, successNoteCaption
, warningNoteCaption
. For example:errorNoteCaption
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:
Links
http://wordpress.org/extend/plugins/video-embed-thumbnail-generator/screenshots/
Open Issue / To Implement
Specific Preview implementation of PreviewComponentProvider
PreviewComponentProvider
- Video (http://videojs.com/)
- Audio
- Document
Specific ThumbnailComponentProvider
implementation
ThumbnailComponentProvider
- Video (Create a thumbnail from a video)
http://www.javacodegeeks.com/2011/02/xuggler-tutorial-transcoding-media.html
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
- Salutation
- GeneratedKey (hidden field)
- RequiredTab
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)
1 Comment
Antti Hietala
This content should replace the content currently in Fields.