Quick Start

Last updated: September 08th, 2024

Installation

1 - Install Cordova

Prerequisites:

Node.js (V20.17.0)

Install Gradle@7.6.2

Install Image Magick@7.1.0-36

Cordova command-line runs on Node.js (V20.17.0) and is available on NPM. Open a command prompt or Terminal, and type

npm install -g cordova@12.0.0

2 - Create Cordova project

Type in the command prompt or Terminal

cordova create HelloWorld com.ashera.hello

Add the following to config.xml:
<preference name="AndroidXEnabled" value="true" />
<preference name="SplashMaintainAspectRatio" value="true" />
<preference name="webScaleFactor" value="1.4" />
<preference name="iosHidetoolbar" value="true" />
Add the following (if needed) to config.xml:
<preference name="webHistoryUrlPrefix" value="<base url>/" />

3 - Update package.json with scripts

{
	...,
	"scripts": {
		"clean": "npm install && node cleanup.js",
	    "swt": "cd platforms/swt/app && gradle run",
	    "prebrowser": "cd platforms/browser/app && gradle execute",
	    "browser": "cd platforms/browser/app/src/main/assets/www && npm install -g http-server && http-server",
	    "generate-platform-res": "cd platforms/android/app/src/main/gentool && npm install --legacy-peer-deps && npm run resize && npm run start",
	    "generate-platform-js": "cd platforms/android/app/src/main/tsc && npm install --legacy-peer-deps && npm run build",
	    "generate-platform-drawable": "cd platforms/android/app/src/main/gentool && npm run resize",
	    "fix-ios-symLinks": "cd platforms/android/app/src/main/gentool && npm run fixIosSymLinks",
	    "update-ios-plist": "cd platforms/android/app/src/main/gentool && npm run plist",
	    "backup-android": "cd platforms/android/app/src/main/gentool && npm run backup",
	    "restore-android": "cd platforms/android/app/src/main/gentool && npm run restore",
	    "start-dev": "cd platforms/android/app/src/main/gentool && npm install --legacy-peer-deps && npm run fixIosSymLinks && npm run restore && npm run resize && cd ../tsc && npm install --legacy-peer-deps && cd ../gentool && npm run start skip_watch && cd ../tsc && npm run build",
		...
  	},
  	"dependencies": {
    	"fs-extra": "^10.1.0"
  	},
}

Create a file by named cleanup.js in the root directory. 

let projectBasePath = "";

const fs = require('fs-extra');
fs.removeSync(projectBasePath + "platforms", { recursive: true, force: true });
fs.removeSync(projectBasePath + "node_modules", { recursive: true, force: true });
fs.removeSync(projectBasePath + "plugins", { recursive: true, force: true });

4 - Add platforms

Platform supported
  • Android (android)
  • IOS (ios)
  • Browser (browser)
  • SWT (swt)

cd HelloWorld

cordova platform add android

cordova platform add ios

cordova platform add https://github.com/AsheraCordova/cordova-swt.git

cordova platform add https://github.com/AsheraCordova/cordova-web.git

5 - Install Ashera core

Type in the command prompt or Terminal

cordova plugin add https://github.com/AsheraCordova/Core

6 - Generate cross platform resources

Type in the command prompt or Terminal

npm run generate-platform-res

7 - Generate cross platform JS

Type in the command prompt or Terminal

npm run generate-platform-js

8 - Run on platform

Android

cordova run android

IOS

Download j2objc2.7 from the below location:
Download

Create symlink:

ln -s <Location of j2objc2.7 folder> /Library/j2objc

cordova run ios

Browser

npm -g install http-server

npm run browser -- -Dorg.gradle.java.home=<JAVA8_HOME>

Swt

npm run swt -- -Dorg.gradle.java.home=<JAVA8_HOME>

9 - Patch cordova library files

Ashera requires minor patches to the existing cordova installation to fix plugin rm operations on swt platforms.

The following changes have to be done manually:

Search platformsConfig.json under cordova node_modules. Example file location can be found below:

<<node installation>>/node_modules/cordova/node_modules/cordova-lib/src/platforms/platformsConfig.json

Add "swt" : {} as one of the platforms.

10 - Install additional Ashera plugins (optional)

cordova plugin add https://github.com/AsheraCordova/CapInsets

cordova plugin add https://github.com/AsheraCordova/ConstraintLayout

cordova plugin add https://github.com/AsheraCordova/CSSBorder

cordova plugin add https://github.com/AsheraCordova/Custom

cordova plugin add https://github.com/AsheraCordova/DateTime

cordova plugin add https://github.com/AsheraCordova/Drawer

cordova plugin add https://github.com/AsheraCordova/GridLayout

cordova plugin add https://github.com/AsheraCordova/RecycleView

cordova plugin add https://github.com/AsheraCordova/Toolbar

cordova plugin add https://github.com/AsheraCordova/IQkeyboardManager

cordova plugin add https://github.com/AsheraCordova/ShutterBug

cordova plugin add https://github.com/AsheraCordova/Glide

cordova plugin add https://github.com/AsheraCordova/SDWebImagePlugin

cordova plugin add https://github.com/AsheraCordova/Splash

cordova plugin add https://github.com/AsheraCordova/Dialog

cordova plugin add https://github.com/AsheraCordova/cordova-plugin-camera

cordova plugin add https://github.com/AsheraCordova/cordova-plugin-camera-swt

cordova plugin add https://github.com/AsheraCordova/cordova-plugin-qrscanner

cordova plugin add https://github.com/AsheraCordova/cordova-plugin-qrscanner-swt

cordova plugin add https://github.com/AsheraCordova/cordova-plugin-sqlite-2-swt.git

cordova plugin add https://github.com/AsheraCordova/TextInputLayout.git

cordova plugin add https://github.com/AsheraCordova/ViewPager.git

cordova plugin add https://github.com/AsheraCordova/Snackbar.git

cordova plugin add https://github.com/AsheraCordova/CoordinatorLayout.git

cordova plugin add https://github.com/AsheraCordova/CoordinatorLayout.git

cordova plugin add https://github.com/AsheraCordova/AppBarLayout.git

cordova plugin add https://github.com/AsheraCordova/NestedScrollView.git

cordova plugin add https://github.com/AsheraCordova/NavigationView.git

cordova plugin add https://github.com/AsheraCordova/TabLayout.git

cordova plugin add https://github.com/AsheraCordova/CardView.git

IDE

It is recommended to use Android Studio for ui development as it gives a preview of the xml with advanced refactoring capability. For JS development, it is recommended to Visual Studio code as it is free and has advanced refactoring capability.

Android Studio
1. Download and install Android studio.

2. Open existing project by browsing "project installation root"\HelloWorld\platforms\android
Visual Studio Code
1. Download and install Visual Studio Code.

2. Open the following folder "project installation root"\HelloWorld\platforms\android\src\main\tsc

Scripts

After Installation, package.json contains scripts which help to auto generate files from android xml and ts file which will aid in cross platform development. The following table lists the scripts available:

# Name Description
1 npm run clean Script used to delete node_modules, platforms and plugin folder.
2 npm run generate-platform-js Script used to generate index.js from tsc folder.
3 npm run generate-platform-res Script used to generate files in resources folder and drawable folder
4 npm run generate-platform-drawable Script used to generate resized png files in drawable folders from drawable-xxxhdpi folder.
5 npm run fix-ios-symLinks Script used to fix the symlinks to resources of android. IOS has bug where running cordova prepare in existing projects, symlinks in resources folders are lost. Run this script to fix the same.
6 npm run update-ios-plist Script used to update plist with custom fonts. Run if you add an custom font in the font folder.
7 npm run backup-android Script used to backup tsc and res folder.
8 npm run restore-android Script used to restore tsc and res folder.
9 npm run start-dev Script used to kick-off the development process by generating resources and index.js.

Development Tips

Development of ashera application is done in res folder and tsc folder of android. Run the following in 2 terminal windows during development:
npm run generate-platform-js
npm run generate-platform-res
This will ensure that resources and index js file are continuously updated.
If you add image in drawable-xxxhdpi folder, run
npm run generate-platform-drawable
If you are removing android platform, ensure that you back up and restore android files in res and tsc folder. npm run backup-android
npm run restore-android