A step by step guide in building great apps on top of the AppWorks platform.
A step by step guide in building great apps on top of the AppWorks platform.
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
An AppWorks app has a nested zip structure that must be implemented in the following way:
<AppName>_<versionNumber>.zip ??? app.properties ??? icon.png ??? mobile.zip
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:
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,
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
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
<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.
If you decide to use Ionic, take a look at this article to avoid common pitfalls and get the most performance out of your application: https://www.toptal.com/ionic/most-common-ionic-development-mistakes
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.
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
index.html file with relevant
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.
Deeper look at plugin architecture. Some imagery borrowed from https://cordova.apache.org/docs/en/6.x/guide/overview/
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):
bower install --save appworks-js
Be sure to include a
<script> tag in your web applications
index.html file that references the location of appworks.js.
For Automatic installation:
For Manual installation:
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.
Screenshot from the appworks.js repo on GitHub.
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.
This tool requires
node.jsto be installed on the development machine.
There are several tools that are made available through the CLI. These are currently
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.
start command provides a way to download an existing application to your development machine. It takes 1-4 options.
namethe name of the app. Required
versionthe version to set the app. Defaults to 0.0.0
descriptionthe description to write for the app. Defaults to
An AppWorks App
templatea URL to a valid git repository. It will try to clone this repository into a directory with the same name as the
nameargument provided. Defaults to
For example, to clone an app and name it “MyNewApp”:
appworks start --name MyNewApp --description "My first foray into appworks" --template https://github.com/h5bp/html5-boilerplate.git --version 1.0.0
appworks-cli example usage
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.
fromthe directory where your final application assets reside. Defaults to
tothe directory to store the output of the
packagecommand. Defaults to
Here is a diagram of the structure, the bundle is named
MyApp ??? app.properties ??? icon.png ??? www ??? js ? ??? app.js ??? css ? ??? app.css ??? index.html
The packager requires all application content to live inside of a single directory, by default it looks inside of a directory named
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.
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.
-h flag will bring up the help menu.
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.
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:
On Mac, you can install git with the Xcode command line tools:
On windows, you should download the git installer:
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:
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:
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):
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.
Make sure you are in the root of your project directory, in our case that is DevGuideBootstrap, and run the following:
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
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.
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.
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.
275 Frank Tompa Drive
Canada, N2L 0A1
Copyright © 2016 Open Text SA and/or Open Text ULC. All Rights Reserved.
You need to sign in before voting.