AppWorks Mobile App Development

A step by step guide in building great apps on top of the AppWorks platform.

Overview

What is an AppWorks app?

The Basics

An AppWorks app is a zipped bundle of files – HTML, CSS, JavaScript, images, and anything else you need – that adds functionality to the native AppWorks iOS, Android, or Blackberry mobile client. An app within an app essentially, it is a single page web application, and can use all the API's that the browser provides.

In addition to the browser API, these apps also have access to a powerful API exposed by appworks.js, which provides varying levels of on-device technology access, authentication, and exposure to back-end services.

App developers build applications for their enterprise once, and deploy to any device or platform in a snap using the AppWorks Gateway.

App developers have a number of tools at their disposal to aide them in building apps. The appworks-cli was built to address packaging, emulation, and templating concerns and provides an easy way to bootstrap an AppWorks app.

More on each of these in subsequent sections.

High level application architecture

Structure

An AppWorks app has a nested zip structure that must be implemented in the following way:

Where AppName is the name of your AppWorks app and versionNumber is the version number of the app, specified in x.x.x format. For example, for the 1.0.2 release of an app named Document Scanner, the zip file would be named DocumentScanner_1.0.2.zip. Note that no spaces are allowed in the name of the zip file. Additionally, the underscore delimiter is required to separate the app name from the version number. If there is no underscore to separate the two entities, the deployment will fail.

Inside of the first level zip file we have three files: app.properties, icon.png, and mobile.zip. Each one of these files is necessary in providing correct rendering information to the native client.

app.properties is a key-value properties file that includes the following:

displayName the name of the app. May include spaces. This is how it will render on the gateway and inside the client.

description a brief description of the app. Should not exceed 140 characters.

version the version number of the app. This is the number the gateway will use to determine how to deliver updates to users.

awgPlatformVersion the version of the gateway the app is designed for. For example for Suite 16, this value should be 16.

type: the type of the content being uploaded to the gateway. Since the gateway can also deploy services and containers, this is necessary to determine how the uploaded content will be processed. For apps this value should be “app”.

mobile.zip is where the app content is stored. This may contain arbitrary data and may be structured in any way the app developer pleases. The only requirement is that of an entry point into the application itself, index.html.

Structure – The Web Application

The entry point to the web app must be named index.html, and moreover, should provide the relevant script, style and meta tags to render the web page properly on small screens.

In particular, apps should contain a meta tag related to viewport sizing that instructs the browser how to calculate the width and height of the screen, e.g.

<meta name="viewport" content="width=device-width, initial-scale=1">

More information on mobile specific meta tags can be found here. Options are available for maximum-scale, minimum-scale, zooming, and more.

Furthermore, to have access to on-device API's via appworks.js, two <script> tags must be included to tell the mobile browser to load the relevant scripts. These are cordova.js, and appworks.js. There is no need to include these files within your project, they will be injected automatically as part of the installation process. This ensures that you always have a stable version of the library included you're your project and takes the hassle of dependency management out of your hands. However, you may include the files and provide the path to them yourself. Both files are freely available through outlets such as GitHub or Bower. An example index.html with relevant <meta> and <script> tags can be found below.

Aside from these requirements, the rest of your web app may be structured in any way you wish. We highly recommend that app developers design their apps as Single Page Applications. Apps designed using this pattern typically achieve the best results and provide the best experience for their users on the AppWorks platform. There are several tools and frameworks available for building great SPA's – our number one recommendation is Ionic, and several apps we have built internally are built using the technology provided by this framework.

How should I develop my app? Is there an AppWorks IDE?

It is important to remember that an AppWorks app is regular web application. It uses common web technologies such as HTML, CSS and JavaScript and may be tested in any environment where these technologies may be rendered (e.g. a browser).

There is no AppWorks specific IDE, in fact any text editing software may be used to generate the source files, from Sublime Text to Eclipse. Our IDE of choice when building web applications is WebStorm, as we feel that it provides the best development experience and produces the highest quality output when building these kinds of applications.

For simulation, we recommend using the Google Chrome browser and its responsive design utilities to build out your app. One important fact to consider is that on iOS the browser that will render your web page is Safari, and on Android that is Chrome. It is good practice (but not necessary) to test your app against both browsers. Additionally, it is good practice to test your app against varying screen widths to ensure that it is rendered properly from device to device.

By far the easiest way to get started is to use the AppWorks CLI to bootstrap an app from a starter template we have built. This template is a simple starting point and an excellent reference in utilizing appworks.js and browser API's to build effective applications.

Note: Testing on the browser is a great way to get started with the rendering and layout of your app. For apps that require appworks.js API calls, the current method of testing is to stub out these calls manually, or by deploying the current state of the app to the native iOS, Android, or Blackberry container. We are continually introducing more tools around testing and development, particularly around the appworks.js API. You may ensure you get the latest tools by following our progress on GitHub: https://github.com/opentext/appworks-js

appworks.js is a small JavaScript library that provides an API into several powerful features, most notably, features that access on-device technology such as the camera or GPS. This library is auto injected into any app that is deployed using the AppWorks native client for iOS, Android, or Blackberry. Including the library provides the following features:

How does it work?

The library works by exposing a JavaScript layer that communicates with the native iOS, Android, or Blackberry OS through a communications protocol, typically marshaled through Cordova.

Under the hood, each part of the API is implemented through a Plugin, and these plugins access some functionality of the underlying mobile OS. These plugins are built using the Cordova plugin specification. The figure below shows a high level diagram of how these plugins operate.

appworks.js hooks into these plugins natively, and provides the functionality of the API through callback functions implemented in JavaScript. This means that your web application can use appworks.js objects to make native API calls, passing regular JavaScript functions as callbacks, and get regular JavaScript objects back when the execution is finished. You don't need to worry about the implementation details of a Plugin, and do not need to deal with low-level native code. You simply use JavaScript functions to get your desired output.

Where do I get it?

To download appworks.js you don't need to do anything at all. The library will be auto injected into any application deployed using the AppWorks native client for iOS, Android, or Blackberry. (Automatic installation). This means that we physically copy our own builds of the relevant appworks.js files into the root of your web app during the deployment process.

However, if you would like to download the library and install it yourself, you may do so in one of three ways (Manual installation):

Be sure to include a <script> tag in your web applications index.html file that references the location of appworks.js.

For Automatic installation:

<script type="text/JavaScript" src="appworks.js"></script>

For Manual installation:

<script type="text/JavaScript" src="<path-to-appworks.js>"></script>

Note: You may find all of the documentation, examples and more on the GitHub page. If you are interested in staying up to date on future releases of the library, create a GitHub account and star the library.

What is the AppWorks command line interface (CLI)?

The AppWorks CLI is a command line tool that allows app developers to quickly bootstrap new applications from existing templates. In addition to bootstrapping, the CLI provides packaging options that allow developers to package their apps for installation after development and testing cycles.

The command line tool is available on GitHub here and NPM here. Documentation is readily available to help developers get started right away.

Note:This tool requires node.js to be installed on the development machine.

Command Line Tools

There are several tools that are made available through the CLI. These are currently start and package, with plans to continuously add new features and functionality. By running one of these commands from the terminal or command prompt, one can bootstrap an application or package an app for deployment.

See the Getting Started section below for details on installing the CLI. It may alternatively be downloaded GitHub:

Each command takes in 0-4 arguments delimited by -- (two dashes), followed by the argument, e.g. --template.

Start

The start command provides a way to download an existing application to your development machine. It takes 1-4 options.

name the name of the app. Required

version the version to set the app. Defaults to 0.0.0

description the description to write for the app. Defaults to An AppWorks App

Note: value must be in quotes when typing command

template a URL to a valid git repository. It will try to clone this repository into a directory with the same name as the name argument provided. Defaults to https://github.com/opentext/appworks-app-starter

Package

The package command allows you to package your app in accordance with the specification laid out in the beginning of this document. Of course, you may package up your app manually, but doing so may require more effort, especially when packaging apps frequently. Instead, you may use this command line option to package in one fell swoop.

In order to use this option however, your app's structure must adhere to a particular format. That is, all of your web application content must live inside a single directory. By default, the CLI will look inside a folder named www when bundling your applications content. You can also specify where your application's content resides by passing the --from flag. If it cannot find this directory, the packager will fail. In addition, you can specify where you would like the resulting package to be stored through the --to flag. By default, the CLI will create a directory named package and store the resulting app bundle there.

from the directory where your final application assets reside. Defaults to www

to the directory to store the output of the package command. Defaults to package

The packager requires all application content to live inside of a single directory, by default it looks inside of a directory named www

Build

The appworks-cli has deprecated its build command. We feel that this is an application level concern. Whether you are using Ionic, Angular, React, Vue, or your own custom framework, the build process is specific to your application. Therefore, we leave building to you, and ask that you utilize the package command to bundle your app when it is ready to be deployed.

Emulate

The appworks-cli has deprecated its emulate command. This is a platform level concern and depends on the operating system you are running as well as the mobile platform you are attempting to emulate. We recommend emulating your application in the browser for hybrid (HTML + JS) apps.

Help

Running the --help or -h flag will bring up the help menu.

Getting Started: Building an AppWorks App

In this section we will guide you through the process of building an AppWorks application. We will use the command line interface to bootstrap, modify the bootstrapped application by adding a “hello world” heading to the main page, then we will package up the app for deployment, again using the command line tools.

Prerequisites

In order to use the command line tools, you will need, at the minimum, git and node.js to be installed on your machine. You can install them from the as follows:

To install node.js, visit the following link and follow the instructions to install version 8.x or later. It is important to ensure you have at least this version or you may run into trouble using the command line tools:

Once you have the prerequisites installed, you may install the AppWorks command line tools by issuing the following command:

npm install -g appworks

You should now have the command line tools installed on your system. You may verify by issuing the following:

appworks -h

Bootstrap

Now that the command line tools are installed, lets use them to clone an app locally onto our machine. Open up your terminal/command prompt, navigate to a directory you wish to download your app to and run the following:

appworks start --name DevGuideBootstrap

This will download our starter template from our github repository. Now enter the directory you have just created:

cd DevGuideBootstrap

Modifying the Code

Now you can use your favorite text editor to start modifying the app. Open up tabs-file.html, located inside of the www/templates directory and enter in the following, just under the <ion-content> directive (line 3):

<h1>Hello World</h1>

Testing

Now you may want to see your changes. Run the following command to launch the app in a browser. Note, this is an ionic v1 app, so we will need to install the Ionic CLI on our system to serve the app automatically.

npm install -g ionic

```
ionic serve

This will run a small webserver to serve the app and automatically launch your browser with a tab open at the address serving your page. The page is automatically refreshed when it detects that there has been a change in any of your code.

You may use your browsers responsive design utilities to simulate how the device will look on a small screen. Once you like what you see, you are ready to package and deploy.

Packaging

Make sure you are in the root of your project directory, in our case that is DevGuideBootstrap, and run the following:

appworks package

This will package up your app in a manner ready for deployment. It will scan the contents of the www folder to figure out what to include, and will read data from your app.properties file to decide how to name the bundle. If you have modified those files in any way, please ensure that the command line tool can read the appropriate values. Additionally, ensure that all of the content you want bundled is inside of the www directory.

This command should have placed a new file in a directory named package. You may now take that zip file and upload it to your gateway. Once you have enabled that app from your AppWorks Gateway Admin console, your users are free to install that app using the AppWorks client.

Troubleshooting

Some have reported errors with compiling node-sass on their system. If this occurs, try verifying your version of node and binaries of node-sass are in sync and run npm rebuild node-sass if necessary.

About OpenText

OpenText™ (NASDAQ: OTEX, TSX: OTC) is a global leader in Enterprise Information Management (EIM). OpenText is enabling the digital world by creating a better way for organizations to work with information and achieve-actionable results.

OpenText is driving the digital transformation our customers need to better manage information, better integrate their business networks and make better business decisions with analytics. The OpenText EIM strategy enables organizations to discover and manage information to spur growth and innovation, and decrease time to competitive advantage. OpenText is enabling the digital world for more than 100,000 customers, with the OpenText Cloud processes over 18 billion transactions per year for more than 64,000 customers around the world. OpenText solutions consist of four on-premises suites representing the next generation of innovation in Enterprise Content Management (ECM), Business Process Management (BPM), Customer Experience Management (CEM) and Analytics.

OpenText's next generation of Enterprise Information Management (EIM) solutions address key business goals that drive digital transformation, and are designed for deployment in the cloud, on-premises and in hybrid (cloud and on-premises) environments.