Loading Spinner

The Despia Native Loading Spinner SDK enables your application to display a native loading indicator during asynchronous operations. This provides a seamless user experience while your application performs background tasks, API calls, or resource-intensive operations.

Quick Start

1. Show the Loading Spinner

Display a native loading spinner overlay on the screen.

Copywindow.despia = "spinneron://"

2. Perform Your Operations

Execute your asynchronous operations or tasks while the spinner is displayed.

Copy// Example: Fetch data from an API
fetch('https://api.example.com/data')
  .then(response => response.json())
  .then(data => {
    // Process your data here
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error);
  })
  .finally(() => {
    // Hide spinner when operation completes (success or error)
    window.despia = "spinneroff://"
  });

3. Hide the Loading Spinner

Hide the native loading spinner when your operations are complete.

Copywindow.despia = "spinneroff://"

How It Works

Native Implementation

The Loading Spinner SDK leverages the device's native loading indicator UI, providing a consistent experience with the operating system's design language. This ensures that your application feels integrated with the platform.

Thread Management

The spinner runs on a separate thread, allowing your application to perform intensive operations without affecting the spinner's animation smoothness.

Automatic Styling

The spinner automatically adapts to the device's light/dark mode settings and respects the platform's design guidelines.

Implementation Examples

Here's how you can implement the Loading Spinner in different scenarios:

Copy// Basic implementation example
function fetchData() {
  // Show spinner before operation starts
  window.despia = "spinneron://";
  
  // Perform your asynchronous operation
  setTimeout(() => {
    // Your code here...
    
    // Hide spinner when done
    window.despia = "spinneroff://";
  }, 2000);
}

// EXAMPLES FOR NO-CODE/LOW-CODE TOOLS
            
// ---------- WEWEB ----------     
// WEWEB example using wwWorkflow to handle loading states
// 1. Create a Native WeWeb Global Workflow for showing the spinner:         
window.despia = "spinneron://"
// 2. Perform your operation in another workflow
// 3. Create another Native WeWeb Global Workflow for hiding the spinner:
window.despia = "spinneroff://"

// ---------- WIZED ---------- 
// WIZED example using Wized's JS API
// Show spinner before making a request
window.despia = "spinneron://";

// Make your request
const result = await Wized.requests.execute('YOUR_API_REQUEST');
console.log(result);

// Hide spinner after request completes
window.despia = "spinneroff://";
            
// ---------- NORDCRAFT / TODDLE ---------- 
// For Nordcraft / Toddle - use spinner with action events
// Show spinner
window.despia = "spinneron://";

// Trigger your action
ctx.triggerActionEvent("yourActionEvent", {
    param1: value1,
    param2: value2
});

// Hide spinner when the action completes (in your action event handler)
window.despia = "spinneroff://";

Data Structure

The Loading Spinner SDK doesn't return any data structure as it's a visual UI element.

Best Practices

User Experience

• Only show spinners for operations that take longer than 300ms

• Always hide the spinner when operations complete, even if they result in an error

• Consider using the spinner for initial app loading, data fetching, and form submissions

Error Handling

• Implement try/catch blocks to ensure spinner is dismissed even when operations fail

• Set timeouts to hide spinner if operations take too long

• Provide appropriate error messaging to users after hiding the spinner

Performance

• Use the spinner for operations that block the UI

• Consider using progress indicators instead of spinners for operations with known progress

• Test spinner behavior on various device speeds to ensure good user experience

Complete Implementation Example

Here's a complete example showing how to use the Loading Spinner SDK during an API call:

Copy// Function to fetch data with loading spinner
async function fetchDataWithSpinner() {
  try {
    // Show the loading spinner
    window.despia = "spinneron://";
    
    // Set a timeout to hide spinner if operation takes too long
    const timeoutId = setTimeout(() => {
      window.despia = "spinneroff://";
      alert('Operation timed out. Please try again.');
    }, 10000); // 10 second timeout
    
    // Perform the fetch operation
    const response = await fetch('https://api.example.com/data');
    
    // Clear the timeout as operation completed
    clearTimeout(timeoutId);
    
    // Process the response
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    
    // Process the data
    updateUIWithData(data);
    
    // Hide the spinner
    window.despia = "spinneroff://";
    
    return data;
  } catch (error) {
    // Handle any errors
    console.error('Fetch error:', error);
    
    // Hide the spinner even if there was an error
    window.despia = "spinneroff://";
    
    // Show error to user
    showErrorMessage(error.message);
    
    throw error; // Re-throw to allow caller to handle
  }
}

// Example usage
document.getElementById('fetchButton').addEventListener('click', () => {
  fetchDataWithSpinner()
    .then(data => console.log('Data fetched successfully:', data))
    .catch(error => console.log('Error in main handler:', error));
});

Troubleshooting

Common Issues

Spinner Doesn't Appear

• Check that "spinneron://" is spelled correctly

• Ensure your app has the necessary permissions

Spinner Doesn't Disappear

• Verify that "spinneroff://" is being called in all code paths (including error handlers)

• Check for uncaught exceptions that might prevent the spinner from being hidden

• Implement timeout fallbacks to ensure spinner is hidden even if operations fail

Visual Inconsistencies

• Test on multiple device types to ensure consistent appearance

• Verify that your app isn't applying custom styles that might interfere with the spinner

• Check that the device's accessibility settings aren't affecting the spinner's appearance