Winter CMS AJAX Framework

winter-cms-ajax-readme.md

Winter AJAX Framework

This is some basic documentation on how the Winter CMS AJAX framework currently works.

Headers

Name	Purpose	Values
X-Requested-With	Tells Winter/Laravel/Symfony that the request is an "AJAX Request".	XMLHttpRequest
X-WINTER-REQUEST-HANDLER	Tells Winter which AJAX handler method to use on the controller/component. modules/backend/classes/Controller.php#L435	Component handler: component::onEvent; Generic handler: onEvent (Note: the onAjax handler name will always return null)
X-WINTER-REQUEST-FLASH	Tells Winter that it should respond with flash messages. modules/cms/classes/Controller.php#L764	true | false

Response Data

{
  "result" : {},
  "X_WINTER_REQUEST_PARTIALS": {
    "name": "<div>HTML</div>",
    // ...
  },
  "X_WINTER_REDIRECT": "https://example.com",
  "W_WINTER_ASSETS": {
    "css": [
      // ...
    ],
    "js": [
      // ...
    ],
    "img": [
      // ...
    ],
  },
  "X_WINTER_ERROR_FIELDS": {
    "field": [
      "Validation message.",
      // ...
    ],
    // ...
  },
  "X_WINTER_ERROR_MESSAGE": ""
}

Name	Purpose	JSON Structure Example
result	If your AJAX handler function returned an array, the data will be present under this key.	N/A
X_WINTER_REQUEST_PARTIALS	Contains the contents of the partials to update on the page. modules/backend/classes/Controller.php#L460	{ "myPartial": "<div>...</div>", ... }
X_WINTER_REDIRECT	Contains the URL that the browser should redirect to. modules/backend/classes/Controller.php#L494	"https://example.com"
W_WINTER_ASSETS	Contains the assets that should be injected into the page. modules/backend/classes/Controller.php#L508	{ "css": [ "style.css", ... ], "js": [ "script.js", ... ], "img": [ "image.png", ... ] }
X_WINTER_ERROR_FIELDS	Contains the results of backend field validation. modules/backend/classes/Controller.php#L535	{ "email": [ "The email field must be a valid email address.", ... ] }
X_WINTER_ERROR_MESSAGE	Used in the backend/cms, not relevant for frontend requests. modules/cms/classes/Controller.php#L790

Making a request to the server

When making an AJAX request to Winter, the X-Requested-With header must be set to XMLHttpRequest.

• Winter checks if the request is a POST request made using AJAX, and if the X-WINTER-REQUEST-HANDLER header is set.
  • Laravel checks that header with Request#ajax() (which is an alias of Symfony's Request#isXmlHttpRequest())

Winter CMS will look for a handler function name that matches the one supplied in the header. Once executed, the response is returned to the client.