在 Card Region 顯示多張圖片
使用 Carousel 的方式,在 Card Region 中顯示多張圖片
Introduction
我們想要在 Card Region 中以 Carousel 的方式顯示多張圖片。
Moreaux [1] 提供了一個逐步指南,在 Oracle APEX card region 中添加圖片輪播。
但是,該指南使網路上的圖片的 URL。在這文件中,我們將使用表格中的 blob 欄位,而非網路上的其它圖片。
程序
S1. 為 Products 表格建立一個表單(Form)
附註: 如果使用 RESTful Web Service 提供圖片下載,則不需要這個步驟。
我們需要為 Products 表格建立一個表單(Form),以取得使用 APEX_UTIL.GET_BLOB_FILE_SRC
時需要旳 Display Image
item。
使用 Page Wizard 為 Products 表格建立一個表單。
將 Product_Image
blob 欄位對應的 Form Item 的型態設定為 Display Image
。

之後設定該 Item 的 Settings 相關屬性:
Filename Column
MIMI Type Column
BLOB Last Updated Column
填入表格上對應到上述屬性的欄位名稱。

之後,我們會在 APEX_UTIL.GET_BLOB_FILE_SRC
中使用到這個 Item 的名稱(P3_PRODUCT_IMAGE
)。
S2. 設定 Card Region 中的 SQL Query 做為資料來源
新增一 page, 並加入一個 Card Region。
設定此 Card Region 的 Source 相關屬性:

-- first subquery to get the image urls from the blob column
with image_blob_src as (
select product_id,
APEX_UTIL.GET_BLOB_FILE_SRC(p_item_name => 'P3_PRODUCT_IMAGE',
p_v1 => product_id) img_src
from products),
-- second subquery to get the product name, category and image urls
product_image_urls as (
select PRODUCT_ID,
pc.PRODUCT_NAME,
pc.CATEGORY,
ibs.img_src image_url
from PRODUCT_WITH_CATEGORY pc join image_blob_src ibs using (product_id))
-- main query to get the category and list of image urls
-- Assume that each category has multiple images
select pu.category,
listagg(pu.image_url, '|') within group (order by pu.product_id) url_list
from product_image_urls pu
group by pu.category;
在上述的 SQL Query 中:
我們使用了
APEX_UTIL.GET_BLOB_FILE_SRC
來取得圖片的 URL。因為一個 Card 中可能會有多張圖片,所以在 main query 中,我們使用
listagg
函數來將每個 category 的圖片 URL 串接成一個字串,並以|
分隔。後續在 HTML Expression 中,我們會使用這個字串欄位來建立多個圖片 的URL,以便在輪播中顯示。參考 [2] 用到的技巧。
S3. 設定 Card Region 中的 Media 的 HTML 內容 及 Media 要套用的 CSS Class
選擇 Card Region > Attributes Media
啟用 Advanced Formatting 選項。

在 Media 中,設定 CSS Class 為 carousel_media
。

在 HTML Expression 中,設定如下的 HTML 內容:
<div class="carousel_container">
{loop "|" URL_LIST/}
<div class="carousel_snap" >
<img class="carousel_image" loading="lazy" src="&APEX$ITEM."
data-num="&APEX$I." ></img>
</div>
{endloop/}
</div>
<div class="carousel_dots">
{loop "|" URL_LIST/}
<span class="fa fa-circle carousel_dot" data-num="&APEX$I."></span>
{endloop/}
</div>
第一個 div 中的 URL_LIST
是資料來源中的欄位。該欄位存放多個圖片的 URL , 並以 |
分隔。
{loop/}{endloop/}
為 Apex 23.1 的 Template Directive。在此,我們使用它來迭代 URL_LIST
中的每個 URL。
迭代過程中,&APEX$ITEM.
為當前迭代的 URL。&APEX$I.
為當前迭代的索引。
第二個 div 中的 carousel_dots
是用來顯示輪播指示器的。 data-num
屬性用來標識圖片的索引
S4. 設定 Card Region 中的 CSS Class
在 Page > CSS > Inline 中新增以下 CSS 內容[1]:
.card-title {
font-weight: bolder;
}
.card-subtitle {
font-weight: lighter;
font-size: smaller;
}
.carousel_media {
flex-direction: column;
padding: 0px;
height: 300px;
}
.carousel_container {
display: flex;
overflow-x: scroll;
scroll-behavior: smooth;
scroll-snap-type: x mandatory;
height: 300px;
column-gap: 1rem;
width: 100%;
}
.carousel_snap {
scroll-snap-align: center;
display: flex;
flex-basis: 100%;
flex-shrink: 0;
}
.carousel_image {
width: 80%;
object-fit: cover;
}
.carousel_dots {
display: flex;
position: absolute;
bottom: .5rem;
gap: 0.5rem;
color: gainsboro;
}
原理說明: 捲動時同步輪播的指示器(Synchronizing the Carousel Indicators while Scrolling)
技術要求,當某個卡片進入畫面時,對應的輪播指示器要改變 icon class。
使用 Intersection Observer API,可以監聽元素進入畫面的事件。範例參考 [2]。
我們會建立一個觀察者(Observer), 並告訴它要監聽哪個元素.
當被監聽的元素與觀察者所設定的根節點(root element)有交集時(intersection),觀察者會執行 callback function。
建立觀察者時,要傳入一個 callback function,及一個 options 物件。
Options 物件可以設定以下屬性:
root: 觀察者的根節點。如果沒有設定,則預設為 viewport。
rootMargin: 根節點的邊界。可以設定為一個字串,例如 "10px 10px 10px 10px",或是一個物件,例如 {top: 10, right: 10, bottom: 10, left: 10}。使用此屬性擴展或縮小 root 元素的 box 的範圍,以便提早或延遲觸發 intersection event。
threshold: 一個介於 0 到 1 之間的數字,表示觸發的交集比例。例如 0.5 表示監聽元素已顯示一半時,觸發 callback function。可用陣列表示多個觸發點,例如 [0, 0.25, 0.5, 0.75, 1]。
在 callback function 中,可以取得進入畫面的一或多個被監聽的元素(entries),及觀察者(Observer)本身。 在 callback function 中,對每個 entry 做處理,例如改變元素的樣式,如下程式碼所示:
let callback = (entries, observer) => {
entries.forEach((entry) => {
// Each entry describes an intersection change for one observed
// target element:
// entry.boundingClientRect
// entry.intersectionRatio
// entry.intersectionRect
// entry.isIntersecting
// entry.rootBounds
// entry.target
// entry.time
});
};
總結來說,Intersection Observer API 的使用程序如下:
建立觀察者的選項及 callback function。
let options = {
root: document.querySelector("#scrollArea"), // 監聽的根節點. set null to use viewport
rootMargin: '0px',
threshold: 0.5
};
let callback = (entries, observer) => {
entries.forEach((entry) => {
// Each entry describes an intersection change for one observed
// target element:
// entry.boundingClientRect
// entry.intersectionRatio
// entry.intersectionRect
// entry.isIntersecting
// entry.rootBounds
// entry.target
// entry.time
});
};
建立觀察者物件
let observer = new IntersectionObserver(callback, options);
將被監聽的元素加入觀察者。
let target = document.querySelector('#target');
observer.observe(target);
S5. 在 Card Region 中使用 Intersection Observer API 更新 Carousel Indicators
參考 [1] 的步驟。
S5.1 增加 Dynamic Action 以建立 Intersection Observer
在 Cards Region 中新增一個 Dynamic Action(DA), 當事件為 Page Change[Cards] 時,執行 JavaScript Code,以建立 Intersection Observer。
DA 的 WHEN
相關屬性如下:

接著,增加一個 True Action, 類型為 Execute JavaScript Code.

JavaScript 內容如下:
// Loop through all the carousel containers
// 找出所有的輪播容器 (class 為 carousel_container 的 div)
document.querySelectorAll(".carousel_container").forEach(
function(container){
// container 為選到的輪播容器
//Declare the IntersectionObserver options
let options = {
root: container,
rootMargin: "0px",
threshold: [0.5, 1]
};
// Create the observer
// intersectionCallback 另外定義
let observer = new IntersectionObserver(intersectionCallback, options);
//Get all the images inside the container
let images = container.querySelectorAll("img");
// Loop through all images and start observe it
// 設定所要觀察的圖片
images.forEach(function(image){
observer.observe(image);
});
});
接著再設定此 Action 的 Execution 相關屬性, 啟用 Fire on Initialization. 如此,當頁面載入時,就會執行此 Action。

S5.2. 定義 Intersection Observer 的 callback function
在 Page 的 Function and Global Variable Declaration 中新增一個 JavaScript Function,做為 Intersection Observer 的 callback function。

在 Card 中的 Media 的 html 元素結構如下:
<div class="carousel_container">
{loop "|" URL_LIST/}
<div class="carousel_snap" >
<img class="carousel_image" loading="lazy" src="&APEX$ITEM." data-num="&APEX$I." ></img>
</div>
{endloop/}
</div>
<div class="carousel_dots">
{loop "|" URL_LIST/}
<span class="fa fa-circle carousel_dot" data-num="&APEX$I."></span>
{endloop/}
</div>
配合上述的 html 元素結構,新增的 Intersection Observer 的 callback function 如下:
function intersectionCallback(entries) {
// Private function used to update the dots
function updateDots(container, num){
// container 為輪播容器, class 為 carousel_container 的 div
// num 為圖片的編號,放在 data-num 屬性中
// Get all the individual spans of the class carousel_dot
let dots = container.nextElementSibling.querySelectorAll(".carousel_dot");
//Loop through the dots
dots.forEach(function(dot){
// extract the data-num attribute
let dotNum = dot.getAttribute("data-num");
//Add or remove the dot's classes depending on whether it's the selected image or not
if (dotNum === num ) {
dot.classList.remove("fa-circle-o");
dot.classList.add("fa-circle");
} else {
dot.classList.add("fa-circle-o");
dot.classList.remove("fa-circle");
}
});
}
// This loops through the entries providing in the callback
entries.forEach((entry) => {
//If the image is 100% visible
if (entry.isIntersecting === true && entry.intersectionRatio === 1) {
// Get the image, image num and parent to update the dots
let image = entry.target;
let parent = image.closest(".carousel_container");
let imageNum = image.getAttribute("data-num");
updateDots(parent, imageNum);
}
});
}
結果

使用 RESTful Web Service 取得圖片 url
使用 RESTful Web Service 提供圖片下載。
因為,使用 APEX_UTIL.GET_BLOB_FILE_SRC
來取得圖片的 URL 會相依於某個 Display Image
item。
我們會在 img
標籤的 src
屬性中,改使用 RESTful Web Service 的 URL。
S1. Enable the REST service in the PROJECT3 schema [5].
在 Schema 中啟用 RESTful Web Service。
啟用時,沒有使用自動授權,以利測試。
DECLARE
PRAGMA AUTONOMOUS_TRANSACTION;
BEGIN
ORDS.ENABLE_SCHEMA(p_enabled => TRUE,
p_schema => 'PROJECT3',
p_url_mapping_type => 'BASE_PATH',
p_url_mapping_pattern => 'project3',
p_auto_rest_auth => FALSE);
commit;
END;
S2. Create a RESTful Web Service Module in the Apex.
Path: SQL Workshop > RESTful Services 建立新的 RESTful Web Service Module。
Click Modules > (B)[Create Module]

Enter:
Module Name:
img
Base Path:
/img/
之後在 Full URL Path 中會顯示此 module 的完整 URL。

完成 Module 的建立後,我們要建立在此 Module 下的 Resource 的 URI Template。
S3. Create a Resource Template in the RESTful Web Service Module.
點選在 Module 下方的 (B)[Create Templates]。

輸入 URI Template: fetch/:id
其中 :id
是一個路徑參數,表示要取得的圖片的 id,他是一個 bind variable, 可直接在 SQL 或 PL/SQL 中使用。

完成 Resource URI Template 的建立後,我們要設定此 Resource 的 Handler, 用以處理在此 URI 下的不同的 HTTP Method 的請人求。
S4. Create a Handler for the Resource URI Template.
點選在 Resource URI Template 下方的 (B)[Create Handler]。

輸入以下資訊:
Method:
GET
Source Type: Media Resource

之後,在 Source 中,設定 SQL Query:
select 'image/jpeg', product_image
from products
where product_id = :id
其中:
若 Source Type 為 Media Resource, Query 中的第一個 column 代表 MIME Type, 第二個 column 代表圖片的 binary data。
:id
: 為 URI Template 中的路徑參數。
完後按 (B)[Apply Changes]。
S5. Test the RESTful Web Service.
把 RESTful Web Service 的 URL 貼到瀏覽器中,並在 URI 中加入路徑參數,應該可看到圖片。

S6. 修改 Card Region 中的 SQL Query
with image_blob_src as (
select product_id,
'/ords/project3/img/fetch/' || product_id as img_src -- Modification: generate the url for the image
from products),
product_image_urls as (
select PRODUCT_ID,
pc.PRODUCT_NAME,
pc.CATEGORY,
ibs.img_src image_url
from PRODUCT_WITH_CATEGORY pc join image_blob_src ibs using (product_id))
select pu.category,
listagg(pu.image_url, '|') within group (order by pu.product_id) url_list
from product_image_urls pu
group by pu.category;
在修改處,原本使用 APEX_UTIL.GET_BLOB_FILE_SRC
來取得圖片的 URL, 現在改為直接使用 RESTful Web Service 的 URL 加上路徑參數。
好處是,我們不再需要使用某面中的 Display Image
item 來取得圖片。使用 APEX_UTIL.GET_BLOB_FILE_SRC
會相依於某個 Display Image
item. 使用 RESTful Web Service 的方式可以解除這個相依性。
References
[1] Moreaux, L., 2023. Step-by-Step Guide for Adding an Image Carousel to the Oracle APEX Card Region
[2] 超好用的 Web API - Intersection Observer
[3] Intersection Observer API - Web APIs | MDN
[4] Azmi, A., 2022. Get Picture url which stored as BLOB & show it in Oracle APEX
Last updated
Was this helpful?