Skip to content

Commit 036681d

Browse files
NetanelBasalNetanelBasal
committed
docs: add @NetanelBasal as a contributor
1 parent 5647f8b commit 036681d

File tree

2 files changed

+123
-24
lines changed

2 files changed

+123
-24
lines changed

‎.all-contributorsrc

+15-1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,20 @@
99
"imageSize": 100,
1010
"commit": true,
1111
"commitConvention": "angular",
12-
"contributors": [],
12+
"contributors": [
13+
{
14+
"login": "NetanelBasal",
15+
"name": "Netanel Basal",
16+
"avatar_url": "https://avatars1.githubusercontent.com/u/6745730?v=4",
17+
"profile": "https://www.netbasal.com/",
18+
"contributions": [
19+
"code",
20+
"content",
21+
"doc",
22+
"ideas",
23+
"infra"
24+
]
25+
}
26+
],
1327
"contributorsPerLine": 7
1428
}

‎README.md

+108-23
Original file line numberDiff line numberDiff line change
@@ -12,46 +12,125 @@
1212
[![ngneat](https://img.shields.io/badge/@-ngneat-383636?style=flat-square&labelColor=8f68d4)](https://github.com/ngneat/)
1313
[![spectator](https://img.shields.io/badge/tested%20with-spectator-2196F3.svg?style=flat-square)]()
1414

15-
> The Library Slogan
15+
> Sync URL Query Params with Angular Form Controls
1616
17-
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquid assumenda atque blanditiis cum delectus eligendi ipsam iste iure, maxime modi molestiae nihil obcaecati odit officiis pariatur quibusdam suscipit temporibus unde.
18-
Accusantium aliquid corporis cupiditate dolores eum exercitationem illo iure laborum minus nihil numquam odit officiis possimus quas quasi quos similique, temporibus veritatis? Exercitationem, iure magni nulla quo sapiente soluta. Esse?
17+
The library provides a simple and reusable solution for binding URL query params to Angular Forms.
1918

20-
## Features
19+
## Installation
2120

22-
- ✅ One
23-
- ✅ Two
24-
- ✅ Three
21+
`npm install @ngneat/bind-query-params`
2522

26-
## Table of Contents
23+
## Usage
2724

28-
- [Installation](#installation)
29-
- [Usage](#usage)
30-
- [FAQ](#faq)
25+
Inject the `BindQueryParamsFactory` provider, pass an array of [defenitions](#QueryParamDefenition) and `connect` it to your form:
3126

32-
## Installation
27+
<!-- prettier-ignore -->
28+
```ts
29+
import { BindQueryParamsFactory } from '@ngneat/bind-query-params';
30+
31+
interface Filters {
32+
searchTerm: string;
33+
someBoolean: boolean;
34+
}
35+
36+
@Component({
37+
template: `Your normal form setup`,
38+
})
39+
export class MyComponent {
40+
filters = new FormGroup({
41+
searchTerm: new FormControl(),
42+
someBoolean: new FormControl(false),
43+
});
44+
45+
bindQueryParamsManager = this.factory
46+
.create<Filters>([
47+
{ queryKey: 'searchTerm' },
48+
{ queryKey: 'someBoolean', type: 'boolean' }
49+
]).connect(this.filters);
50+
51+
constructor(private factory: BindQueryParamsFactory) {}
52+
53+
ngOnDestroy() {
54+
this.bindQueryParamsManager.destroy();
55+
}
56+
}
57+
```
3358

34-
### NPM
59+
With this setup, the `manager` will take care of two things:
3560

36-
`npm install @ngneat/bind-query-params --save-dev`
61+
1. Update the `control`'s value when the page is loaded for the first time
62+
2. Update the URL query parameter when the corresponding `control` value changes
3763

38-
### Yarn
64+
## QueryParam Defenition
3965

40-
`yarn add @ngneat/bind-query-params --dev`
66+
### `queryKey`
4167

42-
## Usage
68+
The query parameter key
69+
70+
### `path`
4371

44-
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquid assumenda atque blanditiis cum delectus eligendi ipsam iste iure, maxime modi molestiae nihil obcaecati odit officiis pariatur quibusdam suscipit temporibus unde.
72+
The form control path. If it is not specified, the manager assumes that the `path` is the `queryKey`. We can also pass nested keys, for example, `person.name`:
4573

4674
```ts
47-
function helloWorld() {}
75+
{ queryKey: 'name', path: 'person.name' }
4876
```
4977

50-
## FAQ
78+
### `type`
79+
80+
Specify the control value type. Available options are:
81+
`string`, `boolean`, `array`.
82+
Before updating the control with the value, the manager will parse it based on the provided `type`.
83+
84+
### `parser`
85+
86+
Provide a custom parser. For example, the default `array` parser converts the value to an `array` of strings. If we need it to be an array of numbers, we can pass the following `parser`:
5187

52-
## How to ...
88+
`{ parser: value => value.split(',').map(v => +v ) }`
5389

54-
Lorem ipsum dolor sit amet, consectetur adipisicing elit. Aliquid assumenda atque blanditiis cum delectus eligendi ips
90+
### `strategy`
91+
92+
When working with async control values, for example, a dropdown list that its options come from the server, we cannot immediately update the control.
93+
94+
In this cases, we can provide the `modelToUrl` strategy, that will not update the control value when the page loads. When the data is available we can call the `manager.syncDefs()` method that'll update the provided keys based on the current query params:
95+
96+
```ts
97+
@Component()
98+
export class MyComponent {
99+
filters = new FormGroup({
100+
searchTerm: new FormControl(),
101+
users: new FormControl([]),
102+
someBoolean: new FormControl(false),
103+
});
104+
105+
bindQueryParamsManager = this.factory
106+
.create<Filters>([
107+
{ queryKey: 'searchTerm' },
108+
{ queryKey: 'someBoolean', type: 'boolean' },
109+
{ queryKey: 'users', type: 'array', strategy: 'modelToUrl' },
110+
])
111+
.connect(this.filters);
112+
113+
constructor(private factory: BindQueryParamsFactory) {}
114+
115+
ngOnInit() {
116+
service.getUsers().subscribe((users) => {
117+
// Initalize the dropdown
118+
this.users = users;
119+
this.manager.syncDefs('users');
120+
});
121+
}
122+
123+
ngOnDestroy() {
124+
this.bindQueryParamsManager.destroy();
125+
}
126+
}
127+
```
128+
129+
Note that `syncDefs` will always be called once under the hood.
130+
131+
## Browser Support
132+
133+
The library uses the [URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) API, which supported in any browser except IE.
55134

56135
## Contributors ✨
57136

@@ -60,7 +139,13 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
60139
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
61140
<!-- prettier-ignore-start -->
62141
<!-- markdownlint-disable -->
63-
<!-- markdownlint-enable -->
142+
<table>
143+
<tr>
144+
<td align="center"><a href="https://www.netbasal.com/"><img src="https://avatars1.githubusercontent.com/u/6745730?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Netanel Basal</b></sub></a><br /><a href="https://github.com/@ngneat/bind-query-params/commits?author=NetanelBasal" title="Code">💻</a> <a href="#content-NetanelBasal" title="Content">🖋</a> <a href="https://github.com/@ngneat/bind-query-params/commits?author=NetanelBasal" title="Documentation">📖</a> <a href="#ideas-NetanelBasal" title="Ideas, Planning, & Feedback">🤔</a> <a href="#infra-NetanelBasal" title="Infrastructure (Hosting, Build-Tools, etc)">🚇</a></td>
145+
</tr>
146+
</table>
147+
148+
<!-- markdownlint-restore -->
64149
<!-- prettier-ignore-end -->
65150

66151
<!-- ALL-CONTRIBUTORS-LIST:END -->

0 commit comments

Comments
 (0)