diff --git a/programming/javascript/api-reference/interfaces/parsed-result-item-v2.4.2000.md b/programming/javascript/api-reference/interfaces/parsed-result-item-v2.4.2000.md new file mode 100644 index 0000000..4f1933c --- /dev/null +++ b/programming/javascript/api-reference/interfaces/parsed-result-item-v2.4.2000.md @@ -0,0 +1,121 @@ +--- +layout: default-layout +title: ParsedResultItem - Dynamsoft Code Parser JavaScript Interface +description: This page shows the ParsedResultItem interface of Dynamsoft Code Parser for JavaScript. +keywords: ParsedResultItem, javascript, interface +needAutoGenerateSidebar: false +noTitleIndex: true +breadcrumbText: ParsedResultItem +--- + +# ParsedResultItem + +The ParsedResultItem interface provides a structure representing the result items returned by Dynamsoft Code Parser. + +```ts +interface ParsedResultItem extends Core.CapturedResultItem { + codeType: string; + jsonString: string; + getFieldValue: (fieldName: string) => string; + getFieldMappingStatus: (fieldName: string) => EnumMappingStatus; + getFieldValidationStatus: (fieldName: string) => EnumValidationStatus; +} +``` + + + +## codeType + +Returns the code type of the parsed result. + +```ts +codeType: string; +``` + +## jsonString + +Returns the parsed result as a JSON formatted string. + +```ts +jsonString: string; +``` + +## getFieldValue + +Gets the value of a specified field from the parsed result. + +```ts +getFieldValue(fieldName: string): string; +``` + +**Parameters** + +`fieldName`: specifies the name of the field. + +**Return Value** + +A string which contains the field value. + +**Code Snippet** + +```js +parser.getFieldValue("passportNumber"); +``` + +## getFieldMappingStatus + +Gets the mapping status of a specified field from the parsed result. + +```ts +getFieldMappingStatus: (fieldName: string) => EnumMappingStatus; +``` + +**Parameters** + +`fieldName`: specifies the name of the field. + +**Return Value** + +A value that indicates whether the mapping succeeded. + +**Code Snippet** + +```js +await parser.getFieldMappingStatus("nationality"); +``` + +**See Also** + +* [EnumMappingStatus](../enum/EnumMappingStatus.md) + +## getFieldValidationStatus + +Gets the validation status of a specified field from the parsed result. + +```ts +getFieldValidationStatus: (fieldName: string) => EnumValidationStatus; +``` + +**Parameters** + +`fieldName`: specifies the name of the field. + +**Return Value** + +A value that indicates whether the validation succeeded. + +**Code Snippet** + +```js +await parser.getFieldValidationStatus("passportNumber"); +``` + +**See Also** + +* [EnumValidationStatus](../enum/EnumValidationStatus.md) diff --git a/programming/javascript/api-reference/interfaces/parsed-result-item.md b/programming/javascript/api-reference/interfaces/parsed-result-item.md index eb653cb..8a18982 100644 --- a/programming/javascript/api-reference/interfaces/parsed-result-item.md +++ b/programming/javascript/api-reference/interfaces/parsed-result-item.md @@ -16,7 +16,8 @@ The ParsedResultItem interface provides a structure representing the result item interface ParsedResultItem extends Core.CapturedResultItem { codeType: string; jsonString: string; - getFieldValue: (fieldName: string) => Promise; + getFieldValue: (fieldName: string) => string; + getFieldRawValue: (fieldName: string) => string; getFieldMappingStatus: (fieldName: string) => EnumMappingStatus; getFieldValidationStatus: (fieldName: string) => EnumValidationStatus; } @@ -51,7 +52,7 @@ jsonString: string; Gets the value of a specified field from the parsed result. ```ts -getFieldValue(fieldName: string): Promise; +getFieldValue(fieldName: string): string; ``` **Parameters** @@ -60,12 +61,34 @@ getFieldValue(fieldName: string): Promise; **Return Value** -A promise resolving to a string which contains the field value. +A string which contains the field value. **Code Snippet** ```js -await parser.getFieldValue("passportNumber"); +parser.getFieldValue("passportNumber"); +``` + +## getFieldRawValue + +Gets the value of a specified field from the parsed result, without mapping process. + +```ts +getFieldRawValue(fieldName: string): string; +``` + +**Parameters** + +`fieldName`: specifies the name of the field. + +**Return Value** + +A string which contains the field raw value. + +**Code Snippet** + +```js +parser.getFieldRawValue("passportNumber"); ``` ## getFieldMappingStatus diff --git a/programming/javascript/user-guide/index-v2.4.2000.md b/programming/javascript/user-guide/index-v2.4.2000.md new file mode 100644 index 0000000..b9273fa --- /dev/null +++ b/programming/javascript/user-guide/index-v2.4.2000.md @@ -0,0 +1,289 @@ +--- +layout: default-layout +title: User Guide - Dynamsoft Code Parser for JavaScript v2.x +description: This is the user guide page of Dynamsoft Code Parser for JavaScript SDK v2.x. +keywords: user guide, javascript +breadcrumbText: User Guide +noTitleIndex: true +needAutoGenerateSidebar: true +needGenerateH3Content: true +--- + + + +# Dynamsoft Code Parser for Your Website + +Dynamsoft Code Parser is designed to parse data strings (usually encrypted in barcodes, machine readable zones, etc.) into human-readable information. The JavaScript edition is based on WebAssembly and offers great speed and accuracy. With its well-designed API, you can equip your web pages with a code parser with just a few lines of code. + +In this guide, you will learn step by step on how to integrate the SDK into your website. + +Table of Contents + +- [Dynamsoft Code Parser for Your Website](#dynamsoft-code-parser-for-your-website) + - [Hello World](#hello-world) + - [About the code](#about-the-code) + - [Run the example](#run-the-example) + - [Building your own page](#building-your-own-page) + - [Include the SDK](#include-the-sdk) + - [Use a CDN](#use-a-cdn) + - [Host the SDK yourself](#host-the-sdk-yourself) + - [Configure the SDK](#configure-the-sdk) + - [Specify the license](#specify-the-license) + - [Specify the location of the "engine" files (optional)](#specify-the-location-of-the-engine-files-optional) + - [Interact with the SDK](#interact-with-the-sdk) + - [Load the specification for parsing](#load-the-specification-for-parsing) + - [Create a `CodeParser` object](#create-a-codeparser-object) + - [Start Parsing](#start-parsing) + - [System requirements](#system-requirements) + - [API Documentation](#api-documentation) + +## Hello World + +Dynamsoft Code Parser is designed to work both independently and alongside another functional product such as [Dynamsoft Barcode Reader](https://www.dynamsoft.com/barcode-reader/overview/) or [Dynamsoft Label Recognizer](https://www.dynamsoft.com/label-recognition/overview/). + +Let's start with the "Hello World" example of the SDK which demonstrates how to use the minimum code to enable a web page to parse an existing string into human-readable fields. + +The complete code of the "Hello World" example is shown below: + +```html + + + + + + + + + +
+ + + + +``` + +### About the code + +- `let passportMRZStr = "P NOTE: +> +> The sample code requires the following to run: +> +> 1. Internet connection +> 2. [A supported browser](#system-requirements) + +Please note: + +- Although the page should work properly when opened directly as a file ("file:///"), it's recommended that you deploy it to a web server and access it via HTTPS. +- On first use, you need to wait a few seconds for the SDK to initialize. +- The license "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9" used in this sample is an online license good for 24 hours and requires network connection to work. To test the SDK further, you can request a 30-day trial license via the Request a Trial License link. + +If the test doesn't go as expected, you can [contact us](https://www.dynamsoft.com/company/customer-service/#contact). + +## Building your own page + +### Include the SDK + +#### Use a CDN + +The simplest way to include the SDK is to use either the [jsDelivr](https://jsdelivr.com/) or [UNPKG](https://unpkg.com/) CDN. The "hello world" example above uses **jsDelivr**. + +* jsDelivr + + ```html + + + + ``` + +* UNPKG + + ```html + + + + ``` + +#### Host the SDK yourself + +Besides using the CDN, you can also download the SDK and host its files on your own website / server before including it in your application. + +Options to download the SDK: + +* npm + + ```cmd + npm install dynamsoft-core@3.4.20 --save + npm install dynamsoft-license@3.4.20 --save + npm install dynamsoft-code-parser@2.4.22 --save + ``` + +Depending on how you downloaded the SDK and where you put it, you can typically include it like this: + +```html + + + + +``` + +or + +```html + + + +``` + +or + +```typescript +import { LicenseManager } from "dynamsoft-license"; +import { type ParsedResultItem, CodeParser } from 'dynamsoft-code-parser'; +``` + +### Configure the SDK + +Before using the SDK, you need to configure a few things. + +#### Specify the license + +The SDK requires a license to work, use the method `Dynamsoft.License.LicenseManager.initLicense` to specify the license key. + +```javascript +//You can visit https://www.dynamsoft.com/customer/license/trialLicense?utm_source=github&product=dcp&package=js to get your own trial license good for 30 days. +Dynamsoft.License.LicenseManager.initLicense("YOUR-LICENSE-KEY"); +``` + +#### Specify the location of the "engine" files (optional) + +This is usually only required with frameworks like Angular or React, etc. where the referenced JavaScript files such as `core.js`, `dcp.js` are compiled into another file. + +The purpose is to tell the SDK where to find the engine files (\*.worker.js, \*.wasm.js and \*.wasm, etc.). The API is called `Dynamsoft.Core.CoreModule.engineResourcePaths`: + +```javascript +//The following code uses the jsDelivr CDN, feel free to change it to your own location of these files +Dynamsoft.Core.CoreModule.engineResourcePaths.core = "https://cdn.jsdelivr.net/npm/dynamsoft-core@3.4.20/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.license = "https://cdn.jsdelivr.net/npm/dynamsoft-license@3.4.20/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dcp = "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser@2.4.22/dist/"; +``` + +### Interact with the SDK + +#### Load the specification for parsing + +The SDK requires the specification of the code string to parse it. If we are going to parse the MRZ strings found on passports, we need the specification "MRTD\_TD3\_PASSPORT". + +```javascript +await Dynamsoft.DCP.CodeParserModule.loadSpec("MRTD_TD3_PASSPORT"); +``` + +#### Create a `CodeParser` object + +Then we create a `CodeParser` object. + +```javascript +let parser = null; +try { + parser = await Dynamsoft.DCP.CodeParser.createInstance(); +} catch (ex) { + console.error(ex); +} +``` + +Tip: When creating a `CodeParser` object within a function which may be called more than once, it's best to use a "helper" variable to avoid double creation such as `helperParser` in the following code + +```javascript +let helperParser = null; + +function foo() { + try { + const parser = await (helperParser = helperParser || Dynamsoft.DCP.CodeParser.createInstance()); + } catch (ex) { + console.error(ex); + } +} +``` + +#### Start Parsing + +The method `parse()` takes data in two formats: `Uint8Array` and `string`. `Uint8Array` refers to the binary data produced by another software such as Dynamsoft Barcode Reader. + +```javascript +let parsedResultItem = await parser.parse("THE-CODE-TO-PARSE"); +``` + +## System requirements + +The SDK requires the following features to work: + +- Secure context (HTTPS deployment) + + When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required because Dynamsoft License requires a secure context to work. + +- `WebAssembly`, `Blob`, `URL`/`createObjectURL`, `Web Workers` + + The above four features are required for the SDK to work. + +The following table is a list of supported browsers based on the above requirements: + + | Browser Name | Version | + | :----------: | :-----: | + | Chrome | v78+ | + | Firefox | v68+ | + | Safari | v14+ | + | Edge | v79+ | + +Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. + + + +## API Documentation + +For more information about the APIs of the SDK, read [Dynamsoft Code Parser JavaScript Edition API Reference](https://www.dynamsoft.com/code-parser/docs/web/programming/javascript/api-reference/?ver=2.0.20). diff --git a/programming/javascript/user-guide/index.md b/programming/javascript/user-guide/index.md index b9273fa..0c1c1c4 100644 --- a/programming/javascript/user-guide/index.md +++ b/programming/javascript/user-guide/index.md @@ -50,9 +50,9 @@ The complete code of the "Hello World" example is shown below: - - - + + +
- - + + + ``` * UNPKG ```html - - - + + + ``` #### Host the SDK yourself @@ -157,18 +157,18 @@ Options to download the SDK: * npm ```cmd - npm install dynamsoft-core@3.4.20 --save - npm install dynamsoft-license@3.4.20 --save - npm install dynamsoft-code-parser@2.4.22 --save + npm install dynamsoft-core@3.4.31 --save + npm install dynamsoft-license@3.4.31 --save + npm install dynamsoft-code-parser@2.4.32 --save ``` Depending on how you downloaded the SDK and where you put it, you can typically include it like this: ```html - - - + + + ``` or @@ -207,9 +207,9 @@ The purpose is to tell the SDK where to find the engine files (\*.worker.js, \*. ```javascript //The following code uses the jsDelivr CDN, feel free to change it to your own location of these files -Dynamsoft.Core.CoreModule.engineResourcePaths.core = "https://cdn.jsdelivr.net/npm/dynamsoft-core@3.4.20/dist/"; -Dynamsoft.Core.CoreModule.engineResourcePaths.license = "https://cdn.jsdelivr.net/npm/dynamsoft-license@3.4.20/dist/"; -Dynamsoft.Core.CoreModule.engineResourcePaths.dcp = "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser@2.4.22/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.core = "https://cdn.jsdelivr.net/npm/dynamsoft-core@3.4.31/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.license = "https://cdn.jsdelivr.net/npm/dynamsoft-license@3.4.31/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dcp = "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser@2.4.32/dist/"; ``` ### Interact with the SDK