Tapestry5-jQuery

Documentation
JSONParameters
Example

AJAX/XHR/iFrame upload component

Description

Upload single or multiple files using either an XHR POST or (in case of Opera and IE) regular POSTs through an invisible iFrame.
Triggered events:

Event	Description
JQueryEventConstants.AJAX_UPLOAD ("ajaxFileUpload")	Triggered in case of an XHR file upload. The event handler may return renderable objects such as MultiZoneUpdate. null is also possible and will result in a regular rendering of the success json.
JQueryEventConstants.NON_XHR_UPLOAD ("fileUpload")	Triggered in case of a regular file upload using the iFrame fallback. The event handler cannot return a MultiZoneUpdate or similar. Only JSONObjects are supported. If you need other parts of your page to rerender after the upload took place you can return a JSONObject with the following structure to trigger a custom event (which will be a separate XHR call): { AjaxUpload.UPDATE_ZONE_CALLBACK : { url : /consult the ComponentResources to generate one/, zoneId : /insert your zone id in here/ } } null as a result will cause a simple response like { "success" : "true" } in case a file has been uploaded.

Event

Description

JQueryEventConstants.AJAX_UPLOAD ("ajaxFileUpload")

Triggered in case of an XHR file upload. The event handler may return renderable objects such as MultiZoneUpdate. null is also possible and will result in a regular rendering of the success json.

JQueryEventConstants.NON_XHR_UPLOAD ("fileUpload")

Triggered in case of a regular file upload using the iFrame fallback.
The event handler cannot return a MultiZoneUpdate or similar. Only JSONObjects are supported.
If you need other parts of your page to rerender after the upload took place you can return a JSONObject with the following structure to trigger a custom event (which will be a separate XHR call):

	{
	    AjaxUpload.UPDATE_ZONE_CALLBACK : {
	        url : /consult the ComponentResources to generate one/,
	        zoneId : /insert your zone id in here/
	    }
	}

null as a result will cause a simple response like { "success" : "true" } in case a file has been uploaded.

Example for JQueryEventConstants.AJAX_UPLOAD event handler:

		
    @OnEvent(component = "uploadImage", value = JQueryEventConstants.AJAX_UPLOAD)
    void onImageUpload(UploadedFile uploadedFile) {

        if (uploadedFile != null) {

            this.uploadedFiles.add(uploadedFile);
        }

        message = "This upload was: AJAX_UPLOAD";

        ajaxResponseRenderer.addRender("uploadResult", uploadResult);
    }

Example for JQueryEventConstants.NON_XHR_UPLOAD event handler with custom event handler for the additional zone refresh:

		
    @OnEvent(component = "uploadImage", value = JQueryEventConstants.NON_XHR_UPLOAD)
    Object onNonXHRImageUpload(UploadedFile uploadedFile) {

        if (uploadedFile != null) {

            this.uploadedFiles.add(uploadedFile);
        }

        final JSONObject result = new JSONObject();
        final JSONObject params = new JSONObject()
              .put("url", resources.createEventLink("myCustomEvent", "NON_XHR_UPLOAD").toURI())
              .put("zoneId", "uploadResult");

        result.put(AjaxUpload.UPDATE_ZONE_CALLBACK, params);

        return result;
    }

Links

The original JS library: https://github.com/valums/file-uploader
Inspiration for the AjaxUploadDecoder: https://github.com/tawus/tawus/tree/master/tawus-ajaxupload

Parameters
Name	Required	Java Type	Default Prefix	Default Value	Description
multiple	false	boolean	prop	false	Enables multiple file uploads.
allowedExtensions	false	String	literal		Defines allowed extensions. All files are allowed by default.
sizeLimit	false	JSONObject	literal	0	Defines the maximum size of one single file in bytes. If the number has a trailing K, M or G the limit will be calculated accordingly (base 2). A value of 10M will result a limit of 10 * 1024 * 1024 byte = 10 MiB. No limit by default.
maxConnections	false	int	prop	3	Limits the amount of parallel uploads.
params	false	JSONObject	prop		Gives you the full control over all parameters. Please read the documentation of valum's file-uploader. Besides the already mentioned parameters the messages can also be overridden by either specifying them in your own global message bundles or by passing the translated texts as parameters.

API for the 'params' component parameter

Description

Note: If you define your own templates make sure you keep the original css classes. The file-uploader script looks for them to apply its functions (qq-upload-drop-area for the drop-area for example).

	params = {
	    messages : {            
	        typeError: "{file} has invalid extension. Only {extensions} are allowed.",
	        sizeError: "{file} is too large, maximum file size is {sizeLimit}.",
	        minSizeError: "{file} is too small, minimum file size is {minSizeLimit}.",
	        emptyError: "{file} is empty, please select files again without it.",
	        onLeave: "The files are being uploaded, if you leave now the upload will be cancelled."
	
	        // label for the default templates. 
	        uploadLabel   : "regular upload field label",
	        dropAreaLabel : "drop field label",
	        cancelLabel   : "text for the cancel button", 
	        failedLabel   : "error label"
	    },
	
	    // You can also override the internal event handler!
	    // But beware: AjaxUpload's onComplete handler has some
	    // tweaks included to make non-XHR uploads support 
	    // zone-updates! Don't break it if you need it!
	    onSubmit: function(id, fileName){},
	    onProgress: function(id, fileName, loaded, total){},
	    onComplete: function(id, fileName, responseJSON){},
	    onCancel: function(id, fileName){},
	
	    showMessagesDialog : "The id of your custom message dialog.",
	
	    button: null,
	    multiple: true,
	    maxConnections: 3,
	    // validation
	    allowedExtensions: [],
	    sizeLimit: 0,
	    minSizeLimit: 0,
	
	    // the template where to drop in your stuff
	    template : "Define your own upload component template here",
	
	    // that's the one that lists uploaded files, cancel link, etc.
	    fileTemplate : "Define your own file template here."
	}

		
<j:ajaxUpload t:id="uploadImage" 
	                  t:multiple="true" 
	                  t:allowedExtensions="[jpg, png, gif]" 
	                  t:sizeLimit="1M"> <!-- The units K, M and G are valid for size limits. Anything else will be treated as 0 -->
    <noscript>
        <p>JavaScript must be activated!</p>
    </noscript>
</j:ajaxUpload>

<t:zone t:id="uploadResult">
    <div>
        <t:if test="message">
            <p>
                <strong>${message}</strong>
            </p>
        </t:if>

        <t:if test="uploadedFiles">
            <h4>Uploaded files</h4>
            
            <t:grid source="uploadedFiles"></t:grid>
        </t:if>
    </div>
</t:zone>

		
public class DocsAjaxUpload {

    @Persist(PersistenceConstants.FLASH)
    private String message;

    @Persist
    @Property
    private List<UploadedFile> uploadedFiles;

    @InjectComponent
    private Zone uploadResult;

    @Inject
    private ComponentResources resources;

    @Inject
    private AjaxResponseRenderer ajaxResponseRenderer;

    void onActivate() {

        if (uploadedFiles == null)
            uploadedFiles = new ArrayList<UploadedFile>();
    }

    @OnEvent(component = "uploadImage", value = JQueryEventConstants.AJAX_UPLOAD)
    void onImageUpload(UploadedFile uploadedFile) {

        if (uploadedFile != null) {

            this.uploadedFiles.add(uploadedFile);
        }

        message = "This upload was: AJAX_UPLOAD";

        ajaxResponseRenderer.addRender("uploadResult", uploadResult);
    }

    @OnEvent(component = "uploadImage", value = JQueryEventConstants.NON_XHR_UPLOAD)
    Object onNonXHRImageUpload(UploadedFile uploadedFile) {

        if (uploadedFile != null) {

            this.uploadedFiles.add(uploadedFile);
        }

        final JSONObject result = new JSONObject();
        final JSONObject params = new JSONObject()
              .put("url", resources.createEventLink("myCustomEvent", "NON_XHR_UPLOAD").toURI())
              .put("zoneId", "uploadResult");

        result.put(AjaxUpload.UPDATE_ZONE_CALLBACK, params);

        return result;
    }

    @OnEvent(value = "myCustomEvent")
    void onMyCustomEvent(final String someParam) {

        message = "This upload was: " + someParam;

        ajaxResponseRenderer.addRender("uploadResult", uploadResult);
    }

    void onUploadException(FileUploadException ex) {

        message = "Upload exception: " + ex.getMessage();

        ajaxResponseRenderer.addRender("uploadResult", uploadResult);
    }

    public String getMessage() {

        return message;
    }
}

Core Components

jQuery Components

jQuery Mixins

Mecanisms

AJAX/XHR/iFrame upload component

Description

Links

API for the 'params' component parameter

Description