Skip to content

Commit cf94659

Browse files
Tom-DynamsoftTom-Dynamsoft
authored
Merge pull request #1 from Dynamsoft/amro-branch
Amro branch
2 parents 5cc0d71 + 0970dc8 commit cf94659

File tree

4 files changed

+237
-0
lines changed

4 files changed

+237
-0
lines changed

‎1.hello-world/README.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# The Hello World Sample Set
2+
3+
As you have gone through the user guide, you might have seen some basic "Hello World" code to help you quickly create a basic web application that uses our SDK.
4+
5+
This sample set will revisit the Hello World code, and its implementation in some of the popular frameworks such as Angular, React, an Vue.
6+
7+
Let's break down each of the samples
8+
9+
### Hello World - Read Barcodes via Video
10+
11+
In this sample, you will find the basic lines of code ncessary to initialize the library and set it up.
12+
13+
Please note that if no license is specified in code via the `organizationID` property or the `productKeys` property, as shown in the commented lines of code, a 7-day public trial will be used starting from v8.2.5. In earlier versions, an error will be thrown if no license, trial or full, is specified.
14+
15+
Let's quickly break down the methods used in order:
16+
17+
- `createInstance`: This method instantiates a `BarcodeReader` object or a `BarcodeScanner` object, depending on the scenario.
18+
19+
- `onFrameRead`: This event is triggered after each single frame is scanned. The `results` object contains all the barcode results that the library found on this frame. In the above code, the results found in every frame are printed to the console.
20+
21+
- `onUnduplicatedRead`: This event is triggered when a new barcode (not a duplicate) is found. `txt` holds the barcode text value while `result` is an object that holds details of the found barcode. In this example, an alert will be displayed for each unique barcode found.
22+
23+
- `show`: Displays the UI of the `BarcodeScanner` object and starts the scanning process.
24+
25+
In fact, `onFrameRead` and `onUnduplicatedRead` do not have to both be defined in the code. `onUnduplicatedRead` is the more used one between the two as it is triggered when a new barcode is found rather than on every frame.
26+
27+
### Hello World - Read Barcodes from an Image
28+
The second sample in this set focusses on the secondary class of the JavaScript edition, `BarcodeReader`. To learn of the exact differences between the `BarcodeScanner` and `BarcodeReader` classes, please refer to the *BarcodeReader vs BarcodeScanner* section of the [User Guide](https://github.com/Dynamsoft/javascript-barcode#readme).
29+
30+
In this sample, a listener is set up so that the SDK decodes any image that the user uploads. Please note that the [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) API is used to read the uploaded file and convert it to a format suitable for the `BarcodeReader` API.
31+
32+
[`decode`](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/BarcodeReader.html?ver=latest#decode) is the main method to go for when using the `BarcodeReader` class, although the class offers a number of other methods should you work with base64 strings, for instance. The rest of the image decoding methods can be found [here](https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/BarcodeReader.html?ver=latest#decode-barcode).
33+
34+
### Hello World - Angular
35+
36+
This sample demonstrates how to use the library in an Angular application in the most basic manner. [Angular CLI](https://github.com/angular/angular-cli) v11.2.4 is used to generate this sample project.
37+
38+
As mentioned in the user guide, when working with Angular aplications, it is recommended to use the `dynamsoft-javascript-barcode` npm package. The library is then set up as its own component, in this case defined in `barcode-scanner`.
39+
40+
The majority of the `DBR` (short for Dynamsoft Barcode Reader) operations are grouped in the `barcode-scanner` folder. Since we are using the npm package, the engine files are not in the same location as the main library file, `src/app/dbr.ts`. Therefore, the `engineResourcePath` must be defined so that the library knows where to find the engine files.
41+
42+
In our sample, we assign the `engineResourcePath` to our jsDelivr CDN URL as it is the easiest way to go. However, you can choose to use the engine files in installed npm package instead as such:
43+
```js
44+
DBR.BarcodeScanner.engineResourcePath = "/node_modules/dynamsoft-javascript-barcode/dist/"; // use the npm package in node_modules
45+
```
46+
Please note that the path is relative to where the `dbr.ts` file is compared to the `node_modules` folder.
47+
48+
The license is also defined in `dbr.ts`, so please input your `organizationID` in order to use the trial license. Of course, this assumes that you requested a new trial license for DBR JavaScript via the customer portal.
49+
50+
Let's do a quick breakdown of the `barcode-scanner` folder where the barcode scanner component is declared and all of its operations are defined:
51+
52+
- `barcode-scanner.component.ts`: The core file where the scanner is created (via `createInstance`) and assigned a UI element (via `setUIElement`). Afterwards, the `onFrameRead` event action was set, and lastly the scanner is opened via the `open` method.
53+
54+
- `barcode-scanner.component.html/barcode-scanner.component.css`: Define the UI of the scanner object. Many of the elements referenced in these files (e.g. `dbrScanner-video`) are inherited from the default UI elements of the library defined in the engine files.
55+
56+
- `barcode-scanner.component.spec.ts`: Contains the unit tests of the component.
57+
58+
The `hello-world` component in turn implements the `barcode-scanner` component, with the main operation being defined in `hello-world.component.ts` and the UI in `hello-world.component.html`.
59+
60+
### Hello World - React JS
61+
Much like the Angular implementation, the library is set up as its own component in the React JS implementation, based on the npm package `dynamsoft-javascript-barcode`. This sample project is bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
62+
63+
The barcode scanner component is defined in the `components` folder. `BarcodeScanner.js` is the most basic implementation of the library as a React component. The `BarcodeScanner` component is then used in the parent component, `HelloWorld`.
64+
65+
Please note that since we are using the npm package, the `engineResourcePath` must be defined in the `src/dbr.js` file, similar to the Angular implementation. In addition, the license must be specified via `organizationID` or `productKeys`, depending on the version of the library you are using.
66+
67+
### Hello World - Vue JS
68+
The Vue implementation of the Hello World sample is very similar to the React and Angular implementations. Of course, this implementation will be based on the npm package `dynamsoft-javascript-barcode`.
69+
70+
The `BarcodeScanner.vue` component, defined in the `components` folder, includes the basic `DBR` methods to get the video scanner up and running. The `BarcodeScanner.vue` component is then used in the parent component, `HelloWorld`.
71+
72+
Like the previous implementations, the `engineResourcePath` and license will need to be defined in `src/dbr.js`
73+

‎2.ui-tweaking/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# UI Customization Sample Set
2+
3+
In this sample set, we will focus on the library's flexible UI that allows developers to create the look and feel for their web application that they desire. To learn more about UI customization, please refer to its corresponding [section](https://github.com/Dynamsoft/javascript-barcode#233-customize-the-ui) in the user guide.
4+
5+
Let's begin by breaking down each of the samples in this set
6+
7+
### Display Barcode Results in Real-Time
8+
9+
In this sample, we perform simple tweak of the default UI to include a couple of `span` elements that will display the barcode text and barcode format as they are detected via video. Our basic 'Hello World' samples displayed the results in the console or via an alert box, so this sample will offer a more user-friendly way of showing the results as they are found.
10+
11+
In the `onFrameRead` event function, a pair of `span` elements are created for each found barcode. The `span` elements are then populated with the barcode text and the barcode format. Afterwards, the scanner UI (via `getUIElement`) is appended to the newly created `span` elements to complete this custom UI.
12+
13+
This is a simple tweak to the UI, but offers a much less intrusive way of displaying the barcode results as they are acquired.
14+
15+
### Hide Display Controls
16+
As explained in the user guide, the default UI comes with 3 core components: a video viewer, a source select dropdown, and a resolution select dropdown. The UI also comes with a built-in close button which allows the user to close the video viewer and barcode scanner.
17+
18+
However, you might encounter a situation where you do not require those extra components and would like to simply display the video viewer, and perhaps automatically close it when a barcode is found.
19+
20+
In this sample, we've chosen to hide the source select dropdown (`dbrScanner-sel-camera`), the resolution select (`dbrScanner-sel-resolution`), and the close button (`dbrScanner-btn-close`). This way, only the video viewer will show up when `scanner.show()` is called.
21+
22+
### Set up External Controls
23+
24+
In the last sample, we chose to hide the extra control options that come with the default UI. This time around, we will choose to hide the default control elements that come with the UI (e.g. `dbrScanner-sel-camera`) and set up our own controls instead using simple `select` and `button` elements.
25+
26+
First off, the external elements must be included in the HTML body, whether they are created programatically in JS or declared manually in the HTML code. In our sample, these elements are contained within the parent `div`, `externalControls`. The following external controls are set up:
27+
- `cameraList`: This `select` element is populated with all the currently connected and available cameras. This is done in the `updateCameras()` function. This function utilizes the `getAllCameras` API method, which retrieves all the camera info once called. Should the user select a different camera (`onchange`), then the scanner will switch to that camera via the `scanner.play()` method.
28+
- `resolutionList`: Similar to the camera list, this `select` element will be populated with a list of resolution values. However, these values are manually included as options rather than automatically populated via a certain function. Whenever the resolution is changed, the `setResolution` method is used to translate this change to the video viewer.
29+
- `toggleScanRect`: Cycles through various scan regions, where the scan region will be a subset of the total video viewer. This control is not found in the default UI of the scanner, but can be easily configured using the `region` property of the `RuntimeSettings`. In this sample, we assigned a set of 5 scan regions and each time the user clicks the button, the library cycles to the next scan region.
30+
- `toggleScanLight`: Controls whether the scan "light" is toggled on. Please note that this light does not actually improve the performance of the scanning process, but offers a user-friendly visual representation of the scanning process that is ocurring. Whenever the button is clicked, the style of the `dbrScanner-scanlight` element is reversed.
31+
- `toggleSound`: Controls whether the library beeps or not on a found barcode. This is translated to the library API via the `bPlaySoundOnSuccessfulRead` property.
32+
33+
These are just a few of the external controls that you can easily set up using the library API, offering your users more control over the scanner.
34+
35+
### Changing Size of Video Viewer
36+
In the last sample of the set, we explore how to switch the video viewer from occupying a limited screen area to a full screen view.
37+
38+
This customization does not involve any of the library API directly, and and is done simply via the `style` properties, as shown in the click event listener of the `fitPage` button or the `exitFullPage` function.

‎3.settings/using-different-modes.html‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
4+
<head>
5+
<meta charset="utf-8">
6+
<meta name="viewport" content="width=device-width,initial-scale=1.0">
7+
<title>Dynamsoft Barcode Reader Sample - Using Runtime Settings</title>
8+
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@8.2.5/dist/dbr.js"></script>
9+
<link rel="stylesheet" href="settings-css.css">
10+
<link rel="stylesheet" href="../balloon.min.css"> <!-- Used for tooltip styling -->
11+
</head>
12+
13+
<body>
14+
<h2>Using Different RuntimeSettings Templates</h2>
15+
<button id='openSimpleSettingsMenu'>Open Runtime Settings Menu</button>
16+
17+
<input type="text" id="result" title="Double click to clear!" readonly="true" class="latest-result"
18+
placeholder="The Last Read Barcode">
19+
<!-- Manually defining the div that will contain the video so that the UI doesn't take up the full screen-->
20+
<div id="div-video-container">
21+
<span id='lib-load' style='font-size:x-large' hidden>Loading Library...</span>
22+
<video class="dbrScanner-video" playsinline="true"></video>
23+
<canvas class="dbrScanner-cvs-drawarea"
24+
style="width: 100%; height: 100%; position: absolute; left: 0px; top: 0px; object-fit: contain;"
25+
width="1280" height="720"></canvas>
26+
</div>
27+
28+
<!-- Settings Menu displayed in a modal -->
29+
<div id="settingsModal" class="modal">
30+
<div id="settingsContent" class="modal-content">
31+
<span id="closeModalBtn" class="closeModal">&times;</span>
32+
<div class="tooltip"
33+
aria-label="The library comes with four pre-built templates that you can choose for the RuntimeSettings without needing to change the runtime settings individually, which could be tasking. Cycle through each mode to find out the differences between them."
34+
data-balloon-pos="down" data-balloon-length="fit">Choose Which Mode to Use
35+
</div>
36+
<form id="chooseSettingsMode">
37+
<input type="radio" id="single" name="settingsMode" value="single">
38+
<label for="single"> single </label><br />
39+
<input type="radio" id="speed" name="barcodeFormat" value="speed">
40+
<label for="QR"> speed </label><br />
41+
<input type="radio" id="coverage" name="barcodeFormat" value="coverage">
42+
<label for="coverage"> coverage </label><br />
43+
<input type="radio" id="balance" name="barcodeFormat" value="balance">
44+
<label for="balance"> balance </label> <br />
45+
</form>
46+
</div>
47+
</div>
48+
49+
<!-- JS Code -->
50+
<script src="initScanner.js"></script> <!-- To initialize the barcode scanner -->
51+
52+
<script>
53+
/** Beginning of barcode formats assignment
54+
* Should the user select one of the barcode format options,
55+
* update the runtime settings accordingly and in the correct selection order
56+
*/
57+
chooseBarcodeFormats.onchange = async function () {
58+
try {
59+
const checkboxes = document.querySelectorAll('input[name="barcodeFormat"]:checked');
60+
let settings = await scanner.getRuntimeSettings();
61+
settings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_NULL; // Set it to NULL first since the default is BF_ALL
62+
checkboxes.forEach((checkbox) => {
63+
// go through each of the checked options and perform a compound bitwise OR
64+
// to include each of the selected formats
65+
switch (checkbox.value) {
66+
case "BF_ONED":
67+
settings.barcodeFormatIds |= Dynamsoft.DBR.EnumBarcodeFormat.BF_ONED;
68+
break;
69+
case "BF_QR_CODE":
70+
settings.barcodeFormatIds |= Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE;
71+
break;
72+
case "BF_PDF417":
73+
settings.barcodeFormatIds |= Dynamsoft.DBR.EnumBarcodeFormat.BF_PDF417;
74+
break;
75+
case "BF_DATAMATRIX":
76+
settings.barcodeFormatIds |= Dynamsoft.DBR.EnumBarcodeFormat.BF_DATAMATRIX;
77+
break;
78+
}
79+
});
80+
await scanner.updateRuntimeSettings(settings);
81+
}
82+
catch (ex) {
83+
alert(ex.message);
84+
}
85+
}
86+
87+
/* End of barcode formats assignment */
88+
89+
/* Now for the expected barcodes */
90+
// Should the user enter the expected number of barcodes to be found per scan,
91+
// the runtime settings are updated as follows
92+
expectedNumberBarcodes.onchange = async function () {
93+
try {
94+
let expectedVal = document.getElementById('expectedNumberBarcodes').value;
95+
document.getElementById('expectedNumberBarcodesLable').innerText = expectedVal;
96+
let settings = await scanner.getRuntimeSettings();
97+
settings.expectedBarcodesCount = expectedVal;
98+
await scanner.updateRuntimeSettings(settings);
99+
}
100+
catch (ex) {
101+
alert(ex.message);
102+
}
103+
}
104+
</script>
105+
</body>
106+
107+
</html>

‎4.use-case/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Use Case Sample Set
2+
3+
This sample set explores some of the most popular real world applications of the `DBR` library that our team has encountered throughout our many years of experience.
4+
5+
### Filling a Form Field with the Barcode Scanner
6+
The first sample will demonstrate how to implement one of, if not the most common usage scenario our library encounters: Filling a form or form field based on the barcode result.
7+
8+
Usually this scenario involves oopening the video scanner on the click of a button, and then once the barcode is scanned, the barcode result would show up in a corresponding form field. In some cases, the form field would come with a tooltip style of button to allow the user to open the scanner on the click of that icon.
9+
10+
This is done in the `onUnduplicatedRead` method of the `scanner` object, so that it is almost instantaneous with finding the barcode.
11+
12+
### Filling out Driver's License Info via the Barcode Scanner
13+
Another very popular scenario is extracting the driver license info that is encoded on the back of driver licenses into a readable text. The text that is normally encoded in the barcode comes as one large string, separated by abbreviations only. The string will in turn require parsing and mapping to have all the info in its corresponding fields.
14+
15+
In order to ensure that the scanner picks up only PDF417 barcode types, we first ensure that the `barcodeFormatIds` of the `RuntimeSettings` is set to `BF_PDF417`. This way, the scanner is better configured to pick up the driver license barcodes.
16+
17+
The core text extraction happens in the function `extractInformation`. Please pay special attention to the `driverLicenseFields` variable, which contains all the mapping defintions for the different abbreviations.
18+
19+
By following a similar extraction and mapping mechanism, you can easily implement this feature in your own web application.

0 commit comments

Comments
 (0)