{"id":21422155,"url":"https://github.com/nolanus/ngx-multi-window","last_synced_at":"2025-07-05T17:08:53.485Z","repository":{"id":38197706,"uuid":"89872606","full_name":"Nolanus/ngx-multi-window","owner":"Nolanus","description":"📬 Pull-based cross-window communication for multi-window angular apps","archived":false,"fork":false,"pushed_at":"2023-10-03T23:05:24.000Z","size":5534,"stargazers_count":58,"open_issues_count":37,"forks_count":16,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-06T01:32:28.790Z","etag":null,"topics":["angular","angular2","multi-window","multiwindow"],"latest_commit_sha":null,"homepage":"https://nolanus.github.io/ngx-multi-window/","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/Nolanus.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-04-30T19:37:06.000Z","updated_at":"2024-05-25T05:56:54.000Z","dependencies_parsed_at":"2024-06-18T21:35:13.088Z","dependency_job_id":"ced05934-4b6f-4ff2-ada9-0e88bef45a7f","html_url":"https://github.com/Nolanus/ngx-multi-window","commit_stats":{"total_commits":101,"total_committers":4,"mean_commits":25.25,"dds":"0.14851485148514854","last_synced_commit":"8bc5e06954234a031977040490d37ec02d537c51"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nolanus%2Fngx-multi-window","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nolanus%2Fngx-multi-window/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nolanus%2Fngx-multi-window/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nolanus%2Fngx-multi-window/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nolanus","download_url":"https://codeload.github.com/Nolanus/ngx-multi-window/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230423563,"owners_count":18223435,"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":["angular","angular2","multi-window","multiwindow"],"created_at":"2024-11-22T20:46:03.142Z","updated_at":"2024-12-19T11:12:30.415Z","avatar_url":"https://github.com/Nolanus.png","language":"TypeScript","readme":"# ngx-multi-window [![npm version](https://img.shields.io/npm/v/ngx-multi-window.svg?style=flat)](https://www.npmjs.com/package/ngx-multi-window) [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT)\n\nPull-based cross-window communication for multi-window angular applications\n\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/b175dcd8585a42bdbdb9c1ee2a313b3b)](https://www.codacy.com/app/sebastian-fuss/ngx-multi-window?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=Nolanus/ngx-multi-window\u0026amp;utm_campaign=Badge_Grade)\n\n## Features\n\n- Send messages between different tabs/windows that are running the angular app\n- Message receive notification for sending tab/window\n- Automatic detection/registration of new tabs/windows\n\n## Setup\n\nFirst you need to install the npm module:\n```sh\nnpm install ngx-multi-window --save\n```\n\nFor older angular versions you may install previous versions of this library:\n\n| ngx-multi-window version | compatible angular version |\n|--------------------------|----------------------------|\n| `0.6.1`                  | `16`                       |\n| `0.6`                    | `15`                       |\n| `0.5`                    | `14`                       |\n| `0.4.1`                  | `8 - 13`                   |\n| `0.3.2`                  | `7`                        |\n| `0.2.4`                  | `6`                        |\n\nThen add the `MultiWindowModule` to the imports array of your application module:\n\n```typescript\nimport {MultiWindowModule} from 'ngx-multi-window';\n\n@NgModule({\n    imports: [\n        /* Other imports here */\n        MultiWindowModule\n        ]\n})\nexport class AppModule {\n}\n```\n\nFinally, you need to specify how your application should load the ngx-multi-window library:\n\n## Usage\n\nInject the `MultiWindowService` into your component or service.\n\n```typescript\nimport {MultiWindowService} from 'ngx-multi-window';\n\nexport class AppComponent {\n    constructor(private multiWindowService: MultiWindowService) {\n        // use the service \n    }\n}   \n```\n\n### Configuration\n\nYou may inject a custom `MultiWindowConfig` object when importing the `MultiWindowModule` into your application.\n\n```typescript\n@NgModule({\n    imports: [\n       ...\n       MultiWindowModule.forRoot({ heartbeat: 542 })\n     ],\n  })\n```\n\nCheck the description of the [MultiWindowConfig interface](https://github.com/Nolanus/ngx-multi-window/blob/master/projects/ngx-multi-window/src/lib/types/multi-window.config.ts) properties for options.\nThe [default options](https://github.com/Nolanus/ngx-multi-window/blob/master/projects/ngx-multi-window/src/lib/providers/config.provider.ts#L6) are\n```typescript\n{\n  keyPrefix: 'ngxmw_',\n  heartbeat: 1000,\n  newWindowScan: 5000,\n  messageTimeout: 10000,\n  windowTimeout: 15000,\n  windowSaveStrategy: WindowSaveStrategy.NONE,\n}\n```\n\n### Window ID and name\n\nEvery window has a unique, unchangeable id which can be accessed via `multiWindowService.id`.\nIn addition to that every window as a changeable name which can be get/set \nvia `multiWindowService.name`.\n\n### Receive messages\n\nReceive messages addressed to the current window by subscribing to the observable returned from\n`multiWindowService.onMessages()`:\n\n```typescript\nimport { MultiWindowService, Message } from 'ngx-multi-window';\n\nclass App {\n    constructor(private multiWindowService: MultiWindowService) {\n        multiWindowService.onMessage().subscribe((value: Message) =\u003e {\n          console.log('Received a message from ' + value.senderId + ': ' + value.data);\n        });\n    } \n}\n```\n\n### Send messages\n\nSend a message by calling `multiWindowService.sendMessage()`:\n\n```typescript\nimport { MultiWindowService, WindowData, Message } from 'ngx-multi-window';\n\nclass App {\n    constructor(private multiWindowService: MultiWindowService) {\n        const recipientId: string; // TODO\n        const message: string; // TODO\n        multiWindowService.sendMessage(recipientId, 'customEvent', message).subscribe(\n          (messageId: string) =\u003e {\n            console.log('Message send, ID is ' + messageId);\n          },\n          (error) =\u003e {\n            console.log('Message sending failed, error: ' + error);\n          },\n          () =\u003e {\n            console.log('Message successfully delivered');\n          });\n    }\n}\n```\nThe message returns an observable which will resolve with a message id once the message has been send (= written to local storage).\nThe receiving window will retrieve the message and respond with a `MessageType.MESSAGE_RECEIVED` typed message. \nThe sending window/app will be informed by finishing the observable.\n\nIn case no `MessageType.MESSAGE_RECEIVED` message has been received by the sending window \nwithin a certain time limit (`MultiWindowConfig.messageTimeout`, default is 10s) \nthe message submission will be canceled. The observable will be rejected and the \ninitial message will be removed from the current windows postbox. \n\n### Other windows\n\nTo get the names and ids of other window/app instances the `MultiWindowService` offers two methods:\n\n`multiWindowService.onWindows()` returns an observable to subscribe to in case you require periodic updates of the \nfellow windows. The observable will emit a new value every time the local storage has been scanned for the windows. \nThis by default happens every 5 seconds (`MultiWindowConfig.newWindowScan`).\n\nUse `multiWindowService.getKnownWindows` to return an array of `WindowData`.\n\n### New windows\n\nNo special handling is necessary to open new windows. Every new window/app will register itself \nby writing to its key in the local storage. Existing windows will identify new windows \nafter `MultiWindowConfig.newWindowScan` at the latest.\n\nThe `MultiWindowService` offers a convenience method `newWindow()` which provides details for the \nnew window's start url. If used the returned observable can be utilized to get notified \nonce the new window is ready to consume/receive message. \n\n### Save window name\n\nThe library comes with a mechanism to save the window id using the browser's `window.name` property. This \nproperty is persisted on page reloads, resulting in the same tab/window running your angular application to keep \nthe ngx-multi-window id even when reloading the page.\nNote: Only the window id is persisted, the customizable window name and messages are kept in the local storage,\nbut are automatically rediscovered by the new window once it starts consuming messages.\n\nTo save the window id, set the respective config property `nameSafeStrategy` to the desired value. Additionally \none needs to call `saveWindow()` function e.g. during window unloading by attaching a `HostListener` in your \nmain AppComponent.\n\n```typescript\n@HostListener('window:unload')\nunloadHandler() {\n  this.multiWindowService.saveWindow();\n}\n```\n\n## Communication strategy\n\nThis library is based on \"pull-based\" communication. Every window periodically checks the local storage for messages addressed to itself.\nFor that reason every window has its own key in the local storage, whose contents/value looks like:\n\n```json\n{\"heartbeat\":1508936270103,\"id\":\"oufi90mui5u5n\",\"name\":\"AppWindow oufi90mui5u5n\",\"messages\":[]}\n```\n\nThe heartbeat is updated every time the window performed a reading check on the other window's local storage keys.\n\nSending message from sender A to recipient B involves the following steps:\n- The sender A writes the initial message (including the text and recipient id of B) into the \"messages\" array located at its own local storage key\n- The recipient window B reads the messages array of the other windows and picks up a message addressed to itself\n- B places a \"MESSAGE_RECEIVED\" message addressed to A in its own messages array\n- A picks up the \"MESSAGE_RECEIVED\" message in B's message array and removes the initial message from its own messages array\n- B identifies that the initial message has been removed from A's messages array and removes the receipt message from its own messages array\n\n![Communication Strategy showcase](communication.gif)\n\n## Example App\n\nThis project contains a demo application that has been adapted to showcase the functionality of ngx-multi-window. \nRun the demo app by checking out that repository and execute the following command in the project root directory:\n\n ```\nnpm install\nng serve\n ```\n \n## TODO\n\n- Tests and cross browser testing\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanus%2Fngx-multi-window","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnolanus%2Fngx-multi-window","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolanus%2Fngx-multi-window/lists"}