Usage

The Image Edit Pro Plugin allows developers to integrate a powerful image editing tool into Oracle APEX applications. This document provides a comprehensive guide on how to use the plugin, including configuration, example save procedures, public JavaScript APIs, and theme customization.

Installation and Setup

Please refer to the Installation guide for detailed instructions on how to install and set up the Image Edit Pro plugin in your Oracle APEX application.

Region Attributes

Key Attributes

Image Blob Column: The database column storing the image as a BLOB.
MIME Type Column: The column storing the MIME type of the image.
Image Title Column: The column storing the title of the image.
Primary Key Column: The column storing the primary key for the image record.
Save Procedure: The PL/SQL procedure to save the edited image back to the database.
Region Height: Can be set to automatic or a fixed height.
Image dimensions: Set the maximum width and height of the image in pixels within the editor. This will not impact the output image.
Editor Tool Options: Select the tools to be displayed in the editor (e.g., Crop, Rotate, Resize, etc.) with a default tool option.
Lazy Loading: Enable or disable lazy loading of the image.
Theme: Choose between White, Dark, or Custom.
Menu Bar Position: Set the position of the menu bar (Top, Bottom, Left, or Right). We recommend using Top for the best user experience.
Displayed Buttons: Select which buttons to display in the editor (Load, Download or Save).

Example Save Procedure

The save procedure is a PL/SQL procedure that updates the image in the database. Below is an example:

PROCEDURE save_image (
    p_id           IN NUMBER, -- or VARCHAR2
    p_image        IN BLOB,
    p_mime_type    IN VARCHAR2,
    p_filename     IN VARCHAR2
) IS
BEGIN
    UPDATE my_image_table
    SET
        image_blob   = p_image,
        mime_type    = p_mime_type,
        image_name   = p_filename
    WHERE image_id = p_id;
END;

Public JavaScript APIs

The plugin exposes several JavaScript APIs for advanced customization and interaction:

Get Edited Image

// Retrieve the edited image as a Base64 string
var editedImage = $("staticRegionId_apeximageedit").apexImageEdit("getImage");

Set Image from URL

// Set a new image in the editor using a URL or Base64 string
$("staticRegionId_apeximageedit").apexImageEdit("setImageFromUrl", "path/to/new-image.jpg");

Save Image

// Save the edited image, which will call the configured PL/SQL procedure
$("staticRegionId_apeximageedit").apexImageEdit("save");

Refresh the Editor

// Refresh the editor to reload the image or settings
$("staticRegionId_apeximageedit").apexImageEdit("refresh");

Set Editor Height

// Set the height of the editor
$("staticRegionId_apeximageedit").apexImageEdit("setEditorHeight", "500px");

Adjust Editor Height Automatically

// Automatically adjust the editor height based on the image size
$("staticRegionId_apeximageedit").apexImageEdit("adjustEditorHeight");

Theme Customization

The plugin supports three themes: White, Dark, and Custom. You can define a custom theme by modifying the customTheme variable.

Custom Theme Example

This variable must be initialized before the plugin is loaded, so it’s recommended to place it in the Function and Global Variable Declaration section of your APEX page or in a separate JavaScript file.

Below is an example of a custom theme configuration, which is used for the “White” theme:

var customTheme = {
  'common.bi.image': 'https://www.united-codes.com/assets/dist/images/logo-united-codes.svg',
  'common.bisize.width': '251px',
  'common.bisize.height': '21px',
  'common.backgroundImage': 'none',
  'common.backgroundColor': '#fff',
  'common.border': '1px solid #c1c1c1',

  // header
  'header.backgroundImage': 'none',
  'header.backgroundColor': 'transparent',
  'header.border': '0px',

  // load button
  'loadButton.backgroundColor': '#fff',
  'loadButton.border': '1px solid #ddd',
  'loadButton.color': '#222',
  'loadButton.fontFamily': "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen,Ubuntu,Cantarell,'Fira Sans','Droid Sans','Helvetica Neue',sans-serif",
  'loadButton.fontSize': '12px',

  // download button
  'downloadButton.backgroundColor': '#343595',
  'downloadButton.border': '1px solid #343595',
  'downloadButton.color': '#fff',
  'downloadButton.fontFamily': "-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen,Ubuntu,Cantarell,'Fira Sans','Droid Sans','Helvetica Neue',sans-serif",
  'downloadButton.fontSize': '12px',

  // main icons
  'menu.normalIcon.color': '#8a8a8a',
  'menu.activeIcon.color': '#555555',
  'menu.disabledIcon.color': '#434343',
  'menu.hoverIcon.color': '#e9e9e9',
  'menu.iconSize.width': '24px',
  'menu.iconSize.height': '24px',

  // submenu icons
  'submenu.normalIcon.color': '#8a8a8a',
  'submenu.activeIcon.color': '#555555',
  'submenu.iconSize.width': '32px',
  'submenu.iconSize.height': '32px',

  // submenu primary color
  'submenu.backgroundColor': 'transparent',
  'submenu.partition.color': '#e5e5e5',

  // submenu labels
  'submenu.normalLabel.color': '#858585',
  'submenu.normalLabel.fontWeight': 'normal',
  'submenu.activeLabel.color': '#000',
  'submenu.activeLabel.fontWeight': 'normal',

  // checkbox style
  'checkbox.border': '1px solid #ccc',
  'checkbox.backgroundColor': '#fff',

  // range style
  'range.pointer.color': '#333',
  'range.bar.color': '#ccc',
  'range.subbar.color': '#606060',

  'range.disabledPointer.color': '#d3d3d3',
  'range.disabledBar.color': 'rgba(85,85,85,0.06)',
  'range.disabledSubbar.color': 'rgba(51,51,51,0.2)',

  'range.value.color': '#000',
  'range.value.fontWeight': 'normal',
  'range.value.fontSize': '11px',
  'range.value.border': '0',
  'range.value.backgroundColor': '#f5f5f5',
  'range.title.color': '#000',
  'range.title.fontWeight': 'lighter',

  // colorpicker style
  'colorpicker.button.border': '0px',
  'colorpicker.title.color': '#000',

  // UC Custom Definitions
  // This will override the "black" ribbon background color
  'uc.mainMenu.backgroundColor': '#000000',
};

Event Bindings

The plugin triggers custom events for additional interactivity.

Available Events

uc_imageedit_afterrefresh: Triggered after the editor is refreshed.
uc_imageedit_aftersave: Triggered after the image is saved.

Example Usage

Event Binding in Oracle APEX

In Oracle APEX, events can be bound declaratively using Dynamic Actions within the App Builder. This approach eliminates the need for custom JavaScript and ensures seamless integration with the APEX framework.

Example: Binding `uc_imageedit_aftersave` Event

Navigate to the Dynamic Actions section of your APEX page.
Create a new Dynamic Action:
- Event: Custom
- Custom Event: uc_imageedit_aftersave
- Selection Type: jQuery Selector
- jQuery Selector: #staticRegionId_apeximageedit (replace with your region’s static ID)
Add a True Action:
- Action: Execute PL/SQL Code or Execute JavaScript Code (depending on your requirement)
- For example, log the saved image data:
```
console.log("Image saved:", this);
```

Example: Binding `uc_imageedit_afterrefresh` Event

Create another Dynamic Action:
- Event: Custom
- Custom Event: uc_imageedit_afterrefresh
- Selection Type: jQuery Selector
- jQuery Selector: #staticRegionId_apeximageedit
Add a True Action:
- Action: Show or any other action to handle the event.
- For example, display a success message:
```
apex.message.showPageSuccess("Editor refreshed successfully.");
```

Using Dynamic Actions ensures that event handling is declarative, maintainable, and fully integrated with Oracle APEX’s native capabilities.

Debugging

Enable debugging by setting the Debug level to option to Application Trace. Debug messages will appear in the APEX debug logs.

Best Practices

Use lazy loading for large images to improve performance.
Define a robust save procedure to handle image updates securely.
Customize the theme to match your application’s design.

For further assistance, see support