Fireline NPM | npm.io

FireLine

FireLine is a powerful Alpine.js plugin that enhances your web applications with advanced reactivity, seamless integration, and features like server-side rendering of Alpine.js components, form handling, and a robust router.

Features

Global reactive state management via window.FireLine.settings.
Intercepts links and forms for dynamic client-side routing.
Directives:
- x-navigate: Enables dynamic routing using the built-in diffAndPatch algorithm.
- x-submit: Handles form submissions with customizable responses.
Server-side rendering integration for updated content.
Customizable plugin settings.
Automatic event triggers for lifecycle management (fireStart, fireEnd, fireError).
Skip Auto Interception by adding native in anchor tag and form element.

Installation

# Install
npm install fireline

# Setup
import FireLine from 'fireline'
import Alpine from 'alpinejs'

Alpine.plugin(FireLine)

window.Alpine = Alpine

Alpine.start()

or Include the plugin in your project by adding the built file to your HTML:

<!-- Alpine Plugins -->
<script src="https://cdn.jsdelivr.net/npm/fireline@1.x.x/dist/cdn.min.js"></script>
 
<!-- Alpine Core -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>

Getting Started

Configuration

FireLine is globally configurable using the window.FireLine.settings object.

Default Settings

window.FireLine.settings = {
    targetEl: '#app > div', // The element to replace with loaded content
    timeout: 30, // Timeout for the loading state in seconds
    interceptLinks: true, // Enable link interception for SPA routing
    interceptForms: true, // Enable form interception for SPA form submissions
};

To update a setting, simply modify it before initializing Alpine.js:

Example

<div id="app">
    <!-- Element to be replaced from here -->
    <div>
        <a x-navigate href="/about">Go to About</a>
        <form x-submit action="/api/submit" method="POST">
            <input type="text" name="email" placeholder="Enter your email" />
            <button type="submit">Submit</button>
        </form>
    </div>
    <!-- Element to be replaced to here -->
</div>
<script>
    document.addEventListener('alpine:init', () => {
        // Customize Settings
        window.FireLine.settings.targetEl = '#app > div';
        window.FireLine.settings.timeout = 40;
        window.FireLine.settings.interceptLinks = false;
        window.FireLine.settings.interceptForms = false;
    });
</script>

NOTE: every html response should have only one root laval element.

Directives

x-navigate

The x-navigate directive dynamically loads and renders content:

<a x-navigate href="/new-page">Navigate to New Page</a>

Uses diffAndPatch for DOM updates.
Ensure Alpine short attributes (e.g., @click, @input) are replaced with their full form (e.g., x-on:click, x-on:input).

Server Response Handling

The response object can include:

title: (Optional) the title to update the document.
html: (Required) the router response to be rendered.

x-submit

Handles form submissions dynamically with server responses:

<form x-submit action="/submit-form" method="POST">
    <!-- Optional: Form Alert -->
    <div status="success" style="color:green"></div>
    <div status="error" style="color:red"></div>
    
    <input type="text" name="name" placeholder="Enter your name" />
    <button type="submit">Submit</button>
</form>

Server Response Handling The response object can include:

status and message: Shows an alert under the form.
html and title: Renders new HTML content using diffAndPatch.
redirect or navigate: Redirects or navigates to a new route.

`$fire` Magic Property

FireLine introduces the $fire magic property, providing a powerful and intuitive way to interact with the router and manage navigation, loading states, and server-side form submissions directly in your Alpine.js components.

Available Properties and Methods

$fire.current: The current URL path.
$fire.loading: Boolean indicating whether the router is currently loading.
$fire.navigate(url): Navigates to the specified URL.
$fire.reload(): Reloads the current URL.
$fire.replaceHtml(html): Replaces the router content with the provided HTML.
$fire.formSubmit(formEl): Submits a form to the server and handles the response.

Example Usage

Highlight Active Links

<a :class="$fire.current == '/' && 'text-green-600'" href="/">Home</a>
<a :class="$fire.current.startsWith('/about') && 'text-green-600'" href="/about">About</a>

Navigation Buttons

<button x-on:click="$fire.navigate('/dashboard')" class="btn">Go to Dashboard</button>
<button x-on:click="$fire.reload()" class="btn">Reload Page</button>

Custom Content Replacement

<div id="app">
    <div>
        <button x-on:click="$fire.replaceHtml('<div><h1>Welcome to FireLine!</h1></div>')" class="btn">
            Update Content
        </button>
    </div>
</div>

Note: In replaceHtml function the input Html should contain only one root laval element.

Server-Side Form Submission

<form x-data x-on:submit="$fire.formSubmit($el)">
    <input type="text" name="username" placeholder="Enter username" required>
    <button type="submit" class="btn">Submit</button>
</form>

Notes

Use $fire.navigate(url) to programmatically navigate between pages.
When using server-side form submission, make sure your form's response includes one of the following properties:
- status and message: Displays an alert under the form.
- html and title: Updates the content via replaceHtml.
- redirect or navigate: Redirects or navigates to a specific route.
Ensure Alpine.js shorthand attributes (e.g., @click) are replaced with full syntax (x-on:click) when using the replaceHtml function to avoid compatibility issues.

The $fire magic property simplifies complex routing and state management, making it easier to build dynamic and reactive Alpine.js applications with FireLine.

Tips for Usage

Use Full Attribute Names: Replace Alpine short attributes (@click, @input) with full ones (x-on:click, x-on:input) to avoid issues with the dom rendering.

Avoid Mixed Bind Attributes: If using x-bind:class, x-bind:style, etc do not include generic attributes (class, style, etc) to prevent conflicts. Example:

<!-- Avoid this -->
<div class="bg-red-500" x-bind:class="isActive ? 'text-white' : 'text-gray-500'"></div>

<!-- Recommended -->
<div x-bind:class="isActive ? 'bg-red-500 text-white' : 'bg-red-500 text-gray-500'"></div>