Skip to content

Commit 6b2f9d2

Browse files
Shuwen QianDan Lasky
authored andcommitted
Update sync article for API changes and some light copy editing
1 parent b52edf5 commit 6b2f9d2

1 file changed

Lines changed: 28 additions & 29 deletions

File tree

docs/articles/data_comps_using_sync.md

Lines changed: 28 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -16,60 +16,59 @@ a `url` property is also exposed and can be used to set the base or non-changing
1616

1717
### Param configuration
1818

19-
Sync's configuration is divided into 2 sets of operations: input and output.
20-
Input params are used for `GET` requests. Output params are used for `POST`, `PUT`, and `DELETE` requests.
19+
Sync accepts configuration via tags corresponding to HTTP methods: `<get>`, `<post>`, `<put>`, and `<delete>`. Params can then be passed to Sync as DOM children of those nodes.
2120

2221
Params were designed to give the developer full flexibility over crafting the request arguments. With this in mind the param options were divided into:
2322

24-
* queryParam -- name value pair objects used to generate the queryString
25-
* urlParam -- name only strings concatenated with '/' to generate a URL
26-
* headers -- name value pairs used to send additional metadata (CSRF, etc) to the webserver
23+
* queryParam&thinsp;&mdash;&thinsp;name value pair objects used to generate the queryString
24+
* urlParam&thinsp;&mdash;&thinsp;name only strings concatenated with '/' to generate a URL
25+
* headers&thinsp;&mdash;&thinsp;name value pairs used to send additional metadata (CSRF, etc) to the webserver
2726

28-
The 'direction' of input or output is relative to the component itself, so when you are pulling data from the server via a get, we consider that 'input' to the component, and the reverse is true for saving/deletion operations.
29-
30-
### Input param example
27+
### GET example
3128

3229
```html
3330
<mm-sync endpoint="http://example.com">
34-
<input-params>
31+
<get>
3532
<queryParam name="q" value="123"/>
3633
<urlParam>123</urlParam>
3734
<header name="X-Some-Header">HeaderValue</header>
38-
</input-params>
35+
</get>
3936
</mm-sync>
4037
```
4138

42-
This will generate a URL for the request of `http://example.com/123/?q=123` and it will send an X-Some-Header: HeaderValue to the server with the request. Note that it is possible to either use a value attribute or to just place the value inside the body of a named node. These formats may be used interchangeably.
39+
This will generate a URL for the request of `http://example.com/123/?q=123` and it will send an X-Some-Header: HeaderValue to the server with the request. Note that it is possible to either use a value attribute or to just place the value inside the textContent of a named node. These formats may be used interchangeably.
4340

44-
### Output param example
41+
### POST example
4542
```html
4643
<mm-sync endpoint="http://test.com">
47-
<output-params>
44+
<post>
4845
<urlParam>campaigns</urlParam>
4946
<urlParam>52312</urlParam>
5047
<header name="X-CSRF-Header">48ccbaffbb0675f2a</header>
51-
</output-params>
48+
</post>
5249
</mm-sync>
5350
```
5451

55-
Note that we use the urlParam twice--this may be done for any set of params N number of times as appropriate. Params are parsed top down for API's where the order matters.
52+
Note that we use the urlParam twice&thinsp;&mdash;&thinsp;this may be done for any set of params _N_ number of times as appropriate. Params are parsed top down for API's where the order matters.
5653

57-
It is also possible to set both input and output params on the same element to configure it for general I/O by adding both sections at the same level:
54+
It is also possible to pass multiple sets of params to the same element to configure it for general I/O by adding sections at the same level:
5855

5956
```html
6057
<mm-sync>
61-
<input-params></input-params>
62-
<output-params></output-params>
58+
<get></get>
59+
<post></post>
60+
<put></put>
61+
<delete></delete>
6362
</mm-sync>
6463
```
6564

6665
## Working with 2-way binding
6766

68-
To support 2-way binding in a scenario using mm-sync we have created the `auto` param. Auto tells mm-sync to respond automatically to data or param changes and make additional requests to sync the data back to the server. Auto may be set via JS or via HTML as an attribute. Auto has 3 possible values:
67+
To support 2-way binding in a scenario using mm-sync we have created the `auto` property. Auto tells mm-sync to respond automatically to data or param changes and make additional requests to sync the data back to the server. Auto may be set via JS or via HTML as an attribute. Auto has 3 possible values:
6968

70-
* true `boolean` -- bidirectional sync input/output for any changes
71-
* load `string`-- only sync data in from server when input params change
72-
* save `string` -- only sync data in from the server when the data property detects a change-- note that due to polymer 1.0 data binding limitations you must manually tell polymer that the data has changed using `set`
69+
* true `boolean`&thinsp;&mdash;&thinsp;bidirectional sync input/output for any changes
70+
* load `string`&thinsp;&mdash;&thinsp;only sync data in from server when input params change
71+
* save `string`&thinsp;&mdash;&thinsp;only sync data in from the server when the data property detects a change&thinsp;&mdash;&thinsp;note that due to Polymer 1.0 data binding limitations you must manually tell Polymer that the data has changed using `set`
7372

7473
```javascript
7574
var sync = document.querySelector("mm-sync");
@@ -92,19 +91,19 @@ The following is an example of the simple input scenario using a self binding te
9291
Now bind this to a sync components params from our earlier example:
9392

9493
```html
95-
<template is="auto-binding">
94+
<template is="dom-bind">
9695
<mm-input value="{{search}}"/>
9796
<mm-sync endpoint="http://example.com" auto="true">
98-
<input-params>
97+
<get>
9998
<queryParam name="q" value="{{search}}"/>
10099
<urlParam>123</urlParam>
101100
<header name="X-Some-Header">HeaderValue</header>
102-
</input-params>
101+
</get>
103102
</mm-sync>
104103
</template>
105104
```
106105

107-
When the lightDOM queryParam values are changed via 2-way binding, the sync component will pick this up and trigger the requisite `GET` calls to retrieve this query from the server. Note that this input is automatically debounced against keyboard input. If necessary you may vary this timing via the `autoDebounce` property. The default is 200ms.
106+
When the light DOM queryParam values are changed via 2-way binding, the sync component will pick this up and trigger the requisite `GET` calls to retrieve this query from the server. Note that this input is automatically debounced against keyboard input. If necessary you may vary this timing via the `autoDebounce` property. The default is 200ms.
108107

109108
### 2-way binding on the response
110109

@@ -114,16 +113,16 @@ Unfortunately this example does not provide any feedback to the user, but it is
114113
<template is="auto-binding">
115114
<input value="{{search}}">
116115
<mm-sync url="http://example.com" auto="true" data="{{result}}">
117-
<input-params>
116+
<get>
118117
<queryParam name="q" value="{{search}}"/>
119118
<urlParam>123</urlParam>
120119
<header name="X-Some-Header">HeaderValue</header>
121-
</input-params>
120+
</get>
122121
</mm-sync>
123122
<ul>
124123
<template is="dom-repeat" items="{{result.list}}">
125124
<li>{{item.name}}</li>
126125
</template>
127126
</ul>
128127
</template>
129-
```
128+
```

0 commit comments

Comments
 (0)