Application Express Dynamic Actions with d3.js
This tutorial will show you how to get data dynamically into a d3.js graph in your Apex application. I did all my work on http://apex.oracle.com so if you want to mess around you can grab your own free account there and give it a shot.
If you want to get more familiar with d3.js Data Driven Documents visualization framework check out this article. Mike Bostock, the creator of d3js has a tutorial on bar charts available here. This tutorial is a great way to get a taste of basic and advanced d3 topics quickly. Part 2 of the tutorial is the basis for what I have shown here.
This document will focus more on the ApEx integration side of things rather than the d3.js knowledge transfer. There are already a lot of great tutorials out there on how to effectively work with d3.js. If you really want to get your mind blown and get excited about new visualizations for your ApEx apps, hit up the Examples Gallery with a supported browser (sorry no IE8) and check out the examples and their source code.
So here is an example of what I came up with in Apex by adapting the dynamic updating part of the tutorial... I want a bar graph that updates with a new value from a PL/SQL function every 2.5 seconds...
So here is how I went about creating this real-time updating graph in ApEx:
Step 1) Create a Dynamic Action
At this point we are going to create a very basic Dynamic Action to return a random number between 1 and 100 when we call it:
- Edit your page
- Add a Page Process
- Select "PL/SQL"
- Name your process GetRandom
- Select "On Demand - Run this process when requested by AJAX"
- Select Next
- Enter the PL/SQL you want to run On Demand and click Create Process
BEGIN HTP.PRINT( (1+ABS(MOD(dbms_random.random,100))) ); END;
We are just pushing out a random number between 1 and 100 to the requestor of our Dynamic Action. You are just running PL/SQL and returning text to the caller, so you have all of the wonderful and warty things that come along with PL/SQL. Future tutorials will get fancier with this and show how to push CSV or JSON output for d3 to digest, but for now we'll keep things simple and return 1 number at a time.
You can also create Application Level processes if you need to re-use the process across multiple pages.
Step 2) Make the d3.js Library Available to Your HTML Page
In your HTML Header of the page add the following code. This is just for testing purposes right now and Mike and GitHub graciously allows folks to link to their files directly. After the proof of concept stage I would suggest hosting the .js on your own site to ensure availability and version stability.... well it will be as available as the rest of your site at least :)
Add a HTML region to your page with the following code. Again thanks to Mike Bostock, creator of d3.js for the tutorial this code is based on. Check inline comments for explanations and highlights:
Step 4) Run it!
Execute your page. The chart will be populated with a few columns worth of data, then every 2.5 seconds after that the Dynamic Action will be invoked to get a new column on the right and to retire a column from the left of the graph.
But at this point you have your graph updating its data from a PL/SQL function that runs inside the database, a new technique to use for supplying dynamic information on your ApEx pages.