Skip to main content

Template handler uploading images

This document covers sample implementation for upload template POST handler uploading images on page submission or on demand using supporting dynamic action Upload Images on Demand. All examples uploads images to the plug-in sample application table UC_FROALA_SAMPLE_BLOBS. The difference between handlers is complexity of PL/SQL code, whether handler uses default query parameters, custom parameters or uses image checksum to secure display handler.

handler features
  • can be combined with handler displaying an image Simple
  • can be combined with handler browsing images Simple
  • doesn't use default parameters and the URL to displaying image handler (page item attribute Image GET URL) is hardcoded in the code

Requirements​

The upload handler must meet the following requirements:

  1. must use POST method
  2. must be compilable at the run time
  3. must return 200 HTTP status code
  4. must print JSON describing uploaded image

Handler definition​

AttributeValue
RESTful Service ModuleA custom RESTservice
Module Base Path/customrest/
URI Templateupload-simple
Full URLhttps://example-domain.com/ords/workspacename/customrest/upload-simple
Handler MethodPOST
Source TypePL/SQL
Mime Types AllowedNot defined

Handler parameters​

The upload handler doesn't require registering any resource parameters as long as REST specific bind variable :status_code is used to set request HTTP status.

Handler Source​

declare
  v_image_blob      blob            := :body;
  v_image_mime_type varchar2(4000)  := :content_type;
  v_image_link      varchar2(4000);  
  v_file_id         number;

  /* without default parameters image filename is not available */
  v_file_name       varchar2(4000)  := 'filename';
begin

  insert into UC_FROALA_SAMPLE_BLOBS(    
    FILE_NAME,    
    FILE_CONTENT,
    FILE_MIMETYPE,    
    SESSION_ID
  ) values(    
    v_file_name,
    v_image_blob,    
    v_image_mime_type,
    null
  ) returning ID into v_file_id;    

  /* The URL to RESTful service GET handler is hardcoded */
  v_image_link := 'https://example-domain.com/ords/workspacename/customrest/display-simple/'||v_file_id;


  /* print JSON to the browser buffer */
  apex_json.open_object;
  apex_json.write('link'         , v_image_link, true);
  apex_json.write('data-image-id', v_file_id   , true);  
  apex_json.close_object;    

  /* set HTTP status code */
  :status_code := 200;
exception
  when others then
    :status_code := 500;
    apex_json.open_object;    
    apex_json.write('error', SQLERRM);  
    apex_json.close_object;  
end;

Handler Output​

When an image is saved in the database table, or any other service hosting images, the handler must print to the browser buffer JSON object containing URL displaying uplaoded image and unique image id.

PropertyTypeDescription
data-image-idVARCHAR2The unique id identyfing uplaoded image. The uploaded image id is then stored in the plug-in session state
linkVARCHAR2The uploaded image URL

The example JSON might look like in the example below.

{
  "data-image-id": "1706",
  "link": "https://example-domain.com/ords/workspacename/customrest/display/1706"
}
display image link & query parameters

Link to uploaded image can include query parameters that can be used in display handler. See example source code Image checksum.

Error handling​

The plug-in relies on HTTP status code set by the upload handler. Specifying HTTP status code results in display different errror message in the plug-in upload summary.

See sample code below presenting displaying custom error message using HTTP status code 500 and JSON printed to the browser buffer.

Upload handler PL/SQL exception handler
begin
  ...
exception 
  when others then
    :status_code := 500;  
    apex_json.open_object;    
    apex_json.write('error', 'Error message to be displayed in the plug-in upload summary');  
    apex_json.close_object;  
end;

403 Forbidden​

The plug-in displays following message:

Uplaod handler: 403 Forbidden

404 Not Found​

The plug-in displays following message:

Uplaod handler: 404 Not Found.

405 Method Not Allowed​

The plug-in displays following message:

Uplaod handler: 405 Method Not Allowed

info

This status code can be assigned, when the plug-in page item attribute Image Upload URL reference RESTful service handler not implementing POST method.

500 Internal Sever Error​

If handler result printed JSON with error property, the plug-in display the error property value. Otherwise the plug-in displays the following message:

Uplaod handler raised an error: 500 Internal Server Error (missin "error" property)

555 User Defined Error​

This HTTP status code is set by ORDS REST when, the upload handler PL/SQL can't be executed when requested. The plug-in displays following message:

Uplaod handler raised error: 555 User Defined Error

note

In contrast to PL/SQL code attributes in page designer, the handler source attribute is not compiled when saving handler changes in SQL Workshop \ RESTful Services.

Other​

If any other HTTP status code is the result of uplaod handler, the plug-in displays the following message:

Unexpected image upload error