Skip to content

Commit 5ee910b

Browse files
AirbladerAirblader
committed
chore(docs): More docs
1 parent 2a637e2 commit 5ee910b

4 files changed

Lines changed: 84 additions & 4 deletions

File tree

‎projects/ngqp-demo/src/app/demo.module.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ import { GettingHelpDocsComponent } from './docs-items/getting-help/getting-help
2323
import { ModelConfigurationDocsComponent } from './docs-items/model-configuration/model-configuration-docs.component';
2424
import { ApiDocsLinkComponent } from './shared/api-docs-link/api-docs-link.component';
2525
import { ReplaceUrlExampleComponent } from './docs-items/model-configuration/examples/replace-url-example/replace-url-example.component';
26+
import { SerializerExampleComponent } from './docs-items/model-configuration/examples/serializer-example/serializer-example.component';
2627

2728
@NgModule({
2829
declarations: [
@@ -49,6 +50,7 @@ import { ReplaceUrlExampleComponent } from './docs-items/model-configuration/exa
4950
ModelConfigurationDocsComponent,
5051
ApiDocsLinkComponent,
5152
ReplaceUrlExampleComponent,
53+
SerializerExampleComponent,
5254
],
5355
imports: [
5456
BrowserModule,

‎projects/ngqp-demo/src/app/docs-items/model-configuration/examples/serializer-example/serializer-example.component.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<demo-example [markup]="markup" [typescript]="typescript">
2+
<demo-browser>
3+
<div class="alert alert-info">
4+
In this example, the boolean parameter of the checkbox is (de-)serialized using the strings "active" and
5+
"inactive" rather than the default "true" and "false".
6+
</div>
7+
8+
<div [queryParamGroup]="paramGroup" class="form-check">
9+
<input id="status" type="checkbox" class="form-check-input" queryParamName="status" />
10+
<label for="status" class="form-check-label">Active</label>
11+
</div>
12+
</demo-browser>
13+
</demo-example>

‎projects/ngqp-demo/src/app/docs-items/model-configuration/examples/serializer-example/serializer-example.component.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { Component } from '@angular/core';
2+
import { QueryParamBuilder, QueryParamGroup } from '@ngqp/core';
3+
4+
declare const require: Function;
5+
6+
@Component({
7+
selector: 'demo-serializer-example',
8+
templateUrl: './serializer-example.component.html',
9+
})
10+
export class SerializerExampleComponent {
11+
12+
public paramGroup: QueryParamGroup;
13+
14+
public markup = require('!raw-loader!./serializer-example.component.html');
15+
public typescript = require('!raw-loader!./serializer-example.component.ts');
16+
17+
constructor(private qpb: QueryParamBuilder) {
18+
this.paramGroup = qpb.group({
19+
status: qpb.booleanParam({
20+
param: 'status',
21+
serialize: (value: boolean): string => value ? 'active' : 'inactive',
22+
deserialize: (value: string): boolean => !value || value === 'active',
23+
}),
24+
});
25+
}
26+
27+
}

‎projects/ngqp-demo/src/app/docs-items/model-configuration/model-configuration-docs.component.html‎

Lines changed: 42 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ <h3>Serializing and deserializing</h3>
7979
versa, how the parameter value is converted into the value used in the form control. If you need or want to
8080
provide your own (de-)serializers, you can pass them to <span apiDocsLink>QueryParamBuilder#param</span>.
8181
</p>
82-
<!-- TODO Example -->
82+
<demo-serializer-example></demo-serializer-example>
8383
<docs-fragment fragment="QueryParam-multi">
8484
<h3>Multiple values</h3>
8585
</docs-fragment>
@@ -93,18 +93,56 @@ <h3>Multiple values</h3>
9393
<h3>Debouncing user input</h3>
9494
</docs-fragment>
9595
<p>
96-
TODO
96+
For some form controls such as an input field, it may be too aggressive to update the URL on every keystroke
97+
as <span apiDocsLink>QueryParamGroup#valueChanges</span> would fire many times as well. A common solution is
98+
to <em>debounce</em> such inputs such that the value is only taken once user input rests for a specified time
99+
period.
100+
</p>
101+
<p>
102+
This effect can be achieved using the <span apiDocsLink>QueryParam#debounceTime</span> option of a parameter,
103+
defining the debounce time in ms.
97104
</p>
105+
<div class="alert alert-info">
106+
Note that the debounce will happen <em>before</em> the URL is updated rather than debouncing the
107+
<span apiDocsLink>QueryParamGroup#valueChanges</span> emissions. This is intentional, as you wouldn't want the
108+
debounce to happen when initially navigating to a specific route.
109+
</div>
110+
<!-- TODO Example -->
98111
<docs-fragment fragment="QueryParam-emptyOn">
99112
<h3>Default values</h3>
100113
</docs-fragment>
114+
<div class="alert alert-warning">
115+
Note that this feature is currently not supported if you are using <span apiDocsLink>QueryParam#multi</span>.
116+
</div>
117+
<p>
118+
By default, if a parameter value is <code>null</code>, the parameter will be removed from the URL. For example,
119+
this prevents useless URL segments such as <code>?q=</code> (without a value). However, in some cases you might
120+
want this "default" to be a different value, e.g., a numeric input should perhaps default to <code>0</code>
121+
instead.
122+
</p>
101123
<p>
102-
TODO emptyOn, compareWith
124+
This can be achieved by speficying the value using <span apiDocsLink>QueryParam#emptyOn</span>. This means that
125+
if the form control takes on the specified value, the parameter will be removed from the URL. Likewise, if the
126+
parameter is not found on the URL, this value will be written to the form control.
103127
</p>
128+
<p>
129+
Note that this relies on a comparison against the given value, which works fine for basic types (string, number,
130+
boolean). If you have complex types, you need to also define a <span apiDocsLink>QueryParam#compareWith</span>
131+
function which checks whether two given values should be considered equal.
132+
</p>
133+
<!-- TODO Example -->
104134
<docs-fragment fragment="QueryParam-combineWith">
105135
<h3>Side effects on other parameters</h3>
106136
</docs-fragment>
107137
<p>
108-
TODO
138+
In some cases you may want changes in a parameter to affect another parameter as well. For example, changing
139+
the sorting of a paginated table should reset the selected page back to the first one. This can be achieved
140+
by providing a <span apiDocsLink>QueryParam#combineWith</span> function.
109141
</p>
142+
<p>
143+
This function will receive the previous and the new value of the parameter and is expected to return an object
144+
containing any other changes to the query parameters. Note that this is a "raw" object, referencing the actual
145+
URL parameter names directly. No (de-)serializers will be run and this effect does not cascade.
146+
</p>
147+
<!-- TODO Example -->
110148
</docs-item>

0 commit comments

Comments
 (0)