Implementation¶

Level 1 - Basic Implementation¶

To achieve the most basic implementation of an "offline-compliant" module, you can simply use the isOnline property (described in Properties) to disable components of your module that will not function without an internet connection. If your module uses simple components that rely only on frontend logic or static code, this approach should be sufficient to create a stable module:

import { Group } from "@element-public/react-group";
import { useBaseProps } from '@hortiview/modulebase';
import { Disclaimer } from "@hortiview/shared-components";
import { 
    OnlineOnlyComponent, 
    ComponentThatWorksInBothConditions 
} from '../components';

export const ComponentThatCanBeUsedOffline = () => {
    const {isOnline} = useBaseProps();

    return (
        <Group>
            {
                isOnline 
                ? <OnlineOnlyComponent /> 
                : <Disclaimer text={t('onlyAvailableWhileBeingOnline')} />
            }
            <ComponentThatWorksInBothConditions />
        </Group>
    )
}

Level 2 - Recommended Implementation¶

To provide a professional module that supports reliable offline usage, a minimal approach is usually not sufficient to meet customer expectations. Depending on the specific module being developed, you will most likely rely on data sourced from HortiView, your own backend, or external APIs. To ensure that the module remains fully functional even without an active internet connection, all required data must be prefetched before the user attempts to access it.

This means that any data needed for offline use—whether originating from HortiView or a custom source—has to be retrieved proactively and stored within a dedicated browser‑based local storage solution. By doing so, the module continues to function seamlessly even in the event of an unstable or interrupted network connection.

The minimal implementation required for this workflow is module-level preloading, ensuring that all essential data is available locally as soon as the module is initialized.

As an best practice pattern, we defined an reliable implementation-flow, to achieve level 2:

1. Before enabling offline capabilities, the module must

Identify all write operations. Disable these operations conditionally using the platform’s isOnline logic by following the basic implementation. Ensure no write‑related features remain accessible during offline states.

This guarantees that the module behaves predictably and avoids invalid or partial writes while offline.

2. Data Precaching

The core of Level 2 is the precaching of all required read‑data before the device goes offline. Precaching means:

Data is fetched while online. Data is persisted in a non‑volatile browser storage. Future read operations depend on the persisted data rather than new network requests.

Appropriate storage mechanisms include:

• SessionStorage (Useful because the session persists across offline periods)
• LocalStorage (Persists beyond sessions)
• IndexedDB (Suitable for larger or structured datasets)

Volatile storage must not be used, as offline functionality must persist reliably across state changes. You can either use the implementation of the BaseModule (everythings already included and prepared) or implement precaching by own. You can use either strategy of the following to implement the precaching.

Precaching Strategies¶

Using the Platform BaseModule (Recommended)¶

The platform’s existing BaseModule provides a preconfigured persistent TanStack Query client. Features:

• Automatic query persistence
• Automatic storage in browser storage (LocalStorage / SessionStorage)
• Offline-safe behavior:
  • Queries are not executed while offline
  • Cached data is returned instead

This approach requires no additional custom logic beyond adopting the BaseModule.

Creating a Custom Query Client Provider¶

A module may implement its own TanStack Query configuration:

• Persistent query caching
• Manual configuration of offline behavior
• Custom storage logic if required

Although functionally equivalent to the BaseModule, this option introduces additional overhead and is generally discouraged unless necessary.

Implementing a Fully Custom Precaching Logic¶

Modules may implement their own persistence handling:

• Manual data fetching
• Writing to LocalStorage, SessionStorage, or IndexedDB
• Implementing custom fallback logic for offline reads

This approach offers flexibility but is more complex and error‑prone.

Level 3 - Full Implementation¶

To enable not only read access but also write operations during offline scenarios, the platform provides a mechanism for creating and managing so-called "OfflineActions." OfflineActions are structured instructions that any module can submit to the platform when a user attempts to perform a write operation (such as POST or PUT) while offline.

When connectivity is restored, the platform notifies each main module, allowing it to process its queued OfflineActions—even if the user has closed and reopened the application in the meantime. This approach overcomes the limitations of persisting full JavaScript functions, which is generally not feasible in web development due to dependencies on runtime context and module-scoped variables.

Instead, OfflineActions are defined as instruction sets containing the functionName to be executed and the corresponding arguments. When the platform detects that the device is back online, it returns these instruction sets to the relevant module, which then interprets and executes the appropriate functions based on the provided instructions. This ensures that complex write operations can be reliably deferred and executed once connectivity is restored, maintaining data integrity and a seamless user experience.