APEX AJAX and how to use apex.server.process

Pada kasus pemkaian dynamic biasanya kita telah terbiasa memakai fitur dari APEX yaitu Dynamic Action (DA). DA merupakan salah satu fitur terbaik yang dimiliki oleh APEX untuk melakukan proses AJAX dan hal lain dengan secara declarative dan bisa di gabunkan dengan kondisi dan sekuriti. Namun pada kasus-kasus khusus  nanti kita tetap perlu untuk membangun AJAX secara manual tanpa atau dikombinasikan dengan DA.

APEX telah menyediakan API untuk hal ini, namun sayang sangat ringkas sehingga perlu try-error untuk memahaminya. Tulisan Tom Petrus sangat mencerahkan dan detail untuk memahami hal ini. saya sangat merekomendasikan untuk membacanya untuk memahami gambaran besar APEX AJAX. 

Adapun hal yang harus diperhatikan adalah APEX AJAX adalah :

• Gunakan documented API dalam hal ini (apex.server.process) untuk pembuatan proses AJAX supaya dalam perkembangannya jika aplikasi di migrasi ke versi yang terbaru tidak muncul masalah.
• Dalam apex.server.process return default adalah JSON, jadi hati-hati karena meskipun kita telah membangun data dengan konstruksi JSON jika dilakukan lewat PL/SQL maka akan selalu menjadi string atau text, jadi untuk proses ini salalu gunakan opsi = dataType: "text". Setelah itu dalam proses JS kita bisa parsing kedalam JSON object memakai jQuery.parseJSON(pData)
• Opsi = success agak membingunkan sering diartikan bahwa disitu untuk hadle proses sukses saja, namun sebenarnya adalah untuk funsi callback yang dilakukan setelah memperoleh return data dari proses pl/sql.
• Cara melakukan passing parameter, item, value dan array.

Silahkan akses contoh pemakaiannya di demo ini disitu akan diperlihatkan contoh code javascript dan pl/sql yang digunakan. Selamat mencoba.

Miscellaneous Javascript APIs

• $x(pNd)
Adalah sebuah padanan dari getElementById(). Dengan pNd adalah id dari DOM atau string "id". returnnya adalah DOM element atau false jika tidak ada.
contoh : $x(P43_TEXT) atau $x("P43_TEXT").
Pemakaian untuk get: $x("P43_TEXT").value, $x("P43_TEXT").name
Pemakaian untuk set: $x("P43_TEXT").value="Test", $x("P43_TEXT").name="test"
Namun tidak semua jenis item dapat dilakukan operasi tersebut seperti checkbox, selectlist dan shuttle.
• $v(pNd), $v2(pNd), apex.item(pNd).getValue(),$f_SelectValue(pNd) dan $("#pNd").val()
Semuanya pada dasarnya adalah untuk mendapatkan value dari sebuah item, namun memiliki beberapa perbedaan. Pada test kasus item berikut :
• Hidden, text, text area, date picker, popup lov (basis input) semua berhasil memperoleh value, khusus untuk display only $("#pNd").val() memakai $("#pNd").text()
• selectlist, checkbox, radiogroup, list manager hanya $v(pNd) $v2(pNd) apex.item(pNd).getValue() dan $f_SelectValue(pNd) yang bisa memperoleh value
• $v2(pNd) adalah shortcut untuk apex.item(pNd).getValue()
• untuk kasus item multiple value perbedaan dari $v(pNd) dan $v2(pNd) adalah $v(pNd) mendapatkan nilai persis string dari item sedangkan $v2(pNd) dalam bentuk array
Kesimpulan yang dapat diambil adalah selalu gunakan APEX APIs $v(pNd) atau $v2(pNd) untuk mengambil nilai item.
• $s(pNd, pValue, pDisplayValue, pSuppressChangeEvent), apex.item( pNd ).setValue(pValue, pDisplayValue, pSuppressChangeEvent), $x_Value(pNd,pValue) dan $("#pNd").val("pValue")
Sama halnya dengan kasus get selalu gunakan APEX APIs, $s(pNd, pValue, pDisplayValue, pSuppressChangeEvent) adalah shortcut untuk apex.item( pNd ).setValue(pValue, pDisplayValue, pSuppressChangeEvent). Kelebihan dari $s( pNd,pValue, pDisplayValue, pSuppressChangeEvent) adlah kita bisa melakukan pada semua jenis item dengan bisa mengatur pSuppressChangeEvent property ini berguna dalam urusan Dynamic Actions
• Silahkan coba fungsi2 diatas pada page demo berikut

Get Yahoo Exchange Rate using PL/SQL

Setelah mencari api yang disediakan oleh Bank Indonesia atau bank-bank swasta/nasional indonesia tidak tersedia. maka dengan terpaksa kebutuhan exchange rate real time saya ambil dari yahoo api.

Melalui Yahoo Query Language kita dapat peroleh URI untuk exchange rate USD-IDR :

http://query.yahooapis.com/v1/public/yql?q=select * from yahoo.finance.xchange where pair in ("USDIDR")&env=store://datatables.org/alltableswithkeys

Lalu kemudian kita bangun fungsi didalam oracle untuk bisa dipakai dalam operasi sql pl/sql atau di APEX.

create or replace function get_yahoo_rate 
return number 
is

/******************************************************************************
   NAME:       get_yahoo_rate
   PURPOSE:    get latest USD-IDR rate from Yahoo finance exchange

   REVISIONS:
   Ver        Date        Author           Description
   ---------  ----------  ---------------  ------------------------------------
   1.0        10/10/2014   Lutfi Hedir     1. Created this function.

******************************************************************************/
  l_xml xmltype;
  l_yahoo_uri constant varchar2(500) := 'http://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20yahoo.finance.xchange%20where%20pair%20in%20(%22USDIDR%22)&env=store://datatables.org/alltableswithkeys';
  l_rate      varchar2(500);
  l_rate_n    number(10);
begin
  -- get xml data
  l_xml := xmltype(utl_http.request(l_yahoo_uri));
  -- extract rate value from xml data  
  select extractvalue(l_xml, '/query/results/rate/Rate/text()') into l_rate
    from dual;  
  -- convert to number   
  l_rate_n := to_number(REGEXP_SUBSTR(l_rate,'[0-9]+'));
  
  return l_rate_n;
  
end get_yahoo_rate;
/

Catatan :

• Jangan lupa setting ACL untuk 11g supaya bisaakses internet.
• Jika akses SSL buatlah wallet terlebih dahulu
• Jika akses proxy modifikasi utl_http.request dengan signature proxy dan wallet

How to get CGI environment

Melalui value dari CGI kita bisa mengetahui IP address client yang akses, user agent dan lainnya. Melalui package OWA_UTIL kita bisa peroleh dengan sub program GET_CGI_ENV. namun dengan GET_CGI_ENV kita harus menentukan masing-masing parameter name untuk memperolehnya.

Untuk mempersingkat code bisa gunakan teknik berikut. dengan catatan bahwa nama dan value yang akan diperoleh tergantung dari web server yang dipakai APEX.

BEGIN
htp.prn('<tr>');
htp.prn('<th>CGI Variable Name</th>');
htp.prn('<th>CGI Variable Value</th>');
htp.prn('</tr>');
FOR i IN 1..owa.num_cgi_vars LOOP
htp.prn('<tr> <td align="left">'||owa.cgi_var_name(i)||'</td> <td align="left">'||owa.cgi_var_val(i)||'</td> </tr>');
END LOOP;
END;

Kita coba implementasikan ke dalam APEX dengan memakai Region PL/SQL Dynamic Content seperti contoh ini

Implementasi Session State Protection

Salah satu feature APEX untuk menangkal serangan URL tampering adalah mengaktifkan Session State Protection. User yang mengerti konsep syntax URL APEX sangat mudah untuk melakukan perubahan session state (contoh nilai page item) memakai URL.

Session State Protection bisa diaktifkan melalui Home>>Application Builder>>Application XXX>>Shared Components>>Session State Protection>>Set Application Protection.

Implikasinya kita harus menyediakan sebuah URL dengan sebuah checksum pada link-link yang tidak disediakan melalui standard branching APEX seperti memakai js popup , jquery modal atau Tree link. URL tersebut dimodifikasi memakai APEX API PREPARE_URL Function. berikut contoh penggunaannya.

1. Tree

select case when connect_by_isleaf = 1 then 0
            when level = 1             then 1
            else                           -1
       end as  status, 
       level,
a.description as title,            
     '#WORKSPACE_IMAGES#myicon.gif'   as icon, 
       a.ALIAS as value, 
       a.TOOLTIP_MENU as tooltip, 
       case when a.status in ('F','R') then
        APEX_UTIL.PREPARE_URL('f?p=&APP_ID.:'||a.ALIAS||':&SESSION.::NO:CIR:P1_SELECTED_NODE:'||a.ALIAS) 
       else
        APEX_UTIL.PREPARE_URL('f?p=&APP_ID.:1:&SESSION.::NO:CIR:P1_SELECTED_NODE:'||a.ALIAS)
       end as link 
from TREE_MENU01 a
start with a.STATUS ='X'
connect by prior a.ID = a.MENU_ID
order siblings by a.SEQ

2. Report dengan js popup

select ' Order #' || o.order_id || '' edit, 
p.product_name, oi.quantity, oi.unit_price, (oi.quantity * oi.unit_price) ext_price, o.user_name, o.order_timestamp
from demo_orders o, demo_order_items oi, demo_product_info p
where customer_id = :P7_CUSTOMER_ID
and o.order_id = oi.order_id
and oi.product_id = p.product_id
order by o.order_id, o.order_timestamp, o.user_name

Catatan : Kita sebenarnya bisa me non-aktifkan sebagian page dan item yang memakai pop-up atau modal menjadi unrestricted sehingga tidak perlu memakai APEX_UTIL.PREPARE_URL, karena pada dasarnya URL untuk pop-up dan modal tidak bisa di edit bukan? kecuali untuk link tree atau report/button yang memakai javascrip code untuk redirect non pop-up atau modal tetap memakai APEX_UTIL.PREPARE_URL.

Sumber: Oracle® Application Express API Reference Release 4.1

ORA-20001: You have exceeded the maximum number of email messages per workspace. Please contact your administrator.

Error tersebut terjadi karena:
Ternyata APEX membatasi pengiriman email melalui APIs APEX_MAIL.SEND. dengan default 1000 email per 24 jam.
Setting tersebut anda atur di  WS : internal

Home >>Manage Instance >>Instance Settings
Tab  : Email
Item : Maximum Emails per Workspace
Ubahlah nilainya menjadi : 10000 atau 10000

Escape special character on query

Masalah muncul ketika data query mengandung karakter special seperti : ',". saat kita pakai JS untuk mengambil nilai tsb (kasus saya popup passback).

Berikut solusi yang saya peroleh dari oracle APEX forum (thanks patrick wolf).

1. Lakukan modifikasi query report dengan memakai apex_javascript.escape

...
 select nama,apex_javascript.escape(nama) as nama_esc,email
 from tab_dummy
 ...

2. Sembunyikan kolom yang telah di escape (nama_esc) menjadi hidden column
3. Refensikan kolom tersebut pada kode js

javascript:passBack('#NAMA_ESC#','#EMAIL#');

My Demo

Membuat Readonly Dynamic di Manual Tabular Form

Jika kita ada kebutuhan untuk membuat text item bersifat dinamis, contoh: kita hanya boleh merubah data gaji yang kosong sedangkan yang sudah terisi tidak boleh di ubah.
berikut contoh :

select ename,empno,
case 
when sal is not null then
 apex_item.text (3, sal, 20, 20,'style="text-align:right" readonly="1"','f03_' || '#ROWNUM#')
else
 apex_item.text (3, sal, 20, 20,'style="text-align:right"','f03_' || '#ROWNUM#')
end as salary
from EMP;

untuk form biasa anda bisa pakai dynamic action.

Membuat Page Help untuk aplikasi

Page help digunakan untuk membuat sebuah keterangan dalam satu page keseluruhan yang merangkum semua keterangan bantuan semua region, item dalam satu bagian, jadi bedakan dengan item help yang mem-pop-up setiap klik label item.
Adapun langkah-langkahnya sebagai berikut:

1. Buatlah text help untuk semua item dalam aplikasi
• Home >> Application Builder >> Application XXX>>Item Utilities >>Edit Item Help Text
• Isi semua item help yang tidak memiliki help dengan klik: Seed Item Help Text
• Contoh: "Belum memiliki Help Text"
2. Buatlah page help untuk menampung informasi help
• Buat page baru (blank) dengan alias: HELP
• Tambahkan region :HELP dengan tipe : PL/SQL Anonymous Block
• Isi region source:

APEX_APPLICATION.HELP(
p_flow_id => :APP_ID,
p_flow_step_id => :REQUEST,
p_before_region_html => '<p><br/><table bgcolor="#A3BED8"
width="100%"><tr><td><b>',
p_after_prompt_html => '</b></p>&nbsp;&nbsp;');

3. Buatlah navigation bar entries
• Home >> Application Builder >> Application XXX>>Shared Components >>Navigation Bar Entries >> Create
• Entry Label: "Help"
• Target Type:URL dan isi URL Target

javascript:popupURL('f?p=&APP_ID.:HELP:&SESSION.:&APP_PAGE_ID.');

sumber : Oracle® Application Express API Reference
catatan :

• Buatlah pakailah template page popup (atau buat baru sesuai kebutuhan) supaya logo,nama user dan nav bar tidak tampak di page help.
• Anda bisa memakai icon dalam nav bar namun harus ada penyesuaian dalam template page.
• Anda bisa memanggil page help dengan tampilan pop-up atau jQuery modal.
• Anda bisa mempelajari lebih lanjut procedure APEX_APPLICATION.HELP disini.