Core Concept: HTML Attributes Drive Behavior

Here's how it works:

1. Backend (PHP/Uxmal): When generating HTML components (like modals, forms, buttons), Uxmal adds specific data-uxmal-* attributes to the elements. These attributes tell the frontend what the element is and how it might behave.
   data-uxmal-modal="myModalName": Identifies this element as a BOUI modal component named "myModalName". data-uxmal-id="uniqueId123": Gives the component instance a unique ID. data-uxmal-action="fetch": Specifies that this element should perform a 'fetch' action. data-uxmal-action-on="click": Specifies the action should trigger on a 'click' event. data-uxmal-route="api.users.list": Provides the named route for an API call.
2. Frontend (BOUI JavaScript): When the page loads, BOUI's JavaScript scans the HTML document for these data-uxmal-* attributes.
3. Initialization: Based on the attributes found, BOUI automatically:
   • Instantiates Component Classes: If it finds data-uxmal-modal, it creates a new JavaScript UIModal object linked to that HTML element.
   • Attaches Actions: If it finds data-uxmal-action and data-uxmal-action-on, it automatically adds the correct event listener (e.g., a click listener) that will execute the specified action's JavaScript code (e.g., code to perform an API fetch).

This approach minimizes the need for custom JavaScript for common component initialization and interactions.

How to Integrate BOUI

Since BOUI is included as a Composer package (uxmaltech/backoffice-ui), its JavaScript assets reside within the vendor directory.

You need to import the main BOUI entry point into your project's primary JavaScript file (usually resources/js/app.js) before it's compiled by Vite or Mix.

How it Starts: Initialization Flow

When the web page finishes loading (DOMContentLoaded):

1. boui/index.js runs: This is the main entry point (imported via your app.js).
2. Loads Config: Fetches necessary info from the backend (like API routes).
3. Finds Components: Scans the HTML for data-uxmal-* component attributes.
4. Creates JS Objects: For each component found, it creates the corresponding JavaScript object (e.g., UIModal, UIForm).
5. Stores Objects: Registers these new JS objects in a central place called bouiState.
6. Finds Actions: Scans the HTML for data-uxmal-action attributes.
7. Attaches Listeners: Sets up event listeners (click, change, etc.) for elements with actions.
8. Ready: The framework signals it's ready (loaded.boui.app event).

Building Blocks: Components (bouiElement)

• Most interactive elements managed by BOUI have a corresponding JavaScript class (e.g., UIModal, UIButton, UIFormInput).
• These classes usually extend a base class called bouiElement.
• An instance of a component class holds a reference to its HTML element (.el) and provides methods specific to that component (e.g., modal.show(), button.loader(true)).
• Components are automatically instantiated during the initialization phase based on the HTML attributes.

Keeping Track: State Management (bouiState)

• Central Registry: bouiState is the heart of the framework's frontend state. Think of it as a big JavaScript object (using Maps internally) that knows about all the active BOUI component instances on the page.
• Why? Instead of constantly searching the DOM (document.querySelector), you can ask bouiState for a component instance if you know its name or ID.
• Accessing Components: You primarily interact with bouiState through the global boui object:

• Event Bus: bouiState also manages an internal event system (dispatch and on). Components and other parts of the system can communicate without being directly coupled.

Making Things Happen: Actions

• An element like: <button data-uxmal-action-on="click" data-uxmal-action="dispatch" data-uxmal-event-name="user:reload">Reload</button> tells BOUI:
  • "When this button is clicked (action-on="click")..."
  • "...perform the dispatch action (action="dispatch")..."
  • "...dispatching an event named user:reload (event-name="user:reload")."
• BOUI has built-in actions for common tasks like dispatching events (dispatch), fetching data from the API (fetch), submitting forms (submit-form), and running arbitrary JavaScript (javascript).

Talking to the Server: API Interaction

• BOUI provides a streamlined way to make API calls to the backend using named routes defined by the server.
• The bouiState.fetch() method (often accessed via boui.cbq() - Command Bus Query) handles this.

• It automatically uses the correct HTTP method, URL, parameters, and adds necessary headers (CSRF, Auth token) based on the named route configuration fetched during initialization.

Using BOUI in Your Code: The Global boui Object

• BOUI exports a global object (the instance created in boui/index.js). You typically import this into your custom JS files.
• This is your main entry point for interacting with the framework:
  • Get a component instance: boui.get('componentNameOrId').
  • Dispatch an event: boui.dispatch('eventName', { data }).
  • Listen for an event: boui.on('eventName', callback).
  • Make an API call: boui.cbq('routeName', params, payload).
  • Control logging verbosity: boui.logLevel('DEBUG').
• In development mode, boui/index.js assigns this instance to window.boui for easy console access.

Interaction Examples

Key takeaways from examples:

• Import the boui object.
• It's often safest to interact with BOUI after the loaded.boui.app event.
• Use boui.get('component-id') to retrieve the specific JavaScript instance of the component.
• Call methods directly on the retrieved instance (e.g., modalInstance.show(), offcanvasInstance.toggle()).