{"id":13808927,"url":"https://github.com/nigrosimone/ng-portal","last_synced_at":"2025-05-14T03:31:48.073Z","repository":{"id":65422160,"uuid":"349718365","full_name":"nigrosimone/ng-portal","owner":"nigrosimone","description":"Component property connection in Angular application wherever they are.","archived":false,"fork":false,"pushed_at":"2024-01-06T20:03:31.000Z","size":3180,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-08-17T05:14:11.713Z","etag":null,"topics":["angular","angular2","decorators","rxjs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ng-portal","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/nigrosimone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"open_collective":"simone-nigro"}},"created_at":"2021-03-20T12:27:17.000Z","updated_at":"2024-02-10T02:33:33.000Z","dependencies_parsed_at":"2024-08-04T01:09:52.637Z","dependency_job_id":null,"html_url":"https://github.com/nigrosimone/ng-portal","commit_stats":{"total_commits":55,"total_committers":1,"mean_commits":55.0,"dds":0.0,"last_synced_commit":"30415b5ce7dff47da2106771c68752f4347c6694"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigrosimone%2Fng-portal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigrosimone%2Fng-portal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigrosimone%2Fng-portal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nigrosimone%2Fng-portal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nigrosimone","download_url":"https://codeload.github.com/nigrosimone/ng-portal/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225273292,"owners_count":17448080,"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","decorators","rxjs"],"created_at":"2024-08-04T01:01:55.264Z","updated_at":"2024-11-19T00:31:13.512Z","avatar_url":"https://github.com/nigrosimone.png","language":"TypeScript","funding_links":["https://opencollective.com/simone-nigro","https://www.paypal.com/paypalme/snwp"],"categories":["Table of contents"],"sub_categories":["Third Party Components"],"readme":"# NgPortal [![Build Status](https://travis-ci.com/nigrosimone/ng-portal.svg?branch=main)](https://travis-ci.com/nigrosimone/ng-portal) [![Coverage Status](https://coveralls.io/repos/github/nigrosimone/ng-portal/badge.svg?branch=main)](https://coveralls.io/github/nigrosimone/ng-portal?branch=main) [![NPM version](https://img.shields.io/npm/v/ng-portal.svg)](https://www.npmjs.com/package/ng-portal)\n\nComponent property connection in Angular application wherever they are.\n\n## Description\n\nSometime there is a need to send data beetween components. A common pattern in Angular is sharing data between a parent component and one or more child components by using the `@Input()` and `@Output()` directives.\nThis pattern works if component are in the same scope. \nIn this example an _output component_ set a property `value` imputed by _input component_, eg:\n\n```ts\nimport { Component } from '@angular/core';\n\n@Component({\n  selector: 'app-component',\n  template: `\u003capp-output (event)=\"value = $event\"\u003e\u003capp-output\u003e\n             \u003capp-input [value]=\"value\"\u003e\u003c/app-input\u003e`,\n})\nexport class AppComponent {\n  value: string;\n}\n```\n\nBut what happen if both component arent in the same scope? A common pattern in this case is propagate `@Input()` and `@Output()` throught the tree of parents/childs component or write a shared service for exhange the data.\n\n`NgPortal` offer a dead simple solution, a new directive `@NgPortal()` that connect two property wherever they are.\n\nIn this example every property called `value` with `@NgPortal()` directive is connected and every changes is propagated wherever, eg.:\n\n```ts\nimport { Component } from '@angular/core';\nimport { ngPortalInput, ngPortalOutput } from 'ng-portal';\n\n@Component({\n  selector: 'app-input',\n  template: `\u003cinput (keyup)=\"value = $event.target['value']\"\u003e`,\n})\nexport class InputComponent {\n  @ngPortalInput() value: string;\n}\n\n@Component({\n  selector: 'app-output',\n  template: `{{ value | async }}`,\n})\nexport class OutputComponent {\n  @ngPortalOutput() value: Observable\u003cstring\u003e;\n}\n```\n\nThere are also mono-directional directive `@NgPortalInput()` and `@NgPortalOutput()` for more control.\n\n\nSee the [stackblitz demo](https://stackblitz.com/edit/demo-ng-portal?file=src%2Fapp%2Fapp.component.ts).\n\n## Features\n\n✅ Two way data binging\u003cbr\u003e\n✅ Mono directional communication\u003cbr\u003e\n✅ Async pipe support\u003cbr\u003e\n✅ NgModel support\u003cbr\u003e\n\n## Get Started\n\n*Step 1*: install `ng-portal`\n\n```bash\nnpm i ng-portal\n```\n\n*Step 2*: Import `NgPortalModule` into your app module, eg.:\n\n```ts\nimport { BrowserModule } from '@angular/platform-browser';\nimport { NgModule } from '@angular/core';\nimport { AppComponent } from './app.component';\n\nimport { NgPortalModule } from 'ng-portal';\n\n@NgModule({\n  declarations: [AppComponent],\n  imports: [\n    BrowserModule,\n    NgPortalModule,\n  ],\n  providers: [],\n  bootstrap: [AppComponent],\n  ],\n})\nexport class AppModule { }\n```\n\n## API\n\nAvailable property decorators (`options` is optional):\n\n - `@ngPortal(options?: NgPortalDecoratorOptions)`: two way communication\n - `@ngPortalInput(options?: NgPortalDecoratorOptions)`: only send changes \n - `@ngPortalOutput(options?: NgPortalDecoratorOptions)`: only receive changes \n\nDecorator options interface:\n\n```ts\nexport interface NgPortalDecoratorOptions {\n  key: string;\n}\n```\n\nFrom default `ngPortal` use property name as the key:\n\n```ts\n@ngPortal() value: string;\n```\n\nis equivalent to:\n\n```ts\n@ngPortal({key: 'value'}) value: string;\n```\n\nand is also equivalent to:\n\n```ts\n@ngPortal({key: 'value'}) whateverYouWant: string;\n```\n\nCommunication ways:\n\n - `@ngPortal()` sends to `@ngPortal()` and `@ngPortalOutput()`\n - `@ngPortal()` receives from `@ngPortal()` and `@ngPortalInput()`\n - `@ngPortalInput()` sends to `@ngPortal()` and `@ngPortalOutput()` \n - `@ngPortalInput()` doesn't receive\n - `@ngPortalOutput()` doesn't send\n - `@ngPortalOutput()` receives from `@ngPortal()` and `@ngPortalInput()`\n\nType:\n\nBehind the scene, `@ngPortal()` apply a getter and a setter on the property:\n\n - `@ngPortal() property: string;` =\u003e `get property(): Observable\u003cstring\u003e` and `set property(value: string): void`\n - `@ngPortalInput() property: string;` =\u003e `set property(value: string): void` (only setter available)\n - `@ngPortalOutput() property: string;` =\u003e `get property(): Observable\u003cstring\u003e` (only getter available)\n\n## Examples\n\nBelow there are some examples of use case.\n\n### Example: input / output components connected by property name\n\n`InputComponent` has property `value` with `@ngPortalInput()` decorator that on change update property `value` into `OutputComponent` with `@ngPortalOutput()`, eg.:\n\n```ts\nimport { Component } from '@angular/core';\nimport { ngPortalInput, ngPortalOutput } from 'ng-portal';\nimport { Observable } from 'rxjs';\n\n@Component({\n  selector: 'app-input',\n  template: `\u003cinput (keyup)=\"value = $event.target.value\"\u003e`,\n})\nexport class InputComponent {\n  @ngPortalInput() value: string;\n}\n\n@Component({\n  selector: 'app-output',\n  template: `{{ value | async }}`,\n})\nexport class OutputComponent {\n  @ngPortalOutput() value: Observable\u003cstring\u003e;\n}\n```\n\n### Example: input / output components connected by key\n\n`InputComponent` has property `inputValue` with `@ngPortalInput({key: 'foo'})` decorator that on change update property `outputValue` into `OutputComponent` with `@ngPortalOutput({key: 'foo'})`. In this case is the key 'foo' that made the connection, eg.:\n\n```ts\nimport { Component } from '@angular/core';\nimport { ngPortalInput, ngPortalOutput } from 'ng-portal';\nimport { Observable } from 'rxjs';\n\n@Component({\n  selector: 'app-input',\n  template: `\u003cinput (keyup)=\"inputValue = $event.target.value\"\u003e`,\n})\nexport class InputComponent {\n  @ngPortalInput({key: 'foo'}) inputValue: string;\n}\n\n@Component({\n  selector: 'app-output',\n  template: `{{ value | async }}`,\n})\nexport class OutputComponent {\n  @ngPortalOutput({key: 'foo'}) outputValue: Observable\u003cstring\u003e;\n}\n```\n\n### Example: NgModel connection by property name\n\n`ModelComponent` has property `model` with `@ngPortal()` decorator that on change update property `model` in every components with same property and `@ngPortal()` or `@ngPortalOutput()` decorators. eg.:\n\n```ts\nimport { Component } from '@angular/core';\nimport { ngPortal } from 'ng-portal';\n\n@Component({\n  selector: 'app-model',\n  template: `\u003cinput [ngModel]=\"model | async\" (ngModelChange)=\"model = $event\"\u003e`,\n})\nexport class ModelComponent {\n  @ngPortal() model: any;\n}\n```\n\n### Example: NgModel connection connected by key\n\n`ModelComponent` has property `model` with `@ngPortal({key: 'foo'})` decorator that on change update every property in every components with `@ngPortal({key: 'foo'})` or `@ngPortalOutput({key: 'foo'})` decorators. eg.:\n\n```ts\nimport { Component } from '@angular/core';\nimport { ngPortal, ngPortalOutput } from 'ng-portal';\nimport { Observable } from 'rxjs';\n\n@Component({\n  selector: 'app-model',\n  template: `\u003cinput [ngModel]=\"model | async\" (ngModelChange)=\"model = $event\"\u003e`,\n})\nexport class ModelComponent {\n  @ngPortal({key: 'foo'}) model: any;\n}\n\n@Component({\n  selector: 'app-output',\n  template: `{{ value | async }}`,\n})\nexport class OutputComponent {\n  @ngPortalOutput({key: 'foo'}) outputValue: Observable\u003cstring\u003e;\n}\n```\n\n\n## Service\n\nYou can inject into your component the `NgPortalService` that expose some utils methods:\n\n```ts\nexport class NgPortalService {\n\n  /**\n   * Send a \"value\" for the \"key\" (key or property name)\n   */\n  send(key: string, value: any): void;\n\n  /**\n   * Return an Observable for the \"key\" (key or property name)\n   */\n  get\u003cK\u003e(key: string): Observable\u003cK\u003e;\n\n  /**\n   * Return an Observable for all the \"key\" (key or property name)\n   */\n  getAll(): Observable\u003cNgPortalServiceMessage\u003e;\n}\n```\n\n## Support\n\nThis is an open-source project. Star this [repository](https://github.com/nigrosimone/ng-portal), if you like it, or even [donate](https://www.paypal.com/paypalme/snwp). Thank you so much!\n\n## My other libraries\n\nI have published some other Angular libraries, take a look:\n\n - [NgSimpleState: Simple state management in Angular with only Services and RxJS](https://www.npmjs.com/package/ng-simple-state)\n - [NgHttpCaching: Cache for HTTP requests in Angular application](https://www.npmjs.com/package/ng-http-caching)\n - [NgGenericPipe: Generic pipe for Angular application for use a component method into component template.](https://www.npmjs.com/package/ng-generic-pipe)\n - [NgLet: Structural directive for sharing data as local variable into html component template](https://www.npmjs.com/package/ng-let)\n - [NgForTrackByProperty: Angular global trackBy property directive with strict type checking](https://www.npmjs.com/package/ng-for-track-by-property)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigrosimone%2Fng-portal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnigrosimone%2Fng-portal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnigrosimone%2Fng-portal/lists"}