In this blog post, we are going to explore how a 3rd party library can be added to Oracle APEX. In particular – we are going to look at how to integrate Google Material components to Oracle APEX. I’m going to assume you have an intermediate knowledge of APEX but I’m not going to assume you have any exposure to Google’s Material.
Let’s begin with an overview of Material. Google’s Material is an open-source project/design philosophy that offers a stunning open-source selection of components and features. Head to https://material.io to check it out.
Integrating Google Material components into Oracle APEX can describe a broad spectrum of workflows – today we’re going to pick a relatively simple workflow in which we simply copy and paste from Material into our APEX application.
As APEX developers, we are interested in “Web” components, so head to https://material.io/develop/web/ and explore the components menu in the left hand nav. Take your time to admire the components on offer. There’s a lot to study here.
A few component feature comparisons between Material and APEX’s Universal Theme
All of the Material designs were built on the concept of “quantum paper” – Google dreamed up a universe in which your computer screen peers into a paper theatre stage – on which highly responsive paper moves and transforms across your screen in magical but fundamentally consistent and intuitive ways. Here are a few thoughts I have about how Material compares to Universal Theme from a component feature perspective (so I’m not going to mention layout, movement, color, or versatility).
|Material Card Component||vs.||APEX Card Component|
|Shadow coming in at 45 degree angle communicates clearly that the card represents a piece of paper elevated from the background.||What could be described as “shadow” uniformly frames the card in a less obvious metaphor.|
|Material Elevation||vs.||APEX Elevation|
|Material allows you to configure the elevation of your components to communicate clear relationships in your screen’s z-space.||APEX provides an illusion of elevation for many of its components but the shadow is not as convincing because it is so uniform.|
|Material Floating Action Button (FAB)||vs.||APEX Primary Hot Button|
|Material offers a Call-to-Action button that is both elegant in design. “Only one floating action button is recommended per screen to represent the most common action.”||APEX suggests you use the “Hot” and “Primary” options to identify your Call-to-Action button|
|Material Table||vs.||APEX Table|
|The tabular representation of data is not Material’s strong suit.||APEX’s rich library of table options is without compare.|
Back to the tutorial
I propose we make use of the Material Card component in our tutorial because it has no clear substitute on the APEX side. If you want a card layout similar to this in APEX – you’re going to have to write some HTML and CSS no matter how you go about it.
To see some easy and interactive demos of these components, find the Github link at the bottom of the page – then – click into the material-components-web repository and find the “Demos” link. You’ll be taken to the https://material-components.github.io/material-components-web-catalog/#/ where many of the components have demo pages, each of which are worth careful study.
These Demo pages show off how different combinations of HTML elements and classes can produce very different results. Click into the “Card” example and toggle the “options” drop-down to get a sense of this:
The example HTML is helpfully seeded with some provisional classes that you can use to target with your own CSS – this “demo-card” class for example. We will have to write our own CSS for these classes (as we will see later):
Prepare your APEX application for material components
Let’s switch gears and prepare an APEX application to accept the material component HTML. For the benefit of those who want to follow along at home, I’m installing the Sample Database application from the Sample App Gallery. I can recommend getting a free workspace at apex.oracle.com for this purpose.
Once it’s installed, let’s navigate to the products page – I chose this sample app because it features images. We can combine these images with the Material component card to create something that looks more like a blog or a commercial website.
Start by copying this page to a new page. On my new page, I’m going to switch the interactive report to a classic report so that I can make use of the existing “card” theme architecture.
I’ll rename my field names in the SQL in anticipation of feeding them into my card template, as below:
That done, let’s take a look at the existing card layout in the runtime environment:
Add Material Dependencies
Ok, with that, let’s go ahead and begin adding Material dependencies to our App. 1st – we need to add the necessary CSS and JS file references. Material offers many ways to do this but the simplest is simply to reference their CDN. To find this – we navigate back to material.io, go to Develop then Web and click “getting started”.
Capture the 2 CSS files:
Capture the 1 JS file:
Now let’s head to our Templates, under Shared Components. I find the “card” template that I’m currently using and copy it to a new custom template:
Let’s capture the HTML from the demo website we saw earlier: https://material-components.github.io/material-components-web-catalog/#/component/card. We must modify the HTML to include
- the <li> elements at the beginning and end, per the architecture of the native APEX card element
- the substitution strings that we prepared in our SQL earlier
After saving that, return to the page designer where we have the APEX Classic Report with the Cards Theme. Let’s switch the template to our newly created custom theme “Material Cards”:
If you run the page at this point, it won’t look quite right because it’s missing the custom CSS that we have to write:
Next, let’s write a little CSS. I think we can get some attractive results with just the basics (advice: don’t attach CSS to non-custom classes):
With the addition of this custom CSS, we now have something that I think looks acceptable:
Congrats! This completes our tutorial on how to integrate Material Components with Oracle APEX.
For those of you who like watching videos, I assembled the following youtube tutorial, which comes in at a succinct 7.5min.
This post follows the Insum Insider Webinar Series Adding 3rd party design libraries to APEX – Google’s Material Design (May 14th, 2020). This webinar serves as a follow-up to my previous blog post APEX should be beautiful in which I talk about the opportunity presented by integrating with 3rd party design libraries.