You can deliver the same MDriven domain model to browser, desktop, hybrid mobile, and offline device applications; this page helps solution architects and developers choose the right client approach.

Choose a device delivery approach

Choose the client technology per use case and form rather than forcing every user through one interface. Your MDriven product and deployment choices can support a server-hosted application while selected workflows use a desktop-style or device-specific client.

User scenario	Suitable approach	What it is for
Many users access an application online	MVC	Server-hosted pages where broad web access is the main requirement.
Users need a desktop-oriented interaction model	AngularJS or WPF	Forms that benefit from a desktop feel rather than a conventional web page.
Users need an installed application that presents server functionality	Cordova-based app	A specific application shell that displays some or all of a server system and can use HTML5 device capabilities.
Users can lose all network access while working	A device-local MDriven Framework application with local persistence	Workflows that must continue when Wi-Fi and mobile connectivity are unavailable.

For example, an office user can work in a server-hosted MVC page, while a production worker can use a locally persistent application in an environment where radio signals are blocked by surrounding materials, underground locations, or shielded rooms.

Start with the connectivity requirement

Before choosing a client, identify what the user must be able to do when the network is unavailable.

1. List the data the user must read and change in the field. For example, a worker may need to view a planned item and record its production status.
2. Decide whether the workflow requires live server data. If it does, a server-hosted web or hybrid client may be sufficient.
3. If the workflow must continue without a connection, persist the required model data on the device.
4. Define how locally changed data will later be synchronized with the server. The Xamarin walkthrough demonstrates local persistence; synchronization to a Turnkey server through REST APIs is a separate design task.

Do not treat offline access as an edge case. A user can lose connectivity because of the physical work environment, not only because of travel or poor coverage.

Use device capabilities in browser-based applications

A browser-based application can access relevant device capabilities through HTML5 APIs when the browser and device support them. Examples include location, camera and microphone access, network information, vibration, Bluetooth, and battery status.

In MDriven, use an EXT_Component to integrate JavaScript that reads a browser or device capability and saves the result in your application. For example, an EXT_Component can call navigator.mediaDevices.getUserMedia to take a picture and store it in the app. Check availability first and handle the user's permission decision in the component.

Follow HowTos:Integrate Device Features in MDriven Apps Using the Navigator API for the implementation pattern and device-API examples. A device feature does not by itself provide offline data storage; plan local persistence separately when users must work disconnected.

Build a locally persistent Xamarin application

The Xamarin walkthrough shows how to replace manually maintained app data handling with an MDriven Framework EcoSpace and persist its data as XML on an Android device. An EcoSpace is the runtime context that holds the model objects and persistence configuration.

The sequence is:

1. Create the application's generated EcoSpace.
2. Attach handlers to its PMapperXml load and save events.
3. Initialize the application's generated ViewModel definitions with that EcoSpace.
4. Activate the EcoSpace.
5. Register it in the application's data store.
6. Create the generated ViewModel with the registered EcoSpace.

Initialize the EcoSpace

In the Android activity startup code, create and configure the EcoSpace before creating ViewModels. The following example uses the generated EcoProject1EcoSpace type from the walkthrough.

private EcoProject1EcoSpace _es;

protected override void OnCreate(Bundle bundle)
{
    // ...

    _es = new EcoProject1EcoSpace();
    _es.PMapperXml.OnLoadAsXML += Pm_OnLoadAsXML;
    _es.PMapperXml.OnSaveAsXML += Pm_OnSaveAsXML;

    ViewModelDefinitionsInApplication.Init(_es);

    _es.Active = true;
    BaseViewModel.DataStore.SetEcoSpace(_es);
}

The event handlers replace the default XML persistence behavior. They direct the persistence mapper to a file on the Android device instead.

Save the model data to the device

The save handler receives an XML document and a file name from the persistence mapper. It writes the XML to the Android external-storage directory, then sets ContinueWithDefault to false so that the default save behavior does not also run.

private void Pm_OnSaveAsXML(object sender, Eco.Persistence.OnSaveAsXMLArgs e)
{
    var path = global::Android.OS.Environment.ExternalStorageDirectory.AbsolutePath;
    var filename = System.IO.Path.Combine(path.ToString(), e.FileName);
    e.XDocumentToSave.Save(filename);
    e.ContinueWithDefault = false;
}

Load model data from the device

At load time, construct the same file path. If the file exists, read its XML text into LoadedDataAsXml and prevent the default load behavior.

private void Pm_OnLoadAsXML(object sender, Eco.Persistence.OnLoadAsXMLArgs e)
{
    var path = global::Android.OS.Environment.ExternalStorageDirectory.AbsolutePath;
    var filename = System.IO.Path.Combine(path.ToString(), e.FileName);
    if (System.IO.File.Exists(filename))
    {
        using (var fileStream = System.IO.File.OpenRead(filename))
        {
            using (var streamReader = new System.IO.StreamReader(fileStream))
            {
                e.LoadedDataAsXml = streamReader.ReadToEnd();
                e.ContinueWithDefault = false;
            }
        }
    }
}

If no file exists, this handler leaves the default behavior in place. Test both the first-run case and the case where a previously saved file is available.

Create a generated ViewModel

A ViewModel supplies the data and behavior that the client view uses. Create the code-generated ViewModel using the EcoSpace stored in BaseViewModel.DataStore.

viewModel = DMItemsViewModel.Create(
    BaseViewModel.DataStore.GetEcoSpace(),
    null);

In this example, DMItemsViewModel is a generated ViewModel type. Using the generated ViewModel keeps the client aligned with the model and reduces manually written data-handling code as the application changes.

Plan synchronization as a separate concern

Local XML persistence makes data available on the device. It does not define conflict handling, server communication, or synchronization of local changes. If users must later send changed data to a Turnkey server, define the server API contract and the behavior for changes made while disconnected before implementing synchronization.

For example, a barcode scan can be handled locally while offline and cached for later processing, or it can query server data when the device is online. The correct behavior depends on whether the scan result must be validated against current server data.

Watch the walkthrough

The MDriven in Xamarin walkthrough demonstrates adapting the default Xamarin Forms template to use MDriven, reducing manually written code, and storing data on the device.

See also

• Documentation:Framework
• Documentation:MDriven Product Line
• HowTos:Getting started template for MDriven MVC
• HowTos:Integrate Device Features in MDriven Apps Using the Navigator API
• Documentation:GettingStarted

Offline data and synchronization

Offline use is a separate application path from a server-connected application. For users who must work without network access, keep the offline data and logic in a small model running on the device. The local model can save data in an XML file or an SQLite database.

The device example on this page shows XML persistence by handling the persistence mapper's load and save events and reading or writing the XML file on the device.

Synchronization is application-specific

Do not assume that an offline application will automatically synchronize all local changes when it reconnects. Define the data to move, its direction, and the operations that send and receive it.

A possible approach is to use REST APIs to exchange the selected data between the local model and the server-based application. The synchronization discussion in the Convergence documentation describes defining sending and receiving ViewModels in the two models and making them compatible through name matching.

Before implementing synchronization, define:

• Which data must be available on the device while offline.
• Which changes are sent from the device to the server.
• Which data is retrieved from the server by the device.
• How the application handles incompatible or competing changes.

See also

• Documentation:Getting MDriven benefits on devices
• Documentation:Convergence – ViewModels, import, export, multi search, synchronization and Excel

Plan offline work and synchronization

Offline use is a separate application path from an online device application. Keep the offline scope in a small model that runs its logic on the device and persists its local data. The connected application remains server based.

The documented approach does not describe a "magic" offline mode that automatically synchronizes all data after a connection returns. When a local model must exchange data with a server-based application, use REST APIs and JSON information trees based on ViewModels.

Use separate local and server models

Put views and logic that must work without connectivity in the device-local model. Keep views that require server access in the server model.

For example, the device can retain locally changed data while offline and later exchange the relevant part of that data with the server application. A server-only view is available only when the device can connect to the server.

Part	Role
Device-local model	Runs local logic and holds data needed for offline work.
Server model	Runs the connected server application.
REST and ViewModels	Provide the basis for exchanging selected data between the local and server models.

Persist local data on the device

The local model needs device-local persistence. The Xamarin example on this page persists data as XML through an EcoSpace. The offline approach described in the video also mentions SQLite or an XML file as local storage options.

Exchange selected data through REST APIs and ViewModels

When synchronization is required, define the data to exchange between the local and server models. The described approach is to use REST APIs and JSON information trees based on ViewModels to move a selected part of the data changed locally back and forth.

Decide which views belong in the local model and which remain server-side. A view that must work from a local cache is implemented in the client-side model; a view that only works online remains on the server side.

See also

• Documentation:Framework
• Documentation:Convergence – ViewModels, import, export, multi search, synchronization and Excel
• HowTos:Integrate Device Features in MDriven Apps Using the Navigator API