Create a custom offline page for your APEX PWA in 21.2

With the new version (21.2) of APEX, came the built-in PWA support for your APEX applications. PWA stands for Progressive Web App and is a concept that allows your Web Application (an APEX app) to look like a Native App (an iOS or Android app). This includes local resources caching (like Javascript and CSS files), ability to install the app on any device, can be configured to push notifications and you can use it offline. One of the biggest benefits is that PWA needs a single codebase, so you only develop your app once and it’s ready for all devices, and a downside is that you don’t have full access to all of the device’s hardware, something that a Native App has.

For more info about PWA is and the benefits of having it, visit some of the following links:

https://web.dev/what-are-pwas/
https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps/Introduction


This blog post is focused on one of the PWA features, that are now natively supported in APEX – the Offline page. Once your application is converted (or created) as PWA, you already have a default Offline page, that will be shown to the users when they don’t have access to the internet.

Turn an APEX app into a PWA

To see how you can create a PWA APEX application or turn an existing one into a PWA in 21.2, watch the video below. Vincent Morneau explains it as part of the new Oracle APEX series that showcase the 21.2 new features.

The steps to turn an existing application into a PWA in short are:

  • While being in the App Builder, inside your app, select Edit Application Definition
  • Go to Progressive Web App tab
  • Turn on the Enable Progressive Web App option
  • Optionally make your PWA installable using the Installable option

See the Offline Page in action

Now you have an Offline page, out of the box, with a cool SVG graphics on it. To see it in action, either turn of your wi-fi or use the Browser Dev Tools to simulate an internet outage.

In Chrome, go to the Application tab, select Service Workers from the menu to the left, then check the Offline checkbox. Then refresh your page. The default Offline Page should appear.

Notice that the text is automatically translated, depending on your Language Preferences. In the next section you will see how that can be controlled.

The Offline Page explained

Before starting to modify your Offline Page, read this Oracle APEX Documentation:
Progressive Web App (PWA) Messages Requiring Translation

You will find a number of Message Names, starting with APEX.PWA.
Those are the messages that you get in various occasions, when Offline Page display is involved. It includes the Page Body (APEX.PWA.OFFLINE.BODY) and Page Title (APEX.PWA.OFFLINE.TITLE), but also the error messages displayed, when you are using a device that is not supported for PWAs.

What you see on the pictures above is controlled by the APEX.PWA.OFFLINE.BODY message. As seen in the documentation, you can use HTML to design your page. Another very important part of the example is the use of SVG to produce any images on the page. That’s because an SVG can be rendered directly by the browser, it is lightweight and doesn’t require access to any resources on the server, such as raster images (JPG,PNG, etc.).

To change your Offline Page, follow the steps below:

1. Go to Shared Components
2. Under Globalization, select Text Messages
3. Click on Create Text Message button
4. Enter APEX.PWA.OFFLINE.BODY as Name
5. Select the Language you’d like this message/page be associated with
6. Repeat steps 3-5 for all Languages you support in your application
7. Enter the HTML/text/SVG that will be rendered on the Offline page in the Text field

Note that APEX will use the default translation (and SVG image) for the Offline Page (like in the pictures above) if you have not specified additional translation.

What is SVG and why we need it

So what is SVG?

As the name suggests, it is a Scalable (because it can be scaled without loss of quality) Vector (because it is defined by a number of vectors) Graphics (well, it’s a graphic after all). SVG is a XML-based markup language, so it can also be validated, indexed, embedded in HTML documents, edited with text editor (or with more advanced editors that will follow below). It also takes very little space, compared to the bitmap formats.

All those features of SVG make it ideal for use in the PWA and not only. Here is an example of the default Offline Page:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 280" role="presentation">
      <g fill="none">
        <path d="M316.846 213.183c39.532 0 63.154-30.455 63.154-62.764 0-30.943-22.158-56.615-51.441-62.179v-1.17c0-48.123-38.947-87.07-87.07-87.07-39.044 0-72.036 25.672-83.066 61.007-8.492-3.612-17.863-5.564-27.722-5.564-34.261 0-62.764 24.11-69.694 56.322a51.007 51.007 0 0 0-9.468-.879C23.036 110.79 0 133.825 0 162.327c0 28.405 23.036 51.441 51.441 51.441l265.405-.585z" fill="currentColor" opacity=".2"></path>
        <circle fill="#D63B25" cx="336" cy="216" r="64"></circle>
        <path d="M367.357 198.439c-.395-.395-.947-.632-1.657-.632-.71 0-1.184.237-1.657.632L351.97 210.51l-10.494-10.493 12.072-12.072c.395-.395.71-.947.71-1.657A2.29 2.29 0 0 0 351.97 184c-.631 0-1.183.237-1.657.631l-12.071 12.072-7.496-7.496c-.394-.394-.947-.71-1.657-.71a2.29 2.29 0 0 0-2.288 2.288c0 .632.237 1.184.71 1.657l2.604 2.604-13.176 13.176a13.781 13.781 0 0 0-4.024 9.705c0 3.787 1.499 7.18 4.024 9.705l2.13 2.13-14.36 14.36c-.394.394-.71.947-.71 1.657a2.29 2.29 0 0 0 2.288 2.288c.631 0 1.184-.237 1.657-.71l14.36-14.36 1.736 1.736a13.781 13.781 0 0 0 9.704 4.024c3.787 0 7.18-1.5 9.705-4.024l13.176-13.177 2.92 2.92c.394.394.946.71 1.656.71a2.29 2.29 0 0 0 2.289-2.288c0-.632-.237-1.184-.71-1.657l-7.575-7.496 12.072-12.071c.394-.395.71-.947.71-1.657.079-.632-.237-1.184-.631-1.578zm-27.142 33.059a9.398 9.398 0 0 1-6.47 2.603c-2.525 0-4.813-.946-6.47-2.603l-7.1-7.101a9.124 9.124 0 0 1-2.683-6.47 9.124 9.124 0 0 1 2.682-6.47l13.177-13.176 3.156 3.156c.079.079.079.158.158.158l.157.157 13.413 13.413c.08.08.08.158.158.158l.158.158 2.761 2.762-13.097 13.255z" fill="#FFF"></path>
      </g>
</svg>

To read more about the SVG format, you can visit the following link:
https://developer.mozilla.org/en-US/docs/Web/SVG

To see some more examples and tutorials, these are some great resources:
https://css-tricks.com/using-svg/
https://css-tricks.com/lodge/svg/
https://developer.mozilla.org/en-US/docs/Web/SVG/Tutorial

SVG Editors

Starting from Notepad, all the way to the heavy artillery – Adobe Illustrator. If you know what you are doing and the image you try to produce is not so complex, a simple text editor is more than enough. If you need however a graphic with lots of details, you’d better use an editor.

Here is a list of the ones I’ve been using, as number one in the list is the one I like most (by the way also coming as a PWA application):

  1. Figma – free of charge, can be installed locally, has an enormous community and plugins, easy to use. It is also great for wire framing and prototyping. My personal best. I have it installed as a PWA on my machine.
  2. Inkscape – also one of the best free tools. A little more complex, but for a day or two of working, you get used to it.
  3. Boxy SVG – the first tool I tried. It’s perfect to get started. Very intuitive, easy to work with and still having everything you need to produce some great results. It is a paid product, you can have it for $10 per year for the Standard version or $100 for the Premium. It has a trial however, so it’s worth trying it.
  4. Adobe Illustrator – as I said – the heavy artillery. Used by the best designers in the world for a reason. I has all you need, plus a lot more that you would probably never use, unless being a hardcore graphics designer, create animations, etc. Paid product of course – $20 per month . If you need it – good for you, it means you have reached next level.

Creating a new Offline Page with custom SVG

Here is an SVG that I’d like to have on my Offline Page, together with some text.

<main>
    <?xml version="1.0" encoding="iso-8859-1"?>
	<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" viewBox="0 0 512 512" 
		 style="enable-background:new 0 0 512 512;" xml:space="preserve">
		<path style="fill:#FF9F19;" d="M445.215,478.835H66.848c-23.67,0-45.079-12.118-57.25-32.418
			c-12.182-20.3-12.802-44.883-1.663-65.781L198.889,65.387c12.182-20.17,33.548-32.222,57.142-32.222s44.959,12.052,57.152,32.245
			l190.499,314.433c11.585,21.692,10.966,46.274-1.217,66.575C490.294,466.717,468.885,478.835,445.215,478.835z"/>
		<path style="fill:#F28618;" d="M445.215,478.835c23.67,0,45.079-12.118,57.25-32.418c12.182-20.3,12.802-44.883,1.217-66.575
			L313.184,65.409c-12.193-20.193-33.559-32.245-57.152-32.245v445.67H445.215z"/>
		<path style="fill:#486475;" d="M256.031,345.294c-9.215,0-16.693-7.477-16.693-16.693V161.675c0-9.215,7.477-16.693,16.693-16.693
			s16.693,7.477,16.693,16.693v166.926C272.724,337.817,265.247,345.294,256.031,345.294z"/>
		<path style="fill:#3C4D5C;" d="M256.031,412.061c-9.21,0-16.693-7.498-16.693-16.693s7.483-16.693,16.693-16.693
			c9.21,0,16.693,7.498,16.693,16.693S265.241,412.061,256.031,412.061z"/>
	</svg>
    <h1>Oh no, you ran out of internet</h1>
    <p>Please get some and try again</p>
    <button type="button">Retry</button>
</main>

<script>
    document.querySelector("button").addEventListener("click", () => {
        window.location.reload();
    });
</script>

The end result now looks like this, and you can compare it to the default one below.

Now the only thing left is to take your HTML and follow steps 1-7
from the “The Offline Page explained” section.

Note that the Text field supports only 4,000 characters, so be careful when you design your HTML/SVG (especially any complex graphics).


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s