{"id":28561207,"url":"https://github.com/zaxbux/winter-request-framework","last_synced_at":"2025-06-10T10:41:24.382Z","repository":{"id":57170332,"uuid":"356945642","full_name":"zaxbux/winter-request-framework","owner":"zaxbux","description":"A TypeScript implementation of the Winter CMS Request Framework.","archived":false,"fork":false,"pushed_at":"2021-04-21T23:28:41.000Z","size":74,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-20T23:19:11.618Z","etag":null,"topics":["ajax","winter-cms","winter-plugin","wintercms"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zaxbux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-11T18:20:02.000Z","updated_at":"2024-08-06T18:50:41.000Z","dependencies_parsed_at":"2022-08-27T12:02:01.654Z","dependency_job_id":null,"html_url":"https://github.com/zaxbux/winter-request-framework","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaxbux%2Fwinter-request-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaxbux%2Fwinter-request-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaxbux%2Fwinter-request-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaxbux%2Fwinter-request-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zaxbux","download_url":"https://codeload.github.com/zaxbux/winter-request-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zaxbux%2Fwinter-request-framework/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259057767,"owners_count":22799222,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ajax","winter-cms","winter-plugin","wintercms"],"created_at":"2025-06-10T10:41:11.893Z","updated_at":"2025-06-10T10:41:24.362Z","avatar_url":"https://github.com/zaxbux.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Winter CMS Request Framework\n\nThis is a modern implementation of the Winter CMS Request library. The original is based on jQuery, which may not be preferable for some developers to use. This library is intended for use on your front end, in themes. Most of the functionality and features have been kept from the original implementation, however it is not meant to replace the framework used in the backend of Winter.\n\nThere are two parts to this library, a really basic implementation for making requests and handling all responses yourself, and an implementation with \"extras\" that simulate the behavior of the original library.\n\n# Breaking Changes\n\n * The data-* attributes that relied on `eval()` have been removed. There are better ways to achieve this functionality.\n * Asset injection isn't supported by default, but you can extend the plugin to accomplish this.\n * Global AJAX events are removed.\n * `$.Deferred()`-style promises are removed.\n * Support for the global object `$.wn.stripeLoadIndicator` is removed.\n\n# Improvements\n\n  * For the `data-request-update` and `data-request-data` attributes, [JSON5](https://github.com/json5/json5) is used to parse that JSON-like syntax used in those attributes.\n  * [Axios](https://github.com/axios/axios) is used to make requests to the server. It takes care of these by default:\n    * Detects the `XSRF-TOKEN` cookie automatically\n    * Uses the `X-XSRF-TOKEN` header automatically (set to the value of the XSRF cookie).\n    * Request/Response content type is `application/json`.\n\n# Installing\n\nTo include the library in your project, install the package. It has been transpiled into CommonJS and ES2020.\n\n```\nnpm i -D @zaxbux/winter-request-framework\n```\n\n# Examples\n\n```javascript\nimport { WinterRequest } from '@zaxbux/winter-request-framework';\n\n// This is the \"extended\" version, which inherits from the \"base\" version.\nimport { WinterRequestExtras } from '@zaxbux/winter-request-framework';\n\nconst form = document.querySelector('#myForm');\n\nconst wnRequest = new WinterRequest(form, 'myComponent::onSubmit', {\n  onSuccess: async (response) =\u003e {\n    console.log(response.data);\n  },\n  \n  // ...\n});\n\nwnRequest.send();\n```\n\n\n# How does the Winter AJAX Framework work?\n\nWinter includes a way to communicate between the server and frontend JavaScript using \"AJAX Handlers\".\n\n## Making a request to the server\n\nWhen making an AJAX request to Winter, the `X-Requested-With` header must be set to `XMLHttpRequest`.\n\n  * [Winter checks if the request is a POST request made using AJAX](https://github.com/wintercms/winter/blob/9654e0e427536bd1c1e3652dc527547c0d7e2d7a/modules/backend/classes/Controller.php#L429), and if the `X-WINTER-REQUEST-HANDLER` header is set.\n    * Laravel checks that header with [`Request#ajax()`](https://github.com/laravel/framework/blob/42102589bc7f7b8533ee1b815ef0cc18017d4e45/src/Illuminate/Http/Request.php#L238) (which is an alias of Symfony's [`Request#isXmlHttpRequest()`](https://github.com/symfony/http-foundation/blob/f60c2e55bebe18bb54c11d1d91c914ddc8d80995/Request.php#L1763))\n\nWinter 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.\n\n### Headers\n\n| Name                        | Purpose | Values\n| --------------------------- | ------- | -------\n| `X-Requested-With`          | Tells Winter/Laravel/Symfony that the request is an \"AJAX Request\". | `XMLHttpRequest`\n| `X-WINTER-REQUEST-HANDLER`  | Tells Winter which AJAX handler method to use on the controller/component. [modules/backend/classes/Controller.php#L435](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/backend/classes/Controller.php#L435) | Component handler: `component::onEvent`; Generic handler: `onEvent` (Note: the `onAjax` handler name will always return null)\n| `X-WINTER-REQUEST-PARTIALS` | Tells Winter which partials to render and return in the response. | Names of partials, separated by the `\u0026` character. E.g. `partial1\u0026partial2\u0026partial3`\n| `X-WINTER-REQUEST-FLASH`    | Tells Winter that it should clear existing flash messages respond with new flash messages. [modules/cms/classes/Controller.php#L764](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/cms/classes/Controller.php#L764) | `true` \\| `false`\n\n### Response Data\n\n```jsonc\n{\n  \"result\" : {},\n  \"X_WINTER_REQUEST_PARTIALS\": {\n    \"name\": \"\u003cdiv\u003eHTML\u003c/div\u003e\",\n    // ...\n  },\n  \"X_WINTER_REDIRECT\": \"https://example.com\",\n  \"W_WINTER_ASSETS\": {\n    \"css\": [\n      // ...\n    ],\n    \"js\": [\n      // ...\n    ],\n    \"img\": [\n      // ...\n    ],\n  },\n  \"X_WINTER_ERROR_FIELDS\": {\n    \"field\": [\n      \"Validation message.\",\n      // ...\n    ],\n    // ...\n  },\n  \"X_WINTER_ERROR_MESSAGE\": \"\"\n}\n```\n\n| Name                        | Purpose | JSON Structure Example\n| --------------------------- | ------- | ----------------------\n| `result`                    | If your AJAX handler function returned an array, the data will be present under this key. | N/A\n| `X_WINTER_REQUEST_PARTIALS` | Contains the contents of the partials to update on the page. [modules/backend/classes/Controller.php#L460](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/backend/classes/Controller.php#L460) | `{ \"myPartial\": \"\u003cdiv\u003e...\u003c/div\u003e\", ... }`\n| `X_WINTER_REDIRECT`         | Contains the URL that the browser should redirect to. [modules/backend/classes/Controller.php#L494](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/backend/classes/Controller.php#L494)        | `\"https://example.com\"`\n| `W_WINTER_ASSETS`           | Contains the assets that should be injected into the page. [modules/backend/classes/Controller.php#L508](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/backend/classes/Controller.php#L508)   | `{ \"css\": [ \"style.css\", ... ], \"js\": [ \"script.js\", ... ], \"img\": [ \"image.png\", ... ] }`\n| `X_WINTER_ERROR_FIELDS`     | Contains the results of backend field validation. [modules/backend/classes/Controller.php#L535](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/backend/classes/Controller.php#L535)            | `{ \"email\": [ \"The email field must be a valid email address.\", ... ] }`\n| `X_WINTER_ERROR_MESSAGE`    | Used in the backend/cms, not relevant for frontend requests. [modules/cms/classes/Controller.php#L790](https://github.com/wintercms/winter/blob/a56d7ec2af948480a2b24971b8118490f14dd042/modules/cms/classes/Controller.php#L790)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaxbux%2Fwinter-request-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaxbux%2Fwinter-request-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaxbux%2Fwinter-request-framework/lists"}