Merge pull request #10 from OutSystems/development

RMET-3028 Barcode Plugin - Prepare release of version 1.0.0

Author: alexgerardojacinto

CHANGELOG.md

@@ -6,4 +6,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The changes documented here do not include those from the original repository.
 
-## 1.0.0
+## [1.0.0]
+
+### iOS
+
+- Fix error codes and messages (https://outsystemsrd.atlassian.net/browse/RMET-3038).
+- Add `scanOrientation` argument to `scanBarcode` (https://outsystemsrd.atlassian.net/browse/RMET-2753).
+- Add `cameraDirection` argument to `scanBarcode` (https://outsystemsrd.atlassian.net/browse/RMET-2754).
+- Add `scanButtonText` argument to `scanBarcode` (https://outsystemsrd.atlassian.net/browse/RMET-2752).
+- Add `scanInstructions` argument to `scanBarcode` (https://outsystemsrd.atlassian.net/browse/RMET-2751).
+- Implement `scanBarcode` (https://outsystemsrd.atlassian.net/browse/RMET-2748).
+
+### Android
+
+#### 09-01-2024
+- Update error codes and messages (https://outsystemsrd.atlassian.net/browse/RMET-3037).
+
+#### 08-11-2023
+Android - Scan barcode feature (https://outsystemsrd.atlassian.net/browse/RMET-2758)
+
+### Cordova Wrapper
+
+- Add support for plugin's old version of the `scanBarcode` method (https://outsystemsrd.atlassian.net/browse/RMET-2916).
+- Add `scanBarcode` method (https://outsystemsrd.atlassian.net/browse/RMET-2916).

README.md

@@ -1,3 +1,116 @@
 # cordova-outsystems-barcode
 
-## Cordova Bridge for the OutSystems Officially Supported Barcode Plugin.
+*This plugin is SUPPORTED by OutSystems. Customers entitled to Support Services may obtain assistance through Support.*
+
+A barcode scanner for your mobile application. Supports many popular encoding types of 1D and 2D barcodes, presented in the following table.
+
+**1D Barcodes**
+
+|Code|iOS|Android's ML Kit|Android's ZXing|
+|:-|:-:|:-:|:-:|
+|Codabar|:warning:<br>(Available from 15.0)|:white_check_mark:|:white_check_mark:|
+|Code 39|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|Code 93|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|Code 128|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|Databar (GS1)|:warning:<br>(Available from 15.0)|:x:|:white_check_mark:|
+|EAN-8|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|EAN-13|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|ITF|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|ITF-14|:white_check_mark:|:x:|:x:|
+|ISBN-10|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|ISBN-13|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|ISBN-13 Dual Barcode|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|RSSExpanded|:warning:<br>(Available from 15.0)|:x:|:white_check_mark:|
+|UPC-A|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|UPC-E|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+
+**2D Barcodes**
+
+|Code|iOS|Android's ML Kit|Android's ZXing|
+|:-|:-:|:-:|:-:|
+|Aztec Code|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|Data Matrix|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|MaxiCode|:x:|:x:|:white_check_mark:|
+|Micro PDF 417|:warning:<br>(Available from 15.0)|:x:|:x:|
+|Micro QR|:warning:<br>(Available from 15.0)|:x:|:x:|
+|PDF 417|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+|QR Code|:white_check_mark:|:white_check_mark:|:white_check_mark:|
+
+## Installation
+
+```console
+cordova plugin add <path-to-repo-local-clone>
+```
+
+It's also possible to install via the repo's URL directly.
+
+```console
+cordova plugin add https://github.com/OutSystems/cordova-outsystems-barcode
+```
+
+## Supported Platforms
+
+- iOS
+- Android
+
+## Methods
+
+* OSBarcode
+	* [scanBarcode](#scan-barcode)
+
+* OSBarcodeScanner
+	* [scan](#scan)
+
+### Scan Barcode
+
+```js
+cordova.plugins.OSBarcode.scanBarcode(options, successCallback, errorCallback);
+```
+
+An action that triggers the barcode reader. If successful, it returns the text associated with the scanned barcode as a String. In case of an error, it returns the associated error code and message (TODO: link to the table).
+
+The action is composed of the following parameters:
+
+- **options**: A structure containing some configurations to apply to the barcode reader. It's composed of the following properties:
+	- **scanInstructions**: A text containing the scanning instructions.
+	- **cameraDirection**: An integer that indicates if the back (1) or front (2) camera will be used when triggering a new scan action.
+	- **scanOrientation**: An integer that indicates which orientation will the scanner assume: Portrait (1), Landscape (2) or Adaptive (3). "Adaptive" uses the device's current orientation.
+	- **scanButton**: A boolean that will display a scan button on the barcode reader. With the button, scanning will only be triggered when pressing the button instead of automatically when framing the barcode. A second click on the button disables scannning.
+	- **scanText**: A text to be displayed on the scan button. It will only be shown if **scanButton** is set to true.
+	- **androidScanningLibrary**: A text equivalent to the **OSBarcodeConstants.AndroidScanningLibrary** structure. It indicates which library will be used to perform the scan: MLKit or ZXing. As the name indicates, it's only applicable to "Android".
+- **successCallback**: A structure indicating that the action was successful. It returns a **ScanResult**: a text containing the value associated with the scanned barcode.
+- **errorCallback**: A structure indicating that the action was not successful. It returns an "error" structure, composed of:
+	- **code**: A text containing the error code.
+	- **message**: A text containing the error message.
+
+### Scan
+
+```js
+cordova.plugins.OSBarcodeScanner.scan(options, successCallback, errorCallback);
+```
+
+Being the older way to trigger the barcode reader, this was kept to keep retro compatibility. This action calls the [Scan Barcode](#scan-barcode) action, with the possible outputs being the same.
+
+The action is composed of the following parameters:
+
+- **options**: A structure containing some configurations to apply to the barcode reader. It's composed of the following properties:
+	- **scanInstructions**: A text containing the scanning instructions.
+	- **cameraDirection**: An integer that indicates if the back (1) or front (2) camera will be used when triggering a new scan action.
+	- **scanOrientation**: An integer that indicates which orientation will the scanner assume: Portrait (1), Landscape (2) or Adaptive (3). "Adaptive" uses the device's current orientation.
+	- **scanButton**: A boolean that will display a scan button on the barcode reader. With the button, scanning will only be triggered when pressing the button instead of automatically when framing the barcode. A second click on the button disables scannning.
+	- **scanText**: A text to be displayed on the scan button. It will only be shown if **scanButton** is set to true.
+- **successCallback**: A structure indicating that the action was successful. It returns a **ScanResult**: a text containing the value associated with the scanned barcode.
+- **errorCallback**: A structure indicating that the action was not successful. It returns an "error" structure, composed of:
+	- **code**: A text containing the error code.
+	- **message**: A text containing the error message.
+
+## Errors
+
+|Code|Message|iOS|Android|
+|:-|:-|:-:|:-:|
+|OS-PLUG-BARC-0004|Error while trying to scan code.|:white_check_mark:|:white_check_mark:|
+|OS-PLUG-BARC-0006|Couldn't scan because the process was cancelled.|:white_check_mark:|:white_check_mark:|
+|OS-PLUG-BARC-0007|Couldn't scan because camera access wasn’t provided. Check your camera permissions and try again.|:white_check_mark:|:white_check_mark:|
+|OS-PLUG-BARC-0008|Scanning parameters are invalid.|:white_check_mark:|:white_check_mark:|
+|OS-PLUG-BARC-0009|There was an error scanning the barcode with ZXing.|:x:|:white_check_mark:|
+|OS-PLUG-BARC-0010|There was an error scanning the barcode with ML Kit.|:x:|:white_check_mark:|

plugin.xml

@@ -6,22 +6,47 @@
   <js-module name="OSBarcode" src="www/OSBarcode.js">
     <clobbers target="cordova.plugins.OSBarcode"/>
   </js-module>
+
+  <js-module name="OSBarcodeScanner" src="www/OSBarcodeScanner.js">
+    <clobbers target="cordova.plugins.OSBarcodeScanner"/>
+  </js-module>
+
+  <js-module name="OSBarcodeConstants" src="www/OSBarcodeConstants.js">
+    <clobbers target="OSBarcodeConstants"/>
+  </js-module>
+
   <platform name="android">
     <config-file parent="/*" target="res/xml/config.xml">
       <feature name="OSBarcode">
         <param name="android-package" value="com.outsystems.plugins.barcode.OSBarcode"/>
       </feature>
+      <preference name="GradlePluginKotlinEnabled" value="true" />
+      <preference name="GradlePluginKotlinCodeStyle" value="official" />
     </config-file>
     <config-file parent="/*" target="AndroidManifest.xml"/>
-    <source-file src="src/android/com/outsystems/plugins/barcode/OSBarcode.java" target-dir="src/com/outsystems/plugins/barcode"/>
+    <source-file src="src/android/com/outsystems/plugins/barcode/OSBarcode.kt" target-dir="app/src/main/kotlin/com/outsystems/plugins/barcode"/>
+    <framework src="src/android/com/outsystems/plugins/barcode/build.gradle" custom="true" type="gradleReference" />
   </platform>
   <platform name="ios">
     <config-file parent="/*" target="config.xml">
       <feature name="OSBarcode">
         <param name="ios-package" value="OSBarcode"/>
       </feature>
     </config-file>
-    <source-file src="src/ios/OSBarcode.m"/>
-    <header-file src="src/ios/OSBarcode.h"/>
+
+    <dependency id="cordova-plugin-add-swift-support" url="https://github.com/OutSystems/cordova-plugin-add-swift-support.git#2.0.3-OS1"/>
+
+    <preference name="CAMERA_USAGE_DESCRIPTION" default=" " />
+    <config-file target="*-Info.plist" parent="NSCameraUsageDescription">
+      <string>$CAMERA_USAGE_DESCRIPTION</string>
+    </config-file>
+
+    <source-file src="src/ios/OSBarcode.swift" />
+    <source-file src="src/ios/OSBarcodeError.swift" />
+    <source-file src="src/ios/OSBarcodeScanArgumentsModel.swift" />
+
+    <source-file src="src/ios/frameworks/OSBARCArgumentMappable.swift" target-dir="extensions" />
+    <framework src="src/ios/frameworks/OSBarcodeLib.xcframework" embed="true" custom="true" />
+
   </platform>
 </plugin>

src/android/com/outsystems/plugins/barcode/OSBarcode.java

@@ -0,0 +1,101 @@
+package com.outsystems.plugins.barcode
+
+import android.content.Intent
+import com.google.gson.Gson
+import com.outsystems.plugins.barcode.controller.OSBARCController
+import com.outsystems.plugins.barcode.model.OSBARCError
+import com.outsystems.plugins.barcode.model.OSBARCScanParameters
+import com.outsystems.plugins.oscordova.CordovaImplementation
+import kotlinx.coroutines.runBlocking
+import org.apache.cordova.CallbackContext
+import org.apache.cordova.CordovaInterface
+import org.apache.cordova.CordovaWebView
+import org.json.JSONArray
+
+class OSBarcode : CordovaImplementation() {
+
+    companion object {
+        private const val ERROR_FORMAT_PREFIX = "OS-PLUG-BARC-"
+    }
+
+    override var callbackContext: CallbackContext? = null
+    private lateinit var barcodeController: OSBARCController
+    val gson by lazy { Gson() }
+
+    override fun execute(
+        action: String,
+        args: JSONArray,
+        callbackContext: CallbackContext
+    ): Boolean {
+        this.callbackContext = callbackContext
+        val result = runBlocking {
+            when (action) {
+                "scanBarcode" -> {
+                    scan(args)
+                }
+
+                else -> false
+            }
+            true
+        }
+        return result
+    }
+
+    override fun initialize(cordova: CordovaInterface, webView: CordovaWebView) {
+        super.initialize(cordova, webView)
+        barcodeController = OSBARCController()
+    }
+
+    override fun onActivityResult(requestCode: Int, resultCode: Int, intent: Intent?) {
+        super.onActivityResult(requestCode, resultCode, intent)
+        barcodeController.handleActivityResult(requestCode, resultCode, intent,
+            { result ->
+                sendPluginResult(result, null)
+            },
+            { error ->
+                sendPluginResult(null, Pair(formatErrorCode(error.code), error.description))
+            })
+    }
+
+    override fun onRequestPermissionResult(
+        requestCode: Int,
+        permissions: Array<String>,
+        grantResults: IntArray
+    ) {
+        // do nothing
+    }
+
+    override fun areGooglePlayServicesAvailable(): Boolean {
+        // do nothing
+        return true
+    }
+
+    private fun scan(args: JSONArray) {
+        setAsActivityResultCallback()
+        val parameters = buildScanParameters(args)
+        if (parameters != null) {
+            barcodeController.scanCode(getActivity(), parameters)
+        } else {
+            sendPluginResult(
+                null,
+                Pair(
+                    formatErrorCode(OSBARCError.INVALID_PARAMETERS_ERROR.code),
+                    OSBARCError.INVALID_PARAMETERS_ERROR.description
+                )
+            )
+        }
+    }
+
+    private fun buildScanParameters(args: JSONArray): OSBARCScanParameters? {
+        return try {
+            gson.fromJson(args.getString(0), OSBARCScanParameters::class.java)
+        } catch (e: Exception) {
+            null
+        }
+    }
+
+    private fun formatErrorCode(code: Int): String {
+        return ERROR_FORMAT_PREFIX + code.toString().padStart(4, '0')
+    }
+
+}

src/android/com/outsystems/plugins/barcode/OSBarcode.kt

@@ -0,0 +1,48 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.1.1'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+    repositories {
+        maven { url 'https://pkgs.dev.azure.com/OutSystemsRD/9e79bc5b-69b2-4476-9ca5-d67594972a52/_packaging/PublicArtifactRepository/maven/v1' }
+    }
+}
+
+repositories{
+    flatDir {
+        dirs 'src/main/libs'
+    }
+}
+
+
+apply plugin: 'kotlin-kapt'
+
+dependencies {
+    implementation("com.github.outsystems:oscore-android:1.2.0@aar")
+    implementation("com.github.outsystems:oscordova-android:2.0.0@aar")
+    implementation("com.github.outsystems:osbarcode-android:1.0.0@aar")
+
+    implementation 'androidx.appcompat:appcompat:1.4.1'
+    implementation "androidx.activity:activity-ktx:1.4.0"
+
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.5.0'
+    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.4.3'
+
+    implementation 'com.google.zxing:core:3.4.1'
+    implementation 'com.google.mlkit:barcode-scanning:17.2.0'
+    implementation "androidx.camera:camera-camera2:1.0.2"
+    implementation "androidx.camera:camera-lifecycle:1.0.2"
+    implementation "androidx.camera:camera-view:1.0.0-alpha31"
+    implementation "androidx.activity:activity-compose:1.4.0"
+    implementation 'androidx.compose.material3:material3:1.0.0'
+    implementation 'androidx.compose.material3:material3-window-size-class:1.0.0'
+}