Triggered Actions on Buttons & New Metric Card
Triggered Actions on Buttons & New Metric Card
Oracle APEX 26.1 introduced something that quietly changes how I now build dashboards. Two features dropped in the same release that work beautifully together: Declarative Dynamic Action Support for Actions, Buttons, Cards, and Menus, and a brand new template component called Metric Card.
What This Used to Take
Before 26.1, attaching click behavior to per-row elements (a button inside a card, an action on a template component, a menu item) usually meant one of two awkward options. Either you wrote JavaScript that read DOM data attributes and manually called apex.server.process(), or you built a Dynamic Action elsewhere in the page tree with a custom event hook. The connection between what was clicked and what happens lived in two different places.
The result of that gap was a lot of code that worked but was hard to read, harder to debug, and almost impossible to hand off cleanly. APEX 26.1 closes that gap for the components that need it most.
Declarative Dynamic Action Support Explained
The idea is simple once you see it. In APEX 26.1, you can attach Dynamic Actions directly under specific components in the Page Designer tree, instead of going to the Dynamic Actions tab and wiring things up separately. Right click the component, choose Create Triggered Action, and the entire click behavior lives right there beside the component that triggers it.
Each clicked component automatically knows which row it belongs to. You expose columns to the client by toggling a single attribute, and those values are then available throughout the action chain.
Available on Client
Toggle this on each column you want to use during the triggered action. The column value travels into both JavaScript via $v('COLUMN_NAME') and into messages via &COLUMN_NAME.
Value Protected
For sensitive columns such as primary keys, enable Value Protected. APEX signs the value, so the server can detect any tampering done via DevTools before it accepts the request.
Items to Submit (Columns)
A new field on the Execute Server-side Code action lets you select column values directly. Those column values then become available as bind variables in your PL/SQL.
The Action Chain
Each Triggered Action node holds a sequence of True Actions. The common pattern is Confirm, Execute Server-side Code, Refresh, Show Success Message. All four are now native declarative actions, no JavaScript needed.
Building the Cards Region (Per Employee)
The first thing I wanted to confirm was that this all works end to end on a regular Cards region. So I built a page showing each employee as a card, with a button labeled Give 10% Raise. Clicking it should confirm, raise that employee's salary, refresh, and show a toast.
Cards Region Setup
Create a Cards page on the EMP table. Map ENAME to Title, JOB to Subtitle, SAL to Body. This part is standard, no new feature involved yet.
Expose Columns to the Client
Click each column in the Rendering tree and enable Available on Client for ENAME, EMPNO, and SAL. Enable Value Protected on EMPNO as well, since we will use it in the WHERE clause of the UPDATE.
Add the Card Action Button
Right click the Cards region Actions node, choose Create Action, set Type to Button, Label to Give 10% Raise, and Action to Defined by Dynamic Action. A new Triggered Actions node appears under the action.
The PL/SQL for the Raise
Use a bind variable matched to your Items to Submit column. APEX picks up the clicked row's EMPNO and passes it through.
UPDATE emp SET sal = ROUND(sal * 1.10, 2) WHERE empno = :EMPNO; COMMIT;
The Triggered Action Chain
Four True Actions, top to bottom, all declarative.
| Order | True Action | What It Does |
|---|---|---|
| 1 | Confirm | Pops up Give &ENAME. a 10% raise? |
| 2 | Execute Server-side Code | Runs the UPDATE statement using :EMPNO |
| 3 | Refresh | Refreshes the Cards region so the new salary shows |
| 4 | Show Success Message | Displays &ENAME.'s salary increased by 10%. |
&COLUMN. with an ampersand and a period at the end. This is different from older syntax like #COLUMN# used in classic reports. Worth remembering when writing Confirm text or Show Success Message text.
The New Metric Card Template Component
The second 26.1 feature I tested is the Metric Card. It is a brand new template component shipped with the release, designed specifically for KPI dashboards. Before 26.1, building a metric tile meant either hand writing HTML or repurposing a regular Cards region with custom templates. The Metric Card is now a proper first class component.
It exposes three primary slots:
The Title is a small label at the top of the card. The Metric is the big headline number, intended for the value you want users to focus on. The Meta is supporting text below, where you put context like counts and averages. Plus optional CSS Classes for each piece and a Layout dropdown that lets you rearrange the slots.
Building a Department Metrics Dashboard
The goal here is one Metric Card per department from the EMP table, showing total payroll, headcount, and average salary. The query aggregates by department.
Region Source SQL
Standard aggregate query, nothing fancy. One row per department.
SELECT deptno, COUNT(*) AS emp_count, SUM(salary) AS total_sal, ROUND(AVG(salary), 2) AS avg_sal FROM emp GROUP BY deptno ORDER BY deptno
Metric Card Configuration
Inside the Metric Card region, under Attributes Settings, configure each field as below.
| Field | Value |
|---|---|
| Title | Department &DEPTNO. |
| Title CSS Classes | Leave blank |
| Metric | $&TOTAL_SAL. |
| Metric CSS Classes | Leave blank |
| Meta | &EMP_COUNT. employees · Avg $&AVG_SAL. |
| Layout | Default |
Save and run, and you get one tile per department. Each tile shows the department name as a small label, the total salary as the hero number, and the headcount with average as supporting text. Clean and dashboard ready.
Combining Both Features
This is where the two features start working together. The Metric Card supports Template Component Actions, and those actions are exactly the kind of component that picks up the new Triggered Actions tree from feature one. So I added an action labeled Give Dept 5% Raise on each department card. Clicking it raises every employee in that department.
Mark DEPTNO as Primary Key
For Triggered Actions to work on a multi-row Template Component, at least one column needs to be marked as Primary Key. Open the DEPTNO column and toggle Primary Key to On. Also enable Available on Client and Value Protected on the same column.
Create the Template Component Action
Right click the Departments Metric Card region and choose Create Action. Set Position to Link, Label to Give Dept 5% Raise, and Action to Defined by Dynamic Action. The Triggered Actions node appears below the new action.
The PL/SQL Update
Same bind variable pattern. DEPTNO travels in from the clicked card.
UPDATE emp SET salary = ROUND(salary * 1.05, 2) WHERE deptno = :DEPTNO; COMMIT;
The Triggered Action Chain
Four declarative steps, same pattern as the per employee example.
| Order | True Action | Configuration |
|---|---|---|
| 1 | Confirm | Give all &EMP_COUNT. employees in department &DEPTNO. a 5% raise? |
| 2 | Execute Server-side Code | The PL/SQL above, Items to Submit Columns set to DEPTNO |
| 3 | Refresh | Refresh the Departments region |
| 4 | Show Success Message | Department &DEPTNO. updated. All &EMP_COUNT. employees received a 5% raise. |
The moment you click the action on department 20 and the dialog reads Give all 5 employees in department 20 a 5% raise, the row context proves itself. The same chain works for every card. The same SQL with the right bind variable. Zero JavaScript.
Pro Tips: Things Worth Knowing Up Front
-
Triggered Actions need a Primary Key on multi-row regions. If you forget this on a Metric Card, the save will fail with a clear validation error. Mark the primary key column accordingly.
-
Always Value Protect your IDs. Treat the browser as untrusted. If a Card or Template Component sends a primary key to the server, Value Protected ensures the value cannot be modified through DevTools without being detected.
-
Show Success Message and Show Error Message are first class actions now. Both are new declarative actions in 26.1. There is no longer a reason to write an Execute JavaScript step just to display a toast.
-
Substitution syntax matters. Cards and Template Components use
&COLUMN.with an ampersand and trailing period. The older#COLUMN#syntax does not work here. -
Keep the Metric field clean. Just the value, no labels. Labels go in Title or Meta. This is the visual contract Metric Card was designed around.
-
Triggered Actions run top to bottom. Always Confirm first, then run your server code, then Refresh, then Show Success. If you flip the order, you will refresh the region before the data changes, and the success message will appear before the work is done.
Comments
Post a Comment