{"id":19346370,"url":"https://github.com/canjs/can-interrupt","last_synced_at":"2025-04-23T04:36:58.687Z","repository":{"id":57193435,"uuid":"41872041","full_name":"canjs/can-interrupt","owner":"canjs","description":"Pause or cancel changes on a map and route","archived":false,"fork":false,"pushed_at":"2019-06-13T23:13:15.000Z","size":18,"stargazers_count":5,"open_issues_count":5,"forks_count":2,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-17T10:03:26.258Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/can-interrupt","language":"JavaScript","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/canjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-03T16:55:46.000Z","updated_at":"2018-12-28T00:51:43.000Z","dependencies_parsed_at":"2022-09-15T22:30:38.903Z","dependency_job_id":null,"html_url":"https://github.com/canjs/can-interrupt","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canjs%2Fcan-interrupt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canjs%2Fcan-interrupt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canjs%2Fcan-interrupt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/canjs%2Fcan-interrupt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/canjs","download_url":"https://codeload.github.com/canjs/can-interrupt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250372546,"owners_count":21419719,"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":[],"created_at":"2024-11-10T04:09:58.633Z","updated_at":"2025-04-23T04:36:58.431Z","avatar_url":"https://github.com/canjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# can-interrupt\ncan-interrupt allows you to interrupt the setting of a property (or properties) on can.Map in a transaction. One use case \nof this is interrupting the setting of an AppState on route change when a user is attempting to leave a page with \nunsaved changes. By interrupting the setting of the route in a transaction, you can interrupt the application's state\nchange, present the user with a confirmation prompt notifying them of their unsaved changes, and ask them if they \nwant to proceed and lose their changes, or stay on the page and save their changes. In fact, Can Interrupt was designed\nwith this use case in mind. A few examples will illustrate the use of Can Interrupt.\n\n## Using Can Interrupt\nSetting up a can.Map to use Can Interrupt involves the following steps:\n\n1. Bind the can.Map to the `changing` event:\n\n```js\n    \n    myCanMap.bind(\"changing\", function (event) {\n           //See examples below for working with the event object methods\n    }); \n    \n```\n\nThe work you will do when Can Interrupt interrupts the setting of the can.Map will happen here. The `event` object passed\nin to the callback function contains `pause`, `resume`, and `cancel` methods you can use to manage the transaction.\n\n2. If you are not using Can Interrupt with can.route, wrap the changes you want to encapsulate in a can.transaction:\n\n```js\n\n    can.transaction.start();\n    recipe.attr('level', 'easy');\n    recipe.attr('name', 'blah');\n    recipe.attr('type', 'cream');\n    can.transaction.stop();\n\n```\n\nIf you are using Can Interrupt with can.route, you do not need this step. All you need to do is bind the route to the\n`changing` event, as described in step 1, above. Can Interrupt will manage wrapping route changes in a transaction for you.\n\n## Examples\n\n1. Use with a standard can.Map. In this example Can Interrupt inspects the properties being set, and if the \nname property is among the properties being set, it cancels the transaction, and reverts the changes to the\ncan.Map:\n\n```js\n\n    //Define a Recipe can.Map\n    var Recipe = can.Map.extend({\n        define: {\n            name: {\n                value: 'cheese'\n            },\n            level: {\n                value: 'hard'\n            },\n            type: {\n                value: 'dairy'\n            }\n        }\n    });\n    \n    //Create an instance of the Recipe can.Map\n    var recipe = new Recipe();\n\n    recipe.bind(\"changing\", function (event) {\n        var mapProperty = event.args[0];\n        if (mapProperty === 'name') {\n            event.cancel();\n        }\n    });\n\n    //Open a transaction\n    can.transaction.start();\n    //Change properties on the recipe instance\n    recipe.attr('level', 'easy');\n    recipe.removeAttr('name');\n    recipe.attr('type', 'cream');\n    //End the transaction\n    can.transaction.stop();\n\n    //The properties are unchanged\n    //recipe.attr('name') --\u003e 'cheese';\n    //recipe.attr('level') --\u003e 'hard';\n    //recipe.attr('type') --\u003e 'dairy';\n```\n\n2. Use with can.route. This example highlights the use of pausing the transaction to allow for user input.\n\n```js\n\n    can.route.bind(\"changing\", function (event) {\n\n        if(hasUnsavedChanges) {\n\n            event.pause(function () {\n\n                //Add the current path to the browser history\n                var path = can.route.param(can.route.data.serialize(), true);\n                can.route._call(\"setURL\", path, []);\n\n                //Present the user with a confirmation dialog\n                showConfirmationDialog({\n                    text: 'Leaving the page will cause you to lose your unsaved changes. Would you like to continue?',\n                })\n                //The user has chosen to stay on the page, cancel the transaction\n                .then(function cancel (d) {\n                    event.cancel();\n                }, \n                //The user has chosen to leave the page, resume the transaction\n                function proceed (d) {\n                    event.resume();\n                });\n            });\n\n        } else {\n            //There are no unsaved changes, resume the transaction\n            event.resume();\n        }\n\n    });\n\n```\n\n## Methods\n\nCan Interrupt provides the following methods:\n\n### can.transaction\n\n1. `can.transaction.start` Used to begin a transaction set. Once you have called the `start` method, all changes to watched can.Maps will be tracked.  \n2. `can.transaction.stop` Used to end a transaction set. Once you call the `stop` method, the changes to watched can.Maps will either be committed or ignored and no further changes will be tracked.\n\n### can.transaction event object\nWhen you bind a can.Map, or can.route to the `changing` event, your event handler will receive an `event` object. This object has the following methods:\n\n1. `pause` Used to pause the setting of the values of the can.Map until either the `resume` or `cancel` methods have been called.\n2. `resume` Used to resume the committing of changes to the watched can.Map (this will cause your changes to the map to be saved).\n3. `cancel` Used to ignore (or roll back) changes to the watched can.Map (this will prohibit your changes to the map from being saved).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanjs%2Fcan-interrupt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanjs%2Fcan-interrupt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanjs%2Fcan-interrupt/lists"}