Introducing the new AJAX Framework + Turbo Router

Updates and Announcements
#1

Hello everyone.

We are pleased to announce that included in v3 onwards, October CMS ships with a new AJAX framework that removes the need to include jQuery in your themes. The new framework is a drop-in replacement for the old one and includes ongoing support for both jQuery and Vanilla JS.

Library Components

The AJAX framework library contains four main components:

Component Description
AjaxRequest Includes javascript API with request object.
AjaxFramework Applies data attributes API to the DOM.
AjaxExtras Applies extra AJAX features to the DOM.
AjaxTurbo Applies the PJAX library to the DOM.

It is possible to import the framework as a module for build tools like webpack:

npm install --save octobercms

Then require it in your scripts:

var oc = require('octobercms');

The code for the AJAX Framework is public and can be found at the following GitHub repo:

The Turbo Router

The Turbo Router is an implementation of PJAX (push state and AJAX) that uses complementary techniques to dramatically reduce the amount of JavaScript needed to create modern websites. PJAX is now included in the frontend and backend areas by default and is a step forward in modernizing the platform.

PJAX changes the way the browser interacts with the application and uses a slightly different page lifecycle. Specifically, new events are needed to initialize JavaScript controls and controls should be disposable.

If your website or application is affected by this change, we recommend disabling PJAX by including the following META tag in your webpage layouts.


<head>
    <meta name="turbo-visit-control" content="disable" />
</head>

If there are affected plugins, you may also disable the turbo router in the backend with the backend.turbo_router setting.


// config/backend.php
//
'turbo_router' => false,

Plugin developers can disable PJAX on specific controllers by including the turboVisitControl property.


/**
 * @var bool turboVisitControl forces a reload
 */
public $turboVisitControl = 'disable';

We encourage you to learn more about introducing PJAX support by reading the documentation.

Just One Breaking Change

There is only one significant breaking change to the error function signature. The argument order has changed and this is an intentional break to make the API more consistent. Also - the textStatus (provided by jQuery) has been replaced with the HTTP response code.

Old signature:


success: function(data, textStatus, jqXHR)
complete: function(data, textStatus, jqXHR)
error: function(jqXHR, textStatus, errorThrown)

New signature:


success: function(data, responseCode, xhr)
complete: function(data, responseCode, xhr)
error: function(data, responseCode, xhr)

The method signatures are now consistent across the board.

9 Likes
#2

Hello

I just saw in the v3.0.45 release that:
Moves AJAX framework from jQuery to Vanilla JS

I checked out the topic:
Introducing the new AJAX Framework + Turbo Router

Does this now mean, that jQuery AJAX framework functions are deprecated?

To be concrete. Does this in v3.0.45 still work?

$.request('onSomething', { data: someVar });
1 Like
#3

Hey @mathilde,

Yes, it still works if jQuery is found. The new syntax is:

// jQuery API
$.request('onSomething', { data: someVar });

// Vanilla JS API
oc.ajax('onSomething', { data: someVar });

And for this

// jQuery API
$('.some-element').request('onSomething', { data: someVar });

// Vanilla JS API
oc.request('.some-element', 'onSomething', { data: someVar });
1 Like
#4

This is awesome! Congrats on such a great release @daft!:fire:

4 Likes
#5
#6
#7
#8

Probably a very dumb situation / question here, but I struggle with combining this properly with webpack. I noticed that after re-loading a page via turbo, suddenly the framework extras are not anymore present.

var oc = require(‘octobercms’) gives issues due to webpack not understanding how to handle this file:

ERROR in ./node_modules/octobercms/src/observe/control-base.js 4:24
Module parse failed: Unexpected token (4:24)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
| class ControlBase
| {
>     static proxyCounter = 0;
| 
|     static get shouldLoad() {
 @ ./node_modules/octobercms/src/index.js 15:0-53 25:4-15
 @ ./src/js/app.js
 @ multi ./src/js/app.js ./src/scss/style.scss

Help would be very much appreciated!

#9

You may need to use babel loader