View source for Documentation:Barcode - on Android - with Xamarin and MDriven

You can use this sample to scan a shelf and its items on an Android device, build a structured request from an MDriven ViewModel, and let MDrivenServer create or match the corresponding server-side objects. It is for developers extending an [[Documentation:MDriven In Xamarin|MDriven Xamarin]] application with barcode capture.

Official samples have been moved to a dedicated repository.
<message>Write the content here to display this box</message>
Samples moved from the installation folder of MDriven Framework to this new bitbucket Git Repository found here: https://bitbucket.org/MDrivenOpenSource/mdrivenofficialsamples
== What the sample demonstrates ==
The sample models a small storage-registration workflow:

# Scan a shelf barcode.
# Scan one or more item barcodes for that shelf.
# Build JSON from the ViewModel state.
# Send the JSON to the server.
# Interpret the JSON as transient objects and match or create persistent shelf and item objects.

For example, scanning shelf <code>ABC</code>, then items <code>123</code> and <code>234</code>, produces a request conceptually equivalent to:

<syntaxhighlight lang="json">
{
  "Barcode": "ABC",
  "FoundShelfAboveItems": [
    { "Barcode": "123" },
    { "Barcode": "234" }
  ]
}
</syntaxhighlight>

The exact JSON member names are defined by the ViewModel JSON configuration. Treat the example as the shape of the request, not as a fixed integration contract.

Watch this video walkthrough of the barcode scanning workflow.
  <div class="video">
    <div class="video__wrapper">
      <iframe src="https://www.youtube.com/embed/xxVmsm0Ntmo?rel=0&autoplay=0" frameborder="0" allowfullscreen></iframe>
    </div>
    <div class="video__navigation">
        <span class="navigation-item" data-video="xxVmsm0Ntmo"data-start="0" tabindex="0"> Barcode - on Android - with Xamarin and MDriven </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="10" tabindex="0"> Android App Functionality </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="70" tabindex="0"> Scanning QR and Barcodes </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="200" tabindex="0"> MDriven Application Server Model </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="250" tabindex="0"> Phone Model:</span>
        <span class="navigation-item sub" data-video="xxVmsm0Ntmo" data-start="265" tabindex="0"> StorageBuilder ViewModel </span>
        <span class="navigation-item sub" data-video="xxVmsm0Ntmo"data-start="335" tabindex="0"> Sync Action </span>
        <span class="navigation-item sub" data-video="xxVmsm0Ntmo" data-start="380" tabindex="0"> Scanner Action </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="500" tabindex="0"> Running the Model on the Server </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="590" tabindex="0"> Prototyping and Simulating </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="730" tabindex="0"> Xamarin Forms Project </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo"data-start="810" tabindex="0"> Code-Generated ViewModel (BuidStoragePage.xaml) </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="1110" tabindex="0"> Register/Login in MDriven Designer </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="1210" tabindex="0"> JSonToObjects </span>
        <span class="navigation-item" data-video="xxVmsm0Ntmo" data-start="1530" tabindex="0"> MVC ViewModel </span>
    </div>
  </div>
== Get the sample ==

The Android barcode sample is included in the MDriven official samples repository. The referenced sample folder is [https://bitbucket.org/MDrivenOpenSource/mdrivenofficialsamples/src/ff6c50f0355a/MDrivenTurnkey/Barcocde/?at=master Barcocde in MDrivenTurnkey].

The repository location and the referenced revision are historical. Review the repository structure and the dependency versions before using the sample in a current application.
== Design the model first ==

Model and test the business workflow before implementing the phone user interface. The sample uses a ViewModel named <code>BuildStorage</code> and a temporary, or ''transient'', scanned-shelf structure.

{| class="wikitable"
! Element
! Purpose in the sample
! Example
|-
| <code>FoundShelf</code>
| Holds the barcode scanned for the shelf during the phone session.
| <code>ABC</code>
|-
| <code>FoundShelfAboveItems</code>
| Holds the item barcodes scanned under the current shelf.
| <code>123</code>, <code>234</code>
|-
| <code>BuildStorage</code> ViewModel
| Provides the actions, variables, nesting, and JSON representation used by the client.
| Scan shelf, scan item, and sync
|-
| JSON ViewModel configuration
| Selects the root object and the attributes and associations to serialize.
| Shelf barcode plus its scanned item barcodes
|}

Keep the business rules in the model as [[Documentation:Learn OCL|OCL]] expressions. For instance, rules that decide whether a barcode identifies an existing shelf or whether an item may be added belong in the model, where they can be tested before the Android UI is written.
=== Prototype the workflow in MDriven Designer ===

Use the ViewModel UI to verify the workflow with simulated input:

# Open the <code>BuildStorage</code> ViewModel.
# Run the action that opens the scanner ViewModel.
# Enter a test scan result such as <code>ABC</code> and confirm it. The confirmation creates a <code>FoundShelf</code> and assigns its barcode.
# Repeat the scan flow for items, using values such as <code>123</code> and <code>234</code>.
# Run the sync action and inspect the JSON variable used for debugging.
# Confirm that the generated JSON contains the shelf and its nested items before building the Android page.

This separates model and integration errors from camera and device concerns.
== Build the Xamarin.Forms page ==

MDriven generates the ViewModel code, but the Xamarin.Forms user interface is authored in the mobile project. The sample uses a portable class library that contains the model and generated ViewModels; the generated code can be used from Android and iOS projects.

# Add a Xamarin.Forms page for the storage workflow, such as <code>BuildStoragePage</code>.
# Obtain the application's EcoSpace and create the generated <code>BuildStorage</code> ViewModel.
# Set that ViewModel as the page binding context.
# Add controls bound to the three actions: scan shelf, scan item, and sync.
# Bind an item list to the ViewModel association that holds scanned items.
# Bind each row's label to the item barcode attribute.
# During development, bind a label or editor to the JSON-to-send variable so that you can inspect the outgoing request. Remove this diagnostic UI before release.

The important binding path follows the ViewModel nesting. In this sample, the item list follows <code>FoundShelfAboveItems</code>; a row displays the nested item's <code>Barcode</code>.
=== Implement the scan actions ===

The sample opens a ZXing scanner page from each scan action and waits for the scanner result. When scanning finishes, the page closes and the application uses the returned barcode value to update the generated ViewModel objects.

{| class="wikitable"
! Action
! Client-side result
! Example
|-
| Scan shelf
| Create or assign the current <code>FoundShelf</code> and set its <code>Barcode</code> from the scanner result.
| Scan result <code>ABC</code> becomes the shelf barcode.
|-
| Scan item
| Add a scanned item below the current found shelf and set its barcode.
| Scan result <code>123</code> becomes an item below shelf <code>ABC</code>.
|-
| Sync
| Serialize the configured ViewModel root as JSON and post it to the server route.
| Send shelf <code>ABC</code> with item barcodes <code>123</code> and <code>234</code>.
|}

The sample uses ZXing for barcode scanning and Newtonsoft.Json in the mobile application. Camera permissions, platform setup, scanner-page configuration, and package versions are outside the MDriven model and must be configured in the Xamarin application.
== Configure the server request ==

The sync action is backed by an MDriven action that obtains JSON from the ViewModel. Its JSON configuration uses the found shelf as the root and includes the shelf's barcode and the barcodes of its nested items. The action posts this representation to a server route.

Do not hard-code a desktop-local server address in a phone build. A device must be able to reach the configured MDrivenServer endpoint. The walkthrough notes that a local endpoint was unsuitable for the device because of HTTP/certificate concerns; configure a reachable endpoint and validate its transport and certificate configuration for your environment.
== Process the request on the server ==

On the server, receive the POST body, assign it to a variable, and convert the JSON to objects. The sample interprets the request into transient shelf and item objects first. These objects exist in memory for processing; they are not the persistent inventory records.

Then apply the matching and creation rules:

# Find an existing shelf whose barcode matches the transient shelf barcode.
# If a match exists, associate the transient shelf with that persistent shelf.
# If no shelf matches, create a persistent shelf and assign the scanned barcode.
# For every transient item, find a persistent item with the same barcode.
# Associate matching items with their persistent objects.
# For each item with no match, create the persistent item and assign its barcode to the selected shelf.

For the earlier example, the server receives shelf <code>ABC</code> and items <code>123</code> and <code>234</code>. It reuses existing objects when their barcodes match and creates only the shelf or items that are missing. Adapt the matching, creation, and validation rules to your domain in the model's OCL.
== Test before deploying ==

# Test the ViewModel workflow with simulated scan results in MDriven Designer.
# Inspect the JSON produced by sync and verify that the root and nested items are included.
# Send the request to a test server endpoint.
# Verify that existing barcode matches are reused and unmatched barcodes create the intended persistent objects.
# Test camera scanning and network access on an Android device.
# Remove diagnostic JSON display and test-only server-address settings from the production UI.
== See also ==

* [[Documentation:MDriven In Xamarin]]
* [[Documentation:Example Gist]]
* [[HowTos:Generate QR Codes in Turnkey]]

[[Category:Connecting Turnkey to External APIs]]
[[Category:Intermediate-Friendly]]
[[Category:MDriven Turnkey]]
[[Category:Priority 50]]
[[Category:Turnkey How-To Guides]]