Skip to main content

Resource templates

The plug-in is delivered with an example Oracle APEX RESTful service module. The RESTful service module implements required templates to support image handling (upload, browse and delete) and custom templates used by the plug-in sample application.

The RESTful service implements the following templates described in the table below.

TemplateMethodDescription
browseGETTemplate is used to browse previously uploaded images stored in the database.
deletePOSTTemplate is used to delete images displayed in the Froala image browser.
get/:fileidGETTemplate displays uploaded images embedded in CLOB content.
uploadPOSTTemplate handles image upload using.
browseFolderGETAn example implementation showing image filtering using custom parameter folder.
uploadFolderPOSTAn example implementation of uploading images with a custom parameter folder.

The sample RESTful service uses the plug-in example package UC_FROALA_SAMPLE_REST.

All templates use the parameter X-APEX-STATUS-CODE to return the HTTP status of the request.

get/:fileid GET​

The template displays uploaded and embedded images in rich HTML text. An URL to an image is computed and returned by the upload template.

Parameters​

The template is requested with the default one parameter fileid described in the table below.

ParameterBind variableAccess MethodSource TypeDescription
fileid:fileidINURIAn image ID to be deleted.
location:locationOUTHTTP HEADERAn image URL to fetch an image contents.
X-APEX-STATUS-CODE:statusOUTHTTP HEADERThe HTTP status code returned by ORDS.

Source​

The plug-in template handler uses the example package procedure UC_FROALA_SAMPLE_REST.imageGet.

begin    
  UC_FROALA_SAMPLE_REST.imageGet(  
    p_file_id  => :fileid,  
    p_status   => :status,  
    p_location => :location
  );  
end;

Output​

The template handler output to the output buffer must be requested image contents with required HTTP headers. See an example code below.

procedure imageGet(
  p_file_id  in number,  
  p_status   out integer,  
  p_location out varchar2
) is
  v_image_url     varchar2(4000); -- an URL to the requested image
  v_file_mimetype varchar2(4000); -- an image mime type
  v_file_content  BLOB;           -- an image BLOB content
begin
  /*
    here should be the code 
    - fetching an image BLOB from the database table (v_file_content),
    - fetching an image mime type (v_file_mimetype)
    - computing an image URL (v_image_url)
  */

  p_status := 200;  
  p_location := v_image_url;

  sys.HTP.init;  
  sys.OWA_UTIL.mime_header(v_file_mimetype, FALSE);  
  sys.HTP.p('Content-Length: ' || DBMS_LOB.getlength(v_file_content));  
  sys.HTP.p('Access-Control-Allow-Origin: *');  
  sys.OWA_UTIL.http_header_close;  

  sys.WPG_DOCLOAD.download_file(v_file_content);    
end;

Custom Parameters​

Adding a new URL query parameter can be done by updating the template attribute URI Template. The example URI template below includes two new URL query parameters, a and b.

http://www.apexrnd.be/ords192/pluginsplus/ucfroalaapi/get/:fileid?a=1&b=2

The template handler can reference new parameters using bind variables :a and :b. The example code below presents a PL/SQL procedure accepting new parameters.

begin    
  customImageGet(  
    p_file_id        => :fileid,  
    p_custom_param_a => :a,
    p_custom_param_b => :b,      
    p_status         => :status,  
    p_location       => :location
  );  
end;

browse GET​

The template is used to display the gallery of uploaded images. The example implementation fetches all images uploaded to the plug-in table UC_FROALA_SAMPLE_BLOBS.

Parameters​

The template handler is requested with the default five URL query parameters described in the table below.

ParameterBind variableAccess MethodSource TypeDescription
sessionId:sessionIdINQuery ParameterA current APEX session ID.
accessToken:accessTokenINQuery ParameterA current ancoded access token.
appUser:appUserINQuery ParameterA current application username.
applicationId:applicationIdINQuery ParameterA current application ID.
pageId:pageIdINQuery ParameterA current application page ID
X-APEX-STATUS-CODE:statusOUTHTTP HEADERThe HTTP status code returned by ORDS

Source​

The example template handler uses the example procedure UC_FROALA_SAMPLE_REST.imageBrowse. 

begin  
  UC_FROALA_SAMPLE_REST.imageBrowse(  
    p_session_id      => :sessionId,  
    p_access_token    => :accessToken,
    p_app_user        => :appUser,
    p_application_id  => :applicationId,
    p_page_id         => :pageId,
    p_status          => :status
  );  
end;

Output​

The template handler output printed to the output buffer must be an array of images in JSON notation. Each image must be defined as a JSON object having properties described in the Froala API imageManagerLoadURL.

The table below presents an image JSON object.

PropertyTypeDescriptionRequired
urlStringAn image URL
thumbStringAn image thumb URL
tagStringFroala docs do not describe how the editor uses the tag property.

An example output

[
  {
    "URL":"https://apex.oracle.com/pls/apex/examplerest/ucfroalasamplerest/browse/get/614"
  }
]

Custom parameters​

The template PL/SQL handler can be customized using custom URL query parameters.

A custom parameter can be added using the following methods:

  • using an advanced item attribute JavaScript Initialization Code
  • using the supporting dynamic action plug-in United Codes Rich Text Editor Pro (Extend)

An item attribute JavaScript Initialization Code is evaluated only once on a page load when the plug-in is rendered. Thus, it's static until the page is reloaded. To evaluate the custom URL query parameters value each time an image browser is opened, the supporting dynamic action plug-in United Codes Rich Text Editor Pro (Extend) must be used.

JavaScript Initialization Code

An advanced item attribute JavaScript Initialization Code value must be an anonymous JavaScript function returning the Froala options, including the Froala option imageManagerLoadParams.

function( pOptions ) { 
  pOptions.imageManagerLoadParams = {"customParam": "paramValue"};

  return pOptions;
}

A new parameter customParam can be referenced in the template handler using the bind variable :customParam.

The supporting dynamic action plug-in

Using the supporting plug-in United Codes Rich Text Editor Pro (Extend) enables a developer to define an anonymous JavaScript function evaluated each time the end user opens an image browser.

The supporting plug-in action Image Browser Parameters expects an anonymous JavaScript function accepting JSON object. The JSON object can be extended to include a new parameter(s).

See an example implementation below.

function( pParams ) { 
  pParams.customParam = apex.item('P4_UPLOAD_FOLDER').getValue(); 
    
  return pParams; 
}

A new parameter customParam can be referenced in the template handler using the bind variable :customParam.

Read the section Supporting Plug-ins \ Dynamic Action \ Image Browser Parameters to learn more about the supporting dynamic action plug-in.

How to open the image browser​

The end-user must display the image browser using the plug-in editor toolbar button. See the screenshots below.

image-20230304200106681

image-20230304200138081

upload POST​

The template is used to upload images on a page submission.

Uploading images must be enabled using the plug-in attribute Upload Image(s) on Request(s). Learn more about the attribute in the section Item Plug-in \ Custom Attributes \ Component \ Upload Image(s) on Request(s).

Parameters​

The template is requested with seven URL query parameters described below. The handler uses ORDS implicit parameters body and content_type.

ParameterBind variableAccess MethodSource TypeTypeDescription
accessToken:accessTokenINQuery ParameterVARCHAR2A current ancoded access token.
sessionId:sessionIdINQuery ParameterVARCHAR2A current APEX session ID.
applicationId:applicationIdINQuery ParameterVARCHAR2A current application ID.
pageId:pageIdINQuery ParameterVARCHAR2A current application page ID
appUser:appUserINQuery ParameterVARCHAR2A current application username.
filename:filenameINQuery ParameterVARCHAR2An image filename.
tempUniqueId:tempUniqueIdINQuery ParameterVARCHAR2An image temporary ID assigned by the plug-in.
body:bodyINBLOBSpecifies the request's body as a temporary BLOB.
content_type:content_typeINHTTP HEADERVARCHAR2Specifies the MIME type of the request body, as indicated by the Content-Type request header.
location:locationOUTHTTP HEADERVARCHAR2An image URL after upload.
X-APEX-STATUS-CODE:statusOUTHTTP HEADERINTEGERThe HTTP status code returned by ORDS

Source​

The template POST handler uses the example package procedure UC_FROALA_SAMPLE_REST.imageUpload.

begin  
  UC_FROALA_SAMPLE_REST.imageUpload(  
    p_access_token   => :accessToken,  
    p_session_id     => :sessionId,  
    p_application_id => :applicationId,  
    p_page_id        => :pageId,  
    p_app_user       => :appUser,  
    p_image_name     => :filename,  
    p_image_content  => :body,  
    p_image_mimetype => :content_type,
    p_image_temp_id  => :tempUniqueId,
    p_status         => :status,  
    p_location       => :location  
  );    
end;

Output​

The template handler output to the output buffer must be a JSON object describing an uploaded image. An image JSON specification is described in the table below.

PropertyTypeDescriptionRequired
data-image-idStringAn image ID stored in the database table.
data-image-temp-idStringA temporary image ID assigned by the plug-in (bind variable :tempUniqueId)
linkStringAn image URL to be used by the template displaying an image.

Learn more about the image upload output in the Froala Image upload concept.

An example output

{
  "data-image-id": 1706,
  "data-image-temp-id": "ui-id-4",
  "link": "https://apex.oracle.com/pls/apex/examplerest/ucfroalasamplerest/get/1706"
}

Custom Parameters​

The template handler can be customized using URL query parameters available on the PL/SQL level using bind variables. Adding a custom parameter can be done using the following:

  • the plug-in JavaScript Initialization Code attribute
  • the supporting dynamic action plug-in United Codes Rich Text Editor Pro (Extend)

JavaScript Initialization Code

To add custom URL query parameters, define the plug-in attribute JavaScript Initialization code. The anonymous function result must include a JSON object referencing the Froala imageUploadParams.

function( pOptions ) { 
  pOptions.imageUploadParams = {"customParam": "paramValue"};

  return pOptions;
}

The customParam can be referenced in the template PL/SQL code using the bind variable :customParam.

A custom parameter added using JavaScript Initialization Code is static until the page is reloaded. It is because the item attribute is evaluated once on a page load when the plug-in is rendered.

To evaluate the custom URL query parameters value each time an image browser is opened, the supporting dynamic action plug-in United Codes Rich Text Editor Pro (Extend) must be used.

The supporting dynamic action plug-in

The supporting plug-in United Codes Rich Text Editor Pro (Extend) enabled developers to compute custom parameters each time an image is uploaded. The supporting plug-in uses an anonymous JavaScript function returning JSON object containing new parameters to be added to the template handler using URL query parameters.

An example JavaScript function is presented below.

function( pParams ) { 
  pParams.customParam = apex.item('P4_UPLOAD_FOLDER').getValue(); 
    
  return pParams; 
}

The custom parameter named customParam can be referenced in the handler PL/SQL code using bind variable :customParam.

Read the section Supporting Plug-ins \ Dynamic Action \ upload Parameters to learn more about the supporting dynamic action plug-in.

delete POST​

The template is used to delete uploaded images using the RESTful service on the end-user request using the Froala editor. The example template implementation deletes images uploaded to the plug-in table UC_FROALA_SAMPLE_BLOBS.

Parameters​

The template is requested with the default six parameters described in the table below.

ParameterBind variableAccess MethodSource TypeDescription
sessionId:sessionIdINQuery ParameterA current APEX session ID.
accessToken:accessTokenINQuery ParameterA current ancoded access token.
appUser:appUserINQuery ParameterA current application username.
applicationId:applicationIdINQuery ParameterA current application ID.
pageId:pageIdINQuery ParameterA current application page ID.
imageId:imageIdINURIAn image ID to be deleted.
X-APEX-STATUS-CODE:statusOUTHTTP HEADERThe HTTP status code returned by ORDS.

Source​

The plug-in template uses the example package procedure UC_FROALA_SAMPLE_REST.imageDelete.

begin
  UC_FROALA_SAMPLE_REST.imageDelete(  
    p_access_token   => :accessToken,  
    p_session_id     => :sessionId,  
    p_application_id => :applicationId,  
    p_page_id        => :pageId,  
    p_app_user       => :appUser,  
    p_image_id       => :imageId,  
    p_status         => :status  
  );
end;

Output​

The plug-in does not interpret the template result printed to the output buffer. The delete request can be only successful (200 HTTP status ) or unsuccessful (HTTP status 4xx or 5xx).

Custom Parameters​

The template PL/SQL logic can be customized using custom URL query parameters. To add a custom parameter define an item attribute Advanced \ JavaScript Initialization Code.

The function result has to include the Froala imageManagerDeleteParams.

function( pOptions ) { 
  pOptions.imageManagerDeleteParams = {"customParam": "paramValue"};

  return pOptions;
}

The customParam can be referenced in the template PL/SQL code using the bind variable :customParam.

A custom parameter added using JavaScript Initialization Code is static until the page is reloaded. It is because an item JavaScript Initialization Code is evaluated once on a page load when the plug-in is rendered.

How to delete an image​

The end-user has to display an image browser using the plug-in toolbar button. See the screenshots below.

image-20230304200106681

image-20230305192314229