Micro-framework for Fluid User Experience

Flux is a minimalist JavaScript library that's shipped by default with WebEngine.

Its purpose is to give server-rendered applications a fluid user experience: instead of every link click and form submission causing a harsh full-page refresh, navigation and updates feel continuous, more like an SPA where the user never really leaves the page.

The difference is that your application still uses the same straightforward server-rendered code, so it stays readable and predictable, while Flux adds the client-side layer for smooth updates without requiring you to write any JavaScript yourself.

Read the documentation.

Behat browser tests

This repository includes Behat end-to-end tests for the examples in example/.

Install PHP dependencies with:

composer install

Run the suite locally with:

composer behat

Feature files live in test/behat/*.feature. The local wrapper at test/behat/behat-bin serves the repository root with the PHP built-in server, launches a local headless Chrome or Chromium instance, and then runs vendor/bin/behat.

Local requirements:

• PHP dependencies installed with composer install
• A local Chrome or Chromium binary available on PATH, or CHROME_BIN set explicitly

PhpStorm settings:

• Behat executable: test/behat/phpstorm-behat-bin
• Configuration file: behat.yml

Useful overrides:

• CHROME_BIN=/path/to/chrome composer behat
• BEHAT_APP_PORT=8080 composer behat
• BEHAT_CHROME_PORT=9333 composer behat

To use Flux, convert a "regular" HTML form into a flux form by adding the data-flux attribute:

<form method="post" data-flux>
	<label>
		<span>Your name</span>
		<input name="name" required />
	</label>
	<label>
		<span>Your email address</span>
		<input name="email" type="email" required />
	</label>
	<button name="do" value="submit">Submit</button>
</form>

When the above form submits, because it has been marked with the data-flux attribute, the default submit behaviour will be suppressed, and a background fetch will be emitted instead, submitting the POST data in the background. When the fetch completes, the default behaviour is to replace the form with the form's counterpart on the new HTML document (after submitting the page), but other behaviours can be configured.

Flux also supports polling-based live regions:

<time data-flux="live">12:00:00</time>
<div data-flux="live-inner"><strong>Only this content is replaced.</strong></div>

data-flux="live" is shorthand for data-flux="live-outer". If one or more live regions exist on the page, Flux performs a single background GET request every second against the current page URL and applies only the live updates from the returned HTML.

Flux can also turn a server-ordered form into a drag handle:

<ul data-flux-drag-parent="todo" data-flux-drag-handle="Move card">
	<li data-flux="drag-order">
		<form method="post">
			<input type="hidden" name="id" value="1" />
			<input type="hidden" name="parent" value="todo" />
			<input type="number" name="order" />
			<button name="do" value="move">Move</button>
		</form>
		<span>Write the tests</span>
	</li>
</ul>

order is filled with the zero-based position before submit. When an optional parent input is present, Flux also fills it from the destination container's data-flux-drag-parent value, which allows Kanban-style moves while keeping the server-side action as a plain form submission.

Use data-flux-drag-handle on the draggable item or its parent container to change the generated handle text. If it is omitted, the handle text is Drag.

Drag ordering can be nested: the board can sort list containers, and each list can sort its own cards. Flux uses horizontal ordering when sortable siblings are laid out side by side and vertical ordering for normal lists.

Limitations compared to other libraries

Flux is designed as a progressive enhancement tool that encourages plain HTTP techniques. Your web applications should function fully even without any JavaScript or CSS, ensuring simplicity and accessibility. This approach simplifies development by focusing on straightforward, reliable techniques, making the entire development experience more manageable.

This design decision leads to several limitations compared to other libraries:

• GET and POST are the only methods available to you as a web developer. This library doesn't change that.
• Flux is only triggered by actions like clicking a link or submitting a form. While forms can update in the background and elements can refresh automatically, all Flux actions are powered by server-side responses tied to links or buttons, which can be hidden by Flux for better usability.
• Fetched page responses are expected to be full-page responses by default. Partial page renders are not the norm and go against the principles of plain HTTP usage.
• State management is not included, as HTTP is a stateless protocol. Any state must be managed on the server side, similar to how it would be handled without client-side code.
• Client-side routing is not supported. Features like dynamic routes, code-splitting, or navigation guards must be handled entirely on the server.
• WebSocket and Server-Sent Events are not supported. Live updates with data-flux="live" rely on regular GET requests with polling.

Proudly sponsored by

JetBrains Open Source sponsorship program