custom_ui/frontend/documentation/SIMPLE_API_TOAST.md

Simple API Error Handling with PrimeVue Toast

This guide shows how to implement clean, simple error handling using PrimeVue Toast instead of complex custom notification components.

Overview

The simplified approach provides:

• Automatic error toasts using PrimeVue Toast
• Loading state management with component-specific tracking
• Success notifications for create/update operations
• Retry logic with exponential backoff
• Clean error storage for debugging and component-specific error handling

Key Files

1. PrimeVue Notification Store

File: /src/stores/notifications-primevue.js

import { ref } from "vue";
import { defineStore } from "pinia";

export const useNotificationStore = defineStore(
  "notifications-primevue",
  () => {
    // Toast instance reference
    const toastInstance = ref(null);

    // Set the toast instance (called from App.vue)
    const setToastInstance = (toast) => {
      toastInstance.value = toast;
    };

    // Convenience methods for different toast types
    const addSuccess = (message, life = 4000) => {
      if (toastInstance.value) {
        toastInstance.value.add({
          severity: "success",
          summary: "Success",
          detail: message,
          life,
        });
      }
    };

    // ... other methods
  },
);

2. Enhanced API Wrapper

File: /src/api-toast.js

Provides a wrapper around your existing API calls with automatic:

• Error handling and toast notifications
• Loading state management
• Component-specific error tracking
• Retry logic
• Success messages

// Simple usage - automatic error toasts
try {
  const result = await ApiWithToast.getClientStatusCounts();
  // Success - data loaded
} catch (error) {
  // Error toast automatically shown
}

// Create operations with success toasts
await ApiWithToast.createClient(formData);
// Shows: "Client created successfully!"

Usage in Components

1. Basic Setup

In your component:

<script setup>
import ApiWithToast from "@/api-toast";
import { useErrorStore } from "@/stores/errors";
import { useLoadingStore } from "@/stores/loading";

const errorStore = useErrorStore();
const loadingStore = useLoadingStore();

// Simple API call
const loadData = async () => {
  try {
    const result = await ApiWithToast.getPaginatedClientDetails(
      pagination,
      filters,
      [],
    );
    // Handle success
  } catch (error) {
    // Error toast shown automatically
    // Component error stored automatically
  }
};
</script>

2. Loading States

The API wrapper automatically manages loading states:

<template>
  <Button
    @click="loadClients"
    :loading="loadingStore.isComponentLoading('clients')"
    label="Load Clients"
  />
</template>

3. Component-Specific Errors

Access errors for debugging or custom handling:

<template>
  <div v-if="errorStore.getComponentError('clients')" class="error-info">
    Error: {{ errorStore.getComponentError("clients").message }}
  </div>
</template>

App.vue Integration

Ensure your App.vue includes the Toast component and connects it to the store:

<template>
  <div id="app">
    <!-- Your app content -->
    <router-view />

    <!-- PrimeVue Toast for notifications -->
    <Toast ref="toast" />
  </div>
</template>

<script setup>
import { ref, onMounted } from "vue";
import Toast from "primevue/toast";
import { useNotificationStore } from "@/stores/notifications-primevue";

const toast = ref();
const notificationStore = useNotificationStore();

onMounted(() => {
  // Connect toast instance to the store
  notificationStore.setToastInstance(toast.value);
});
</script>

API Wrapper Methods

Convenience Methods

Pre-configured methods for common operations:

// Data fetching (no success toast)
await ApiWithToast.getClientStatusCounts();
await ApiWithToast.getPaginatedClientDetails(pagination, filters, sorting);
await ApiWithToast.getPaginatedJobDetails(pagination, filters, sorting);
await ApiWithToast.getPaginatedWarrantyData(pagination, filters, sorting);

// Create operations (success toast included)
await ApiWithToast.createClient(clientData);

// Utility operations (with retry logic)
await ApiWithToast.getCityStateByZip(zipcode);

Custom API Calls

For custom operations:

await ApiWithToast.makeApiCall(() => yourApiFunction(), {
  componentName: "myComponent",
  showSuccessToast: true,
  successMessage: "Operation completed!",
  showErrorToast: true,
  customErrorMessage: "Custom error message",
  retryCount: 3,
  retryDelay: 1000,
  showLoading: true,
  loadingMessage: "Processing...",
});

Configuration Options

Option	Type	Default	Description
componentName	string	null	Component identifier for error/loading tracking
showErrorToast	boolean	true	Show error toast on failure
showSuccessToast	boolean	false	Show success toast on completion
showLoading	boolean	true	Show loading indicator
loadingMessage	string	'Loading...'	Loading message to display
successMessage	string	null	Success message for toast
customErrorMessage	string	null	Override error message
retryCount	number	0	Number of retry attempts
retryDelay	number	1000	Delay between retries (ms)
operationKey	string	auto-generated	Unique identifier for operation

Demo Pages

1. Simple API Demo

URL: /dev/simple-api-demo

Shows practical usage with real API calls:

• Loading client data
• Creating test clients
• Error handling
• Retry logic

2. PrimeVue Toast Demo

URL: /dev/toast-demo

Demonstrates Toast types and error store integration:

• Different toast severities
• Error store testing
• API simulation

Migration from Custom Notifications

Old Approach (Custom NotificationDisplay)

<!-- Complex setup needed -->
<NotificationDisplay />

<script setup>
import { useNotificationStore } from "@/stores/notifications";
// Manual notification management
</script>

New Approach (PrimeVue Toast)

<!-- Just use the API wrapper -->
<script setup>
import ApiWithToast from "@/api-toast";
// Automatic toast notifications
</script>

Benefits

1. Consistency: Uses PrimeVue components throughout
2. Simplicity: No custom notification components needed
3. Automatic: Error handling happens automatically
4. Flexible: Easy to customize per operation
5. Maintainable: Centralized error handling logic
6. Type Safety: Clear API with documented options

Testing

Test the implementation by:

1. Visit /dev/simple-api-demo
2. Try different operations:
   • Load Clients (success case)
   • Create Test Client (success with toast)
   • Test Error (error toast)
   • Test Retry (retry logic demonstration)

The toasts will appear in the top-right corner using PrimeVue's default styling.

Next Steps

1. Replace existing API calls with ApiWithToast methods
2. Remove custom notification components
3. Update components to use the simplified error handling
4. Test across all your existing workflows

This approach provides cleaner, more maintainable error handling while leveraging your existing PrimeVue setup.