State Manager

The store variable is an instance of the StateManager class. It provides a robust and efficient way to manage application state, including initialization, updates, state change listeners, backend synchronization, and session persistence using local storage. The singleton pattern ensures that only one instance of the state manager exists throughout the application, maintaining a centralized state management system.

Constructor

The constructor initializes the StateManager with an optional initial state. It prepares the state management system by setting up an internal state and a list of listeners for state changes.

  • Parameters: initialState - An optional initial state object for the StateManager. Defaults to an empty object if not provided.

Methods

getInstance(initialState)

Ensures a singleton instance of the StateManager. Returns an existing instance or creates a new one with the given initial state and loads any persisted state.

  • Parameters: initialState - Optional object for the initial state. Used only for the first instance.
  • Returns: The StateManager instance.

setState(update, syncWithBackend)

Updates the state, notifies listeners, persists the updated state to local storage, and optionally synchronizes with the backend.

  • Parameters:
    • update - Object containing updates to merge into the current state.
    • syncWithBackend - Boolean indicating whether to sync with the backend. Defaults to false.

subscribe(listener)

Subscribes a listener to state changes and immediately invokes it with the current state. Returns a function to unsubscribe the listener.

  • Parameters: listener - Function to call on state updates.
  • Returns: Function to unsubscribe the listener.

saveState()

Persists the current state to local storage for continuity across sessions.

loadState()

Loads the state from local storage and updates the internal state. Invoked automatically during instance creation.

resetState(id, syncWithBackend)

Resets the state for a specific id, or clears the entire state if no id is provided. Optionally synchronizes with the backend.

  • With id: Resets only the state associated with the provided key.
  • Without id: Clears the entire state and removes it from local storage.

This is useful for scenarios such as user logouts (clear entire state) or refreshing specific parts of the state dynamically.

State Management for UI Components

This section illustrates how the StateManager class can be applied to manage and persist the state of UI components, such as sidebar visibility and dropdown states, across page reloads. The example demonstrates how to integrate state management into UI interactions to enhance user experience by maintaining consistent UI states across sessions.

Overview

Proper management of UI component states, like a sidebar's open/close status or the expansion state of dropdown menus, significantly improves user experience by ensuring UI consistency. The following example showcases the use of StateManager to achieve this goal efficiently.

Your First Store

To create a new store instance, you can use the global store variable, which is available throughout the application. The following code snippet demonstrates how to create a new store instance with an initial state and subscribe to state changes. To observe the changes, open your developer console, navigate to the Application tab, and look for the key appState_59E13 in the local storage. This key represents the store's state saved in the local storage. 

<button onclick="toggleSidebar" class="p-2 bg-blue-500 text-white rounded-sm">
    Toggle Sidebar
</button>

<script>
    function toggleSidebar() {
        store.setState({
            sidebarOpen: !store.state.sidebarOpen
        });
    }
</script>

Synchronize State with Backend

To synchronize the state with the backend, you can use the syncWithBackend parameter in the setState method. This parameter ensures that any state changes are sent to the backend for persistence. The following code snippet demonstrates how to update the state and synchronize it with the backend. This is useful for scenarios where you need to keep the server-side state in sync with the client-side state.

After clicking the button, refresh the page. The sidebarOpen state will display the value stored in the local storage key appState_59E13, now reflected by PHP code. To retrieve the local storage value, use Request::$localStorage->nameOfTheKey, where nameOfTheKey is the key containing the value of appState_59E13. This value will be synchronized with the backend. Always remember to pass true to store.setState({sidebarOpen: !store.state.sidebarOpen}, true); to ensure synchronization with the backend.

<?php

use Lib\Request;

$sidebarOpen = Request::$localStorage->sidebarOpen ?? false;

?>

<div class="w-screen h-screen grid place-items-center">
    <div class="flex flex-col gap-2">
        <span>sidebarOpen: <?= $sidebarOpen ?></span>
        <button onclick="toggleSidebar" class="p-2 bg-blue-500 text-white rounded-sm">
            Toggle Sidebar
        </button>
    </div>
</div>

<script>
    function toggleSidebar() {
        store.setState({
            sidebarOpen: !store.state.sidebarOpen
        }, true);
    }
</script>

Open and Close Sidebar

<div class="relative z-50">
        <button id="aside-button" class="p-2 bg-blue-500 text-white rounded-sm fixed top-4 left-4">
            Toggle Sidebar
        </button>
    </div>
    <aside class="fixed top-0 left-0 w-64 h-full bg-gray-100 shadow-sm transform -translate-x-full transition-transform z-40">
        <div class="p-4">This is the sidebar content.</div>
    </aside>
    
    <script>
        document.addEventListener('PPBodyLoaded', () => {
            const aside = document.querySelector('aside');
            const button = document.querySelector('#aside-button');

            // Initialize sidebar state on page load
            if (store.state.sidebarOpen) {
                aside.classList.remove('-translate-x-full');
            } else {
                aside.classList.add('-translate-x-full');
            }

            // Button click event listener to toggle sidebar
            button.addEventListener('click', () => {
                store.setState({
                    sidebarOpen: !store.state.sidebarOpen
                });
                aside.classList.toggle('-translate-x-full', !store.state.sidebarOpen);
            });
        });
    </script>

Managing Dropdown States

<div class="relative z-50">
      <button id="dropdown-button" class="p-2 bg-blue-500 text-white rounded-sm">
          Toggle Dropdown
      </button>
      <div id="dropdown-menu" class="absolute w-48 bg-white border border-gray-200 shadow-sm hidden">
          <ul class="py-2">
              <li class="px-4 py-2 hover:bg-gray-100 cursor-pointer">Option 1</li>
              <li class="px-4 py-2 hover:bg-gray-100 cursor-pointer">Option 2</li>
              <li class="px-4 py-2 hover:bg-gray-100 cursor-pointer">Option 3</li>
          </ul>
      </div>
  </div>
  
  <script>
      document.addEventListener('PHPBodyLoaded', () => {
        const dropdownButton = document.querySelector('#dropdown-button');
        const dropdownMenu = document.querySelector('#dropdown-menu');
    
        // Initialize dropdown state on page load
        if (store.state.dropdownOpen) {
            dropdownMenu.classList.remove('hidden');
            dropdownMenu.classList.add('block');
        } else {
            dropdownMenu.classList.remove('block');
            dropdownMenu.classList.add('hidden');
        }
    
        // Button click event listener to toggle dropdown
        dropdownButton.addEventListener('click', () => {
            store.setState({
                dropdownOpen: !store.state.dropdownOpen
            });
    
            if (store.state.dropdownOpen) {
                dropdownMenu.classList.remove('hidden');
                dropdownMenu.classList.add('block');
            } else {
                dropdownMenu.classList.remove('block');
                dropdownMenu.classList.add('hidden');
            }
        });
    
        // Close dropdown if clicking outside
        document.addEventListener('click', (event) => {
            if (!dropdownButton.contains(event.target) && !dropdownMenu.contains(event.target)) {
                store.setState({
                    dropdownOpen: false
                });
                dropdownMenu.classList.remove('block');
                dropdownMenu.classList.add('hidden');
            }
        });
      });
  </script>

Persisting State Across Sessions

The examples above demonstrate effective strategies for saving and restoring UI component states using the StateManager. This approach ensures that the sidebar's visibility and the state of dropdown menus are consistent across page reloads, thereby providing a seamless and engaging user experience.

Conclusion

Leveraging the StateManager for UI state management enables developers to create more interactive and user-friendly web applications. By persisting UI states, applications can maintain user context and preferences across sessions, enhancing the overall usability and satisfaction.