Skip to content

Design Phonegap Build Module

Jump to bottom
Adiche Rafik edited this page Mar 24, 2014 · 97 revisions

Home | Design documentation

#Introduction This document describes the use cases and the features of the module Phonegap Build in Ares IDE. It's organized in the following sections:

##General informations about Phonegap Build module Phonegap Build (PGB) module on Ares IDE supports the versions 2.7, 2.9, 3.0, 3.1 of the Adobe Phonegap Build framework.

In order to be able to use PGB, the Ares User must have an Active Phonegap account created with an Adobe ID. Here is registration link.

Phonegap Build module on Ares IDE offers to the user the possibility to select all of the mobile platforms that are supported by Phonegap Build:

  • Android from V2.2 to V4.4
  • IOS 5-6-7
  • Window Phone 7-8
  • WebOS & BlackBerry 10 (if the selected version of PG is below 3.0.0)

It's supported by the version 2.3.0 of ENYO.

#Use cases of Phonegap Build module in Ares

Fig-01. Use cases diagram of the Phonegap Build Ares module.

##Enable/Disable the Phonegap Build service For a given Ares IDE project, The user can turn on/off the Phonegap Build service when editing the project properties.

##Authenticate in Phonegap Build User Account The user must be authenticated in his Phonegap Build user account in order to enable the interaction between Ares IDE and Phonegap Build service.

##Edit the Phonegap configuration of the project The Phonegap Build module simplifies the Phonegap project configuration by offering an UI that generates the configuration file config.xml. Note: config.xml is the configuration file used by Phonegap framework to generate the native application form the Javascript project.

##Submit the project to PGB user account In order to build a Phonegap application from an Ares Project, the Phonegap Build module will upload the project into the Phonegap Build user's account. The PGB service will build the Phonegap Application.

##Download a built PGB application When the Phonegap application is successfully built, the user will be able to get this application by:

  • Selecting the targeted platform and chose to download the Phonegap applications in a sub-folder of the Ares project.
  • Using an auto-generated Qrcode from the URL of the selected Phonegap application.

##Select the Phonegap Build application The Ares user can see the list of all the built Phonegap applications in the Phonegap user's account in order to associate it with the project.

#Phonegap Build module general architecture

##Data model
The Phonegap Build module use 2 data models structures to store informations in a persistent way:

###User Authentication data When an Ares user is authenticated to his Phonegap Build account, the UserData object is saved in the local storage of the browser. This object have the following attributes :

  • userId [Integer]: the identifier used by Phonegap build to identify the PGB account
  • username [String]: the name of the PGB account user
  • email [String] : E-mail of the PGB account user
  • apps [Integer]: number of the Phonegap applications that are hosted in the PGB user account
  • androidKeys [Integer]: number of the Android signing keys that are defined in the PGB user account
  • blackberryKeys [Integer]: number of the BlackBerry signing keys that are defined in the PGB user account
  • iosKeys [Integer]: number of the IOS signing keys that are defined in the PGB user account

###Phonegap project configuration data

The configuration parameters of a Phonegap Build Ares project are stored in the file "project.json", this file contains the following blocs:

![](assets/PhonegapBuildModule/PGB -ProjectJson.png)

Fig-02. Screen capture on the project.json file.

The Phonegap Build specific parameters are located in the Providers block. These parameters are:

  • enabled: indicates if PhoneGap build is allowed for the project.
  • autoGenerateXml: boolean parameter to enable/disable the auto-generation of the config.xml file
  • minification: boolean parameter to enable/disable the project minification
  • features: array containing the state of activation for each Phonegap plugin that access device's hardware (Example: camera, battery, geolocation, ..).
  • preferences: defines Phonegap configuration attributes that are shared or specific to a platform (check the link). Example:
    • Shared preferences are: phonegap-version, orientation, fullscreen, target-device.
    • Specific preferences are like: android-minSdkVersion for Android, ios-statusbarstyle for IOS and disable-cursor for BlackBerry .
  • icon: list that defines (for each supported Phonegap Build platform) the parameters related to the location and the size(or the density) of the Phonegap application icon.
  • splashScreen: list that defines (for each supported Phonegap Build platform) the parameters related to the location and the size(or the density) of the Phonegap application splash screen.
  • plugins: holds the package name of the external Phonegap Build plugin. Currently, this attribute can't be defined from the Phonegap Build Ares UI.
  • access: defines a list of the authorized external URLs in the Phonegap application in order to access external resources.
  • targets: defines the list of the targeted Phonegap Build platforms for the project build.
  • appId: it is the reference of the submitted application in Phonegap Build user's account.

Here is two sequences diagram showing the interactions between Ares IDE on the file project.json:

Fig-03. Sequences diagram illustrating the interactions between Ares IDE and Phonegap Build module when loading the project configuration data into the PGB UI.

Fig-04. Sequences diagram illustrating the interactions between Ares IDE and Phonegap Build module when saving the the PGB UI values into the project configuration data.

###Phonegap Build attributes in the Project model The PGB data that are specific to the Phonegap Build edition panel in Ares are added as an attribute to the Project model instance. These attributes are:

  • downloadStatus: it's an array that hold a set of status messages. Each status message is related to one platform, it describes the download state of the built application in this platform.
  • validPgbConfig it's an array that hold the validation state of all the Phonegap Build UI rows.

##Ares module of Phonegap Build

Fig-05. Overview on the content of each file related to Phonegap Build.

The different files related to the Phonegap build feature are:

bdPhonegap.js:

REST API situated in the back-end of Ares IDE, the main actions that it does are :

  • Route the URL suffixes below to the following actions:
    • /token to the action getToken()
    • /api/v1/me to the action getUserData()
    • /api/v1/apps/:appId to the action getAppStatus()
    • /api/v1/apps/:appId/:platform/:title/:version to the action downloadApp()
  • Manage the upload of the zip package of the project to the PGB user account
  • Handle the minification of the Ares project

Build.js:

This is the client (front-end) Phonegap Build provider that will interact with bdPhonegap.js, using AJAX requests, in order to manage the lifecycle of a Phonegap Build application.

ProjectProperties.js

Holds the main kinds of the Phonegap Build UI, and contains the following kinds:

  • Phonegap.ProjectProperties: the Phonegap UI panel
  • Phonegap.ProjectProperties.Drawer: defines a drawer that's common for all supported target platforms
  • Phonegap.ProjectProperties.Target: sub-kind of Phonegap.ProjectProperties.Drawer, it defines a kind that's specific for a target platform; have an additional checkbox to disable/enable the target platform for the build.
  • Phonegap.ProjectProperties.AppId: container that manages the showing/hiding of the build status and the QrCode, it also manages the update of the PGB user data, where lies the list of the submitted PGB applications.
  • PhoneGapGridArranger: container for the application permissions checkboxes.

PhonegapUIRows.js

Contains the kind definition of all the Phongap Build UI rows, here is the list of the kinds:

  • Phonegap.ProjectProperties.Row: it's the super-kind of all the Phonegap Build UI rows
  • Phonegap.ProjectProperties.CheckBoxRow: defines a row with a checkbox and a label.
  • Phonegap.ProjectProperties.InputRow: defines a row with a label and an input field
  • Phonegap.ProjectProperties.NumberInputRow: sub-kind of Phonegap.ProjectProperties.InputRow that validates only numerical value.
  • Phonegap.ProjectProperties.AccessRow: defines a row with a label, an input field and a button. When the button is pressed, a new Phonegap.ProjectProperties.AddedAccessRow is added below.
  • Phonegap.ProjectProperties.AddedAccessRow: defines a row with a label, an input field and a button. When the button is pressed, the row is discarded
  • Phonegap.ProjectProperties.PickerRow: defines a row with a label and a picker. The picker have the displayed value equals to the selected value
  • Phonegap.ProjectProperties.SDKVersionRow: define a row with a label and a picker. The label of the selected value of this picker is different from the processed selected value. Example: in the "Max. API Level/Android Version" row the label of the selected value can be : "19 /Android 4.4", the processed selected value is "19".
  • Phonegap.ProjectProperties.ImgRow: defines a row with a label, a file chooser widget.
  • Phonegap.ProjectProperties.AndroidImgRow: defines a row with a label, a file chooser widget and a picker. The picker is used to select the resolution of the image (medium dp, high dp, x-large dp).
  • Phonegap.ProjectProperties.KeySelector: defines a row to select a signing key and the related credentials

PhonegapUIData.js

Contains the Phonegap.UIConfiguration that defines statics arrays holding all the needed information to instantiate each drawer and each row in the Phonegap Build UI.

BuildStatusUI.js

Defines the Build status widget that monitor the build state of the submitted Phonegap application in each supported platform, it contains the following kinds:

  • Phonegap.ProjectProperties.PlatformBuildStatus: defines a single platform icon
  • Phonegap.ProjectProperties.BuildStatus: container of the Build Status widget, holds all the supported platforms icon, the message container that display the status message. It's also in charge to initiate a request to the PGB service in order to refresh the build status data if at least, a build for a targeted platform is in pending state.
  • Phonegap.ProjectProperties.DownloadStatus: updates the download status message related to a targeted platform, the status message is displayed in the BuildStatus message container.

QrCode.js

Defines the kind Phonegap.ProjectProperties.QrCode that manages the generation of the Qrcode using the AppId and the authentication token of the user. The generation of the Qrcode is done by library qrcode.js placed in the folder ares-project\lib\foss

PhonegapAuthConfig.js

Defines the kind PhonegapAuthConfig that manages the authentication UI form of Phonegap Build.

PhonegapUserdata.js

The kind PhonegapUserdata manages the displaying of UI block holding PGB user data.

#Phonegap Build module features ##Authentication In order to use the features of PGB service in Ares, the Ares user must be authenticated in his PGB account (as illustrated in use cases diagram). To do the authentication action, these steps must be followed :

  1. From Ares IDE, select the accounts box

Fig-06. Screen capture of Ares Menu.

  1. Select the Phonegap Build service

Fig-07. Screen capture of Ares Accounts Popup.

  1. Enter the user account credentials (E-mail and Password of the Adobe ID).

Fig-08. Screen capture of Ares Accounts Popup with Phonegap Build Panel.

If the Authentication is successful, then a summary of the Phonegap user account will be displayed as shown in the screen capture below :

Fig-09. Screen capture showing a successful authentication.

Note that the highlighted red box contains the authentication model's attributes.

##Phonegap Build Edition Panel Phonegap Build module enable the Ares user to edit the properties of the Phonegap project through the Phonegap Build UI. this UI is accessible from the project menu:

Fig-10. Screen capture on the Project Menu.

If the Edit command is taped, then the project edition Popup is displayed:

Fig-11. Screen capture on the project edition Popup.

The Popup contains two Ares IDE shell's tabs: Project and Preview, and the Phonegap Build tab "Phonegap Build UI". From the tab Project, the user can enable/disable the Phonegap Build module support for the project.

Actually, The Phonegap Build UI aggregate three Phonegap Command interfaces:

Fig-12. Screen capture of the Phonegap Build UI.

  1. Phonegap project selection
  2. Phonegap Build build status
  3. Phonegap project configuration

###Phonegap project selection When the Phonegap Build UI is displayed, a list of all the submitted Phonegap application into the PGB user account are displayed in the picker Application. This picker can have 3 selected values:

  • The value <AppId - Application Title> that represents The current Application:(as shown in the screenshot below)
  • The value "Select AppId" if the saved AppId of the project does no-longer exist in the PGB user account
  • The value "New Application" if the user chooses to let the PGB service affect a new AppId to the Ares project.

Fig-13. Screen capture of the application picker with the selected application having the AppId:"775518" & the application title: "Example: My Application".

###Phonegap Build Build status A PGB application that's hosted in the PGB user account can have, at a time, one of the following status:

  • Not built: the package isn't submitted yet to PGB user account
  • Skipped: the platform wasn't selected for the build
  • Pending: PBG is still building the application for the targeted platform
  • Complete: the build succeeded for the targeted platform
  • Error: the build failed for the targeted platform

In Ares IDE, when a user select a PGB application, then an update is automatically done on the content of the widget Build Status. This widget is presented in the figure below:

Fig-14. Screen capture of Phonegap Build Status widget.

This figure highlights the following elements:

  1. Platform icon button: The Ares widget that monitor the build status represents each platform by an Icon button, the icon button can have the following colors:
  • Green: for the status Complete
  • Orange for the status Error
  • Gray: for the status Skipped or Pending

  1. Message container: Holds the Download button and the Status message elements. This container is displayed by clicking on a platform icon, and hidden by clicking on the close button.

  2. Download button: This button is displayed only if the status of the Phonegap application is Complete. In this case the download button is shown just under the corresponding Platform icon button. By clicking on it, the download action will be initiated.

  3. Build status message: When a Platform icon button is clicked; the corresponding status message will be displayed to expose explicitly the build state of the Phonegap application. Here are the possible messages:

  • Not built: displays the message: Application not built yet
  • Skipped: displays the message: Build skipped for this platform
  • Pending: displays the message: Build on progress
  • Error: displays the message: Error: < Error message returned by PGB service >
  • Complete: see the section below on downloading a built PGB application in a project sub-directory

When the project edition UI is opened, Ares will automatically look for the build status of the project by consulting PGB service. If any build platforms is in the pending state, then another request is sent after 3 seconds by Ares IDE in order to update the build status.

####Download a built PGB application in a project subdirectory When the Build status of an application is complete, then a download button (element number 3 in the figure 14) is shown along with the download status message Ready for download. When the download button is pressed, then the download status message will change to Download in progress. When the download is in progress, Ares ID send an AJAX request to PGB service in order to stream the built application into a local file located in the project subdirectory /targets/phonegap/. if this folder doesn't exist, then Ares IDE will create it automatically.

The download of the Phonegap application can end with one of the two messages:

  • Download successful: if the request sent by Ares IDE to the PGB service end with success.
  • Download failed: if the request sent by Ares IDE to the PGB service end with an error.

####Download the PGB application in a mobile device

Fig-15. Screen capture of the Qrcode generated for the application with the AppId: 775581.

The user can download a built package on his mobile device by scanning the QrCode presented in the build status view. There is one QrCode for one selected built application. When the Qrcode is scanned, an automatic redirection will be done by PGB service to point to the built application that fit the mobile device OS.

Here a sequence diagram to illustrate the interactions between Ares and PGB service in order to generate the QR code.

Fig-16. Sequence diagram of the QrCodeGeneration.

###Phonegap project configuration The Phonegap project configuration UI is a set of drawers, each drawer can be folded/unfolded to display its content. A drawer contains a set of rows, each row manage a single Phonegap project parameter.

The Build Options drawer let the user enable/disable two actions specific to Ares IDE which are:

  • Generate the config.xml file when building: when enabled, the PGB configuration drawers are displayed and each time the user submit the project package to PGB, the configuration file of the Phonegap application will be re-created and initialized from the values entered in the PGB UI configuration. When disabled, the PGB configuration drawers are hidden, and the config.xml file is no longer auto-generated in each package submission. This will enable the user to edit manually the config.xml file without going thru the PGB UI. This will also enable the user to add some tags that are not supported yet by the Phonegap Build UI.

    Example: the Phonegap Build UI allow to define only one instance of XML tag for a given platform. In Phonegap, it's possible to define multiple XML icon tags depending on the resolution of the device. So in order to overcome the limitation imposed by the Phonegap Build UI, the generation of the config.xml file must be turned off and then the user can edit manually the config.xml file to add as many icon tag as needed.

  • Activate the build minification: when enabled, the element reference by deploy.json will be merged and minified into a limited number of files. The file deploy.json is situated in the top level of the project and usually references:

    • The files: config.xml, index.html, icon.png & splashScreen.png
    • The folders: source, assets, enyo & lib with their content When disabled, the whole project content is submitted as it is to the PGB service when a build is required.

The other drawers in this UI contains rows that are translated later (in the Step 01 of Project upload to PGB account) into an XML tag in the file config.xml. For more informations on the role of each row, check the PGB documentation here.

##Uploading an Ares project into the Phonegap Build user account Ares IDE enables the user to build an Ares project using the PGB service, this can be done by selecting the build action as shown in the screenshot below:

Fig-17. Screen capture of the Project Menu.

To perform this actions there are some requirements:

  • Phonegap Build service must be enabled for the project
  • The Ares user must be authenticated in PGB service
  • At least one target build platform must be selected

If these requirements are fulfilled, then the build action can be initiated.

The project build in Ares IDE consist in these steps:

###Step 01

  • The Ares IDE client get the project's metadata
  • The Ares IDE client updates the config.xml file if it's auto-generated

Fig-18. Screen capture of the displayed "waiting Popup" in Ares IDE while performing Step 01 of the project upload to PGB user account.

###Step 02

  • The Ares IDE client send the project data to the Ares IDE server
  • The Ares IDE server minifies the project

Fig-19. Screen capture of the displayed "waiting Popup" in Ares IDE while performing Step 02 of the project upload to PGB user account.

###Step 03

  • The Ares IDE server generates a ZIP file from the project
  • The Ares IDE server submit the ZIP file to PGB

Fig-20. Screen capture on the displayed "waiting Popup" in Ares IDE while performing Step 03 of the project upload to PGB user account.

Here is a detailed sequences diagram illustrating these interactions:

Fig-21. Sequences diagram of the PGB project build in Ares IDE.

Note:

  • The in the sequence diagram above, each function prefixed with the symbol "*" is a block of instructions that isn't refactored into a function. These functions names are added in this diagram just to expose the functional actions that are done in the sequences 1, 13, 22 and 27.
  • In the sequence 8:_updateConfigXml(): if the auto-generation of the config.xml file is active, then the content of the file config.xml is updated from the Phonegap Build project data that are saved in the file project.json.

When the project zip file is sent to the PGB user account, the build status widget is shown to let the user monitor the build status of his project.

##Phonegap UI validation

Phonegap build UI proposes a value validation feature on:

  • Phonegap.ProjectProperties.NumberInputRow: the value must be a number.
  • Phonegap.ProjectProperties.PickerRow: the selected value must be an element of the content array associated to the picker row in Phonegap.UIConfiguration.
  • Phonegap.ProjectProperties.ImgRow: the values of the inputs "height" and width must be numerics.

Fig-22. Screen capture of an unvalidated PGB UI row.

When a sized value in an instance of the kinds above doesn't respect the rule, then :

  • An error message is displayed on the right of the row
  • The drawer containing the row is highlighted with red color
  • The Ok button of the Project wizard is disabled
  • An error tooltip containing the error message is displayed on the top of the Cancel button of the Project wizard

Fig-23. Sequences diagram showing the interaction between Ares kinds when a PGB UI row is unvalidated.

The Ok button will stay disabled if at least one row in Phonegap Build UI is invalid. The drawer will be highlighted if at least one row of the drawer is invalid.

If the values of the invalid rows are corrected then:

  • The error message on the right of the row is hidden
  • The drawer containing the row is un-highlighted
  • The Ok button of the Project wizard is enabled
  • The error Tooltip containing the error message on the top of the Cancel button is hidden.

Fig-24. Sequences diagram showing the interaction between Ares kinds when a PGB UI row is revalidated.

##References The source file used for the creation of the UML diagrams is attached to this JIRA ticket

Clone this wiki locally