StateLayout Documentation

StateLayout is a library designed to manage default/empty states (e.g., loading, error, empty data) across an entire application or within specific local layouts.

Key Features:

• Global or Local States: Manage empty states for the whole app or specific UI components.
• Flexible Declaration: Define layouts via XML or programmatically via code.
• Built-in Functionality: Quick configuration for 'click to retry' actions, custom animations, and skeleton screens.
• Callbacks: Listen to state change events.
• Automation Support: Can be integrated with BRV for list states and Net for network request states to automate state switching without manual intervention.

StateLayout natively supports four states: Error, Empty, Loading, and Content (the wrapped view).

If you need to distinguish between different types of a single state (for example, differentiating between a Network Error and a Business Logic Error), you can use a tag to identify the specific condition. You can pass an exception object or any other object as a tag when triggering the error state.

// Pass an exception object as a tag to distinguish error types
showError(NetNetworkingException())

To handle the simultaneous hiding of the previous state and the showing of the new state, implement the StateChangedHandler interface. This allows you to orchestrate complex transitions between different Status types.

Built-in Handler: FadeStateChangedHandler

The framework provides a FadeStateChangedHandler which implements a cross-fade transition. It uses onRemove to fade out the old view and onAdd to fade in the new view.

Configuration

You can set a custom or global handler via StateConfig.stateChangedHandler.

// Configure a global handler
StateConfig.stateChangedHandler = FadeStateChangedHandler(duration = 400)

To achieve maximum customization, implement the StateChangedHandler interface. This allows you to replace the default empty state switching logic, including defining custom animations for showing/hiding states and customizing layout parameters (width/height).

By default, StateChangedHandler uses removeView/addView. If you prefer using visibility (e.g., View.GONE vs View.VISIBLE), you must implement this logic yourself within your custom handler.

// Set for a specific instance (Singleton approach)
state.stateChangedHandler = StateChangedHandler()

// Set globally for all instances
StateConfig.stateChangedHandler = StateChangedHandler()

You can specify the layouts for different states (Empty, Error, and Loading) using either XML attributes or programmatic configuration.

XML Configuration

Use the following app: attributes within your StateLayout declaration:

• app:empty_layout
• app:error_layout
• app:loading_layout

Programmatic Configuration

Access the StateLayout instance and assign layout resource IDs to the corresponding properties:

// Programmatic configuration
state.apply {
    emptyLayout = R.layout.layout_empty
    errorLayout = R.layout.layout_error
    loadingLayout = R.layout.layout_loading
}

You can enable automatic retry functionality by providing the ID of a View (such as an image or a button) that users can click when the system is in an error or empty state. When the specified View is clicked, StateLayout will automatically call showLoading() to attempt a retry.

There are two ways to configure this:

1. Instance-based (Singleton/Local): Set retry IDs for a specific StateLayout instance.
2. Global configuration: Set retry IDs globally for all StateLayout instances using StateConfig.

// Instance-based configuration
state.setRetryIds(R.id.msg)

// Global configuration
StateConfig.setRetryIds(R.id.msg)

You can define a global callback for error states using StateConfig.onError. This allows you to intercept the error tag (the object passed to showError) and perform specific UI updates, such as changing an error image or adding a specific view, based on the type of error encountered.

StateConfig.onError {
    if (it is NetNetworkingException) {
        // For network exceptions, show a specific error image
        findViewById<View>(R.id.iv_error).setImageResource(R.drawable.ic_networking_error)
    }
}

In StateLayout, skeleton animation is treated as a specific type of loading state animation. To prevent the animation from flickering (flashing) when network requests are too fast, you should implement a custom LeastAnimationStateChangedHandler.

This handler ensures that the animation has a minimum execution time, providing a smoother user experience by preventing the loading state from being interrupted immediately by a success or error state.

// Note: The implementation logic is demonstrated in the project's SkeletonAnimationActivity.kt
// You should implement LeastAnimationStateChangedHandler to control the minimum duration of the animation state.

You can perform global configuration for StateLayout within your Application class using StateConfig. This allows you to define default layouts for empty, error, and loading states, set a global retry ID, and provide global callbacks for state transitions.

StateConfig.apply {
    // Set default layouts for different states
    emptyLayout = R.layout.layout_empty
    errorLayout = R.layout.layout_error
    loadingLayout = R.layout.layout_loading

    // Set the global ID used for retry actions
    setRetryIds(R.id.msg)

    // Global callbacks for state changes
    onLoading {
        // Handle loading state globally
    }

    onEmpty {
        // Handle empty state globally
    }

    onError {
        // Handle error state globally
    }
}