Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Current »

Content Freeze

As of July 25th, 2023, there is a content freeze on this page.

Introduction


Apache Cordova is a popular open-source tool that lets you build a mobile app from web technology. With Cordova, it's possible to generate apps for all of the popular mobile platforms. These apps are indistinguishable from native mobile apps, and can be distributed through stores such as Apple's App Store or Google's Play. This guide is intended to help you understand how to use the Profound UI framework in a Cordova project.

Prerequisites

The Apache Cordova method of creating a mobile app requires web programming skills. Here is a short summary of the knowledge you should have before you begin:

  • Knowledge of Apache Cordova (can be learned at https://cordova.apache.org/)
  • Understand how to write HTML, CSS and JavaScript code
  • Able to debug web applications using a web browser's developer tools
  • Knowledge of writing and testing Profound UI Rich Displays, including those designed for mobile environments


We are aware that not all Profound UI customers have these skills or the time to learn them! For that reason, we provide the Profound UI Mobile Client, which is a very easy way to deploy mobile apps created with Profound UI mobile. If you are new to mobile apps, we recommend that you start with the Profound UI Mobile Client, and only use Cordova if it is deemed necessary. Most Profound UI applications designed for mobile will work very nicely in the Profound UI Mobile client without a need for the developer to use Cordova.  However, there are a few circumstances where Cordova is necessary. In particular, with Cordova you can:

  • Embed your own JavaScript code into the app that is available when you are not connected to a network
  • Create an app with your own logo on it that can be deployed through the Apple App Store, Google Play, or similar stores
  • Provide support for platforms that Profound Logic does not support with the Profound UI Mobile client
  • Create an app that does not require the user to configure a host name
  • Add in and use additional Cordova plugins besides those provided with the Profound UI Mobile client


Customers who do not have the necessary prerequisite skills, but need one of the features that Profound UI Mobile client does not support may wish to consider hiring Profound Logic on a consulting basis to help create their app.  If this option interests you, please contact Profound Logic Sales.

Creating Your App

Step 1: Set Up and Learn Apache Cordova

Apache Cordova is actively maintained by a large group of individuals. As such, it is constantly changing, so it is not practical for Profound Logic to document its usage here.  Instead, we recommend that you visit https://cordova.apache.org/ and read their documentation about how to get started with creating your own web-based mobile app.  Once you understand the basics of creating a mobile app with Apache Cordova, come back to this site to learn how to use Profound UI Mobile in your Cordova project.  Here is a list of key things you'll probably want to learn from the Apache Cordova site:

  • Whether to use the command line interface (CLI) or GUI version of Cordova.  Profound Logic's developers prefer the CLI version, finding it simpler to use. But, either one will work fine with Profound UI.
  • How to Install Cordova
  • Create a skeleton ("Hello World") app
  • Test your app in a PC Browser
  • Test your app on a device
  • Make modifications to your app
  • Change the logo, splash screen, and other properties you wish to set in your app
  • Build an app that can be distributed and installed onto a device
  • Deploy your app through the Apple App Store, Google Play, or similar stores

All of this and much more should be learned from Cordova's website. Once you understand how to create a simple web app (such as a 'hello world' app in Cordova) then you can come back to this document, and learn how to add Profound UI to your project.

Step 2: Add Profound UI Mobile Objects to Your Project

You can embed your own documents into the app you create with Cordova. Objects stored inside the app are served directly from the device itself, and are available when the network is not accessible. This is useful when you want to write apps that can run without a network connection.  It is also a great way to make your app load faster, since the files don't have to be downloaded over the Internet which can sometimes be a slow link.  On the other hand, when you want to make changes to these files (such as when you install a new version of Profound UI and you need to update the Profound UI code) you would have to re-build the app and deploy it to all of the devices that were using it. This guide assumes that you want to load Profound's runtime JavaScript framework into the device since this eliminates about 850 kb of data that otherwise would have to be downloaded to the device over the network each time the app is run. To do that, follow these steps:

  • Navigate to the directory where Cordova put the web code for your app (such as the index.html file)
  • Create a profoundui subdirectory
  • Create a profoundui/images subdirectory
  • Copy the runtime.js file from the /www/YOUR-INSTANCE/profoundui/proddata/js directory on your IBM i to the profoundui directory
  • Copy the profoundui.css file from the /www/YOUR-INSTANCE/profoundui/proddata/css directory on your IBM i to the profoundui directory
  • Copy all icons from the /www/YOUR-INSTANCE/profoundui/proddata/css/images directory on your IBM i to the profoundui/images directory
  • Copy any other files (such as JavaScript, CSS, images, JSON displays, etc) that you'd like to include on the device
  • Copy any custom widgets (such as the sample Google Maps widget) that you wish to include on the device


You should now have all of the necessary objects needed for Profound UI's runtime environment copied into your Cordova project.

Step 3: Modify (or Create) the Index.html File


Cordova starts your application by loading the index.html file in your project. You should use this file to load the appropriate JavaScript and CSS files into memory and to run the code that executes your app. When you created the app skeleton in Step 1, it included an index.html file that you can modify. Alternatively, you can replace the Cordova generated file with one that you create yourself, depending on what works best for you. You should add the following to the index.html file to make it work with Profound UI.

  • Add <link> and <script> HTML tags to load the Profound UI runtime environment:
    <link rel="stylesheet" type="text/css" href="profoundui/profoundui.css" />
    <script type="text/javascript" src="profoundui/runtime.js"></script>


  • Add additional <link> or <script> tags for any additional CSS or JavaScript files you copied into your project.


  • We recommend creating a separate JavaScript file for your application.  For example, you might call it app.js and therefore add a tag like this:
    <script type="text/javascript" src="app.js"></script>


  • Inside the <body> tag of your html document, you will need a <div> tag with an id of 'pui'. The tag should start out empty, but Profound UI will use it to render the application screens.

        <div id="pui">
    </div>
  • Click here to download an index.html file that was tested with Cordova. This file only loads the minimal Profound UI runtime and does not include other custom CSS or JavaScript files. Since it is possible that newer Cordova versions might require changes to this file, it should be considered an example, only.


You should now have an index.html file that will load all of the needed objects to make Profound UI available in your mobile app.

Note: If you wish to load these files from your server instead of placing them in the app that's served from the device, you can change the src or href attribute to contain a URL that points to the appropriate location on your IBM i server. For example, to load the runtime.js file from IBM i, change the src attribute to http://your-ibm-i:8080/profoundui/proddata/js/runtime.js.

Step 4: Create the JavaScript That Drives Your Application

In the last step, we recommended loading an app.js file that contains the JavaScript for your application.  You will need to write this script, and it should provide the code needed to control your application.  If your application is a program running on the IBM i server, this file will contain the information that Profound UI needs to connect to IBM i and run your application.  If you plan to do something more sophisticated such as create an offline application, this file should contain the JavaScript to display the screens and interact with the user. This code can also be used to do additional things on the device such as take pictures, scan barcodes, read GPS coordinates, or handle the Android back button, all depending on how your app should work.  A full explanation of everything you can do here is beyond the scope of this document. Instead, this document will provide an example of a minimal app.js file that simply connects to your IBM i.

Here's a simple app.js skeleton:

// (a) Configure Profound UI settings

pui["serverURL"] ="http://your-ibm-i:8080";
pui["language"] = "en_US";
pui["no focus"] = true;

// (b) Change the way the "loading" screen looks

pui["loading animation"]["text"] = "One moment...";
pui["loading animation"]["top"] = 5;
pui["loading animation"]["left"] = 5;


// (c) This code starts the Profound UI framework.

window.onload = function() {
  pui.run({ "mobile": true });
};


// (d) Set up a JavaScript function that runs when the device
//     has initialized, here:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
  // Put custom code here that runs after Cordova has loaded
  // device APIs are not available until this event has fired
}

The part of the code at (a) referenced above sets some Profound UI settings:
  • "serverURL" = the IBM i server that Profound UI will connect to. Use https instead of http if you want to use TLS/SSL to make a secure connection. Do not add anything after the port number, the path to the objects on IBM i will be automatically added by Profound UI.
  • "language" = the language used for messages displayed by Profound UI.  More information can be found under Language Support.
  • "no focus" = prevents focus from being automatically placed in the first input field on the display. This stops the touchscreen keyboard from popping up before the user clicks in a field.

The part of the code at (b) changes the text displayed when the screen loads (instead of the default spinning circle).  You can learn more by reading the Loading Animation documentation.

The part of the code at (c) starts Profound UI with the pui.run() API. Here are some different ways of starting Profound UI. See Startup API for details.
  • pui.run({ "mobile": true }) = start Profound UI using the program given in the Visual Designer under Configure Profound UI Mobile
  • pui.run({ "program": "LIB/PGM" }) = start an anonymous program. The program must be allowed to run as anonymous in the Visual Designer.
  • pui.signon() = present a sign-on screen and start the user's initial program.

The part of the code at (d) shows how to run an event when the device is ready.

After this event fires, it is possible to use hardware device features such as the camera, GPS, accelerometer, etc. There are other events available depending on the platform. See the Apache Cordova documentation for more information. The pui.show() API can be used to display screens from your JavaScript code. This is particularly useful if you want to show Rich Display screens without a network connection.

Click here to download an example of an app.js file that has been tested with Cordova. Since this is subject to change with different versions of Cordova, this should be only used as an example.

Step 5: Test/Debug Your Mobile App

Once your app.js script has been written, you are ready to run your Profound UI Mobile application, deployed with Apache Cordova. Refer to the Cordova documentation for information on how to test, debug, build and distribute your app.


  • No labels