Skip to content

GitLab

Commit 3669f4a0 authored by Tejesh's avatar Tejesh 🖖
Browse files

reorder urlfilter documentation. elaborate `urlfilter` event on `pushState`. issue #47

parent d2214db7
Pipeline #47844 failed with stage
in 1 minute and 54 seconds
Hide whitespace changes
Inline Side-by-side
README.md
View file @ 3669f4a0
......@@ -112,9 +112,165 @@ URLFilter containers uses these attributes:
- You can also specify `data-mode`, `data-remove` and `data-src`. This is the same as specifying on
every `.urlfilter` trigger.
## url.parse
`g1.url` provides URL manipulation utilities.
```js
var url = g1.url.parse("https://username:password@example.com:80/~folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash")
```
### url object attributes
This parses the URL and returns an object with the following attributes matching `window.location`:
| Attribute | Value |
|------------|------------------------------------|
| `href` | the original URL |
| `protocol` | `https` |
| `origin` | `username:password@example.com:80` |
| `username` | `username` |
| `password` | `password` |
| `hostname` | `example.com` |
| `port` | `80` |
| `pathname` | `folder/subfolder/filename.html` |
| `search` | `a=1&a=2&b=3%2E&d` |
| `hash` | `hash` |
... and additional attributes:
| Attribute | Value |
|--------------|--------------------------------------------------------|
| `userinfo` | `username:password` |
| `relative` | `folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash` |
| `directory` | `folder/subfolder/` |
| `file` | `filename.html` |
| `searchKey` | `{'a:'2', b:'3.', d:''}` |
| `searchList` | `{'a:['1', '2'], b:['3.'], d:['']}` |
It can also parse URL query strings.
```js
var url = g1.url.parse('?a=1&a=2&b=3%2E&d#hash')
```
| Attribute | Value |
|--------------|----------------------------------|
| `search` | `a=1&a=2&b=3%2E&d` |
| `hash` | `hash` |
| `searchKey` | `{a:'2', b:'3.', d:''}` |
| `searchList` | `a:['1', '2'], b:['3.'], d:['']` |
These attributes are **not mutable**. To change the URL, use
[url.join](#urljoin) or [url.update](#urlupdate).
### url object methods
The url object has a `.toString()` method that converts the object back into a
string.
## url.join
```js
var url = url.join(another_url)
```
updates the `url` with the attributes from `another_url`. For example:
| url | joined with | gives |
|------------------------|----------------------|----------------------------|
| `/path/p` | `a/b/c` | `/path/a/b/c` |
| `/path/p/q/` | `../a/..` | `/path/p/` |
| `http://host1/p` | `http://host2/q` | `http://host2/q` |
| `https://a:b@host1/p` | `//c:d@host2/q?x=1` | `https://c:d@host2/q?x=1` |
| `/path/p?b=1` | `./?a=1#top` | `/path/?a=1#top` |
`.join()` updates the query parameters and hash fragment as well. To prevent this, use:
```js
url.join(another_url, {query: false, hash: false})
```
For example:
```js
g1.url.parse('/').join('/?x=1#y=1', {hash: false}).toString() == '/?x=1'
g1.url.parse('/').join('/?x=1#y=1', {query: false}).toString() == '/#y=1'
```
## url.update
```js
var url = url.update(object)
```
updates the `url` query parameters with the attributes from `object`. For example:
| url | updated with | gives |
|--------------|----------------------|-----------------------|
| `/` | `{a:1}` | `/?a=1` |
| `/?a=1&b=2` | `{b:3, a:4, c:''}` | `/?a=4&b=3&c=` |
| `/?a=1&b=2` | `{a:null}` | `/?b=2` |
| `/?a=1&b=2` | `{a:[3,4], b:[4,5]}` | `/?a=3&a=4&b=4&b=5` |
By default, it *updates* the query parameters. But:
- `url.update(object, 'add')` *adds* the query parameters instead of updating
- `url.update(object, 'del')` *deletes* the query parameters instead of updating
- `url.update(object, 'toggle')` *toggles* the query parameters (i.e. adds if missing, deletes if present)
For example:
| url | updated with | in mode | gives |
|---------------------|----------------------|---------------------|-----------------------|
| `/?a=1&a=2` | `{a:3, b:1}` | `add` | `/?a=1&a=2&a=3&b=1` |
| `/?a=1&a=2'` | `{a:[3,4]}` | `add` | `/?a=1&a=2&a=3&a=4` |
| `/?a=1&a=2&b=1` | `{a:2, b:2}` | `del` | `/?a=1&b=1` |
| `/?a=1&a=2&b=1` | `{a:[1,4]}` | `del` | `/?a=2&b=1` |
| `/?a=1&a=2` | `{a:1, b:1}` | `toggle` | `/?a=2&b=1` |
| `/?a=1&a=2&b=1&b=2` | `{a:[2,3], b:[1,3]}` | `toggle` | `/?a=1&a=3&b=2&b=3` |
You can specify different modes for different query parameters.
```js
g1.url.parse('/?a=1&b=2&c=3&d=4') // Update this URL
.update({a:1, b:[2,3], c:6, d:7}, // With this object
'a=del&b=toggle&c=add') // Delete ?a, Toggle ?b, add ?c, update ?d (default)
// Returns /?b=3&c=3&c=6&d=7
```
## Interaction conventions
All interaction components use this naming convention:
- Interactions are enabled on a *container*, typically `body`. For example,
`$('body').urlfilter()`. Containers have these common attributes:
- `data-selector`: selector to identify triggers. e.g. `.urlfilter`, `.highlight`
- `data-target`: selector that all triggers act on by default
- `data-mode`: mode of interaction for all triggers
- `data-attr`: attribute that contains the interaction data, e.g. `href` for `.urlfilter`
- Interactions are triggered on a *trigger*. For example, `.urlfilter` for `$().urlfilter()`.
Clicking / hovering on / typing in a trigger triggers the interaction.
- `data-target`: selector that this trigger acts on
- `data-mode`: mode of interaction for this trigger
- Interactions change a *target*. For example, `urlfilter` changes `location.href` by default. The
`data-target` on containers and triggers define this.
- Interactions data is contained in an attribute. This is applied to the target. For example,
`.urlfilter` applied `href` to the target. The attribute name is stored in `data-attr`.
- Interactions have *modes*. This can be controlled using `data-mode=`.
All container `data-` attributes can also be passed as an option to the
function. For example, `<body data-selector=".link">` is the same as
`$('body').urlfilter({selector: '.link'})`.
### $.urlfilter events
- `urlfilter` is fired on the trigger when the URL is changed. Attributes:
- `urlfilter` is fired on the trigger when the URL is changed by DOM elements with target as `'pushState'`. Attributes:
- `url`: the new URL
- `load` is fired on the target when the URL is loaded -- only if the `data-target=` is a selector. Attributes:
- `url`: the new URL
......@@ -158,6 +314,47 @@ Highlight containers use these attributes:
- `target`: elements that match the `data-target=` selector
## types
`g1.types(data)` returns the column data types. For example:
```js
var data = [
{a: 1, b: 1.1, c: 'c', d: '2014-04-04', e: true},
{a: 2, b: 2},
]
g1.types(data) // Returns {"a": "number", "b": "number", "c": "string", "d": "date", "e": "boolean"}
```
### types options
`types()` accepts 2 parameters:
- `data`: a list of objects
- `options`: a dictionary that may contain these keys:
- `convert`: converts values to the right type. For example, "1" is converted to 1. default: `false`
- `limit`: number of rows to evaluate. default: 1000
- `ignore`: list of values that should be ignored. default: `[null, undefined]`
Rules:
- Evaluate up to `limit` rows
- Ignore values that are keys in the `ignore` option. Only consider the rest
- If `convert` is `false`, then for each column:
- If all values are Date objects -> `date`
- Else if all values are numbers -> `number`
- Else if all values are strings -> `string`
- Else if all values are bools -> `boolean`
- Else if there are no values or is undefined or null -> `null`
- Else -> `mixed`
- Else if `convert` is `true`, then for each column:
- If all values can be converted to Date -> `date`
- Else if all values can be converted to numbers -> `number`
- Else if all values are bools -> `boolean`
- Else if there are no values or is undefined or null -> `null`
- Else -> `string`
## datafilter
`g1.datafilter(data, filters)` returns the filtered data based on the filters. While urlfilter on [$.formhandler](#formhandler) applies filtering on data server side, `datafilter` applies urlfilter on frontend loaded data.
......@@ -781,200 +978,6 @@ selection.call(
```
## url.parse
`g1.url` provides URL manipulation utilities.
```js
var url = g1.url.parse("https://username:password@example.com:80/~folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash")
```
### url object attributes
This parses the URL and returns an object with the following attributes matching `window.location`:
| Attribute | Value |
|------------|------------------------------------|
| `href` | the original URL |
| `protocol` | `https` |
| `origin` | `username:password@example.com:80` |
| `username` | `username` |
| `password` | `password` |
| `hostname` | `example.com` |
| `port` | `80` |
| `pathname` | `folder/subfolder/filename.html` |
| `search` | `a=1&a=2&b=3%2E&d` |
| `hash` | `hash` |
... and additional attributes:
| Attribute | Value |
|--------------|--------------------------------------------------------|
| `userinfo` | `username:password` |
| `relative` | `folder/subfolder/filename.html?a=1&a=2&b=3%2E&d#hash` |
| `directory` | `folder/subfolder/` |
| `file` | `filename.html` |
| `searchKey` | `{'a:'2', b:'3.', d:''}` |
| `searchList` | `{'a:['1', '2'], b:['3.'], d:['']}` |
It can also parse URL query strings.
```js
var url = g1.url.parse('?a=1&a=2&b=3%2E&d#hash')
```
| Attribute | Value |
|--------------|----------------------------------|
| `search` | `a=1&a=2&b=3%2E&d` |
| `hash` | `hash` |
| `searchKey` | `{a:'2', b:'3.', d:''}` |
| `searchList` | `a:['1', '2'], b:['3.'], d:['']` |
These attributes are **not mutable**. To change the URL, use
[url.join](#urljoin) or [url.update](#urlupdate).
### url object methods
The url object has a `.toString()` method that converts the object back into a
string.
## url.join
```js
var url = url.join(another_url)
```
updates the `url` with the attributes from `another_url`. For example:
| url | joined with | gives |
|------------------------|----------------------|----------------------------|
| `/path/p` | `a/b/c` | `/path/a/b/c` |
| `/path/p/q/` | `../a/..` | `/path/p/` |
| `http://host1/p` | `http://host2/q` | `http://host2/q` |
| `https://a:b@host1/p` | `//c:d@host2/q?x=1` | `https://c:d@host2/q?x=1` |
| `/path/p?b=1` | `./?a=1#top` | `/path/?a=1#top` |
`.join()` updates the query parameters and hash fragment as well. To prevent this, use:
```js
url.join(another_url, {query: false, hash: false})
```
For example:
```js
g1.url.parse('/').join('/?x=1#y=1', {hash: false}).toString() == '/?x=1'
g1.url.parse('/').join('/?x=1#y=1', {query: false}).toString() == '/#y=1'
```
## url.update
```js
var url = url.update(object)
```
updates the `url` query parameters with the attributes from `object`. For example:
| url | updated with | gives |
|--------------|----------------------|-----------------------|
| `/` | `{a:1}` | `/?a=1` |
| `/?a=1&b=2` | `{b:3, a:4, c:''}` | `/?a=4&b=3&c=` |
| `/?a=1&b=2` | `{a:null}` | `/?b=2` |
| `/?a=1&b=2` | `{a:[3,4], b:[4,5]}` | `/?a=3&a=4&b=4&b=5` |
By default, it *updates* the query parameters. But:
- `url.update(object, 'add')` *adds* the query parameters instead of updating
- `url.update(object, 'del')` *deletes* the query parameters instead of updating
- `url.update(object, 'toggle')` *toggles* the query parameters (i.e. adds if missing, deletes if present)
For example:
| url | updated with | in mode | gives |
|---------------------|----------------------|---------------------|-----------------------|
| `/?a=1&a=2` | `{a:3, b:1}` | `add` | `/?a=1&a=2&a=3&b=1` |
| `/?a=1&a=2'` | `{a:[3,4]}` | `add` | `/?a=1&a=2&a=3&a=4` |
| `/?a=1&a=2&b=1` | `{a:2, b:2}` | `del` | `/?a=1&b=1` |
| `/?a=1&a=2&b=1` | `{a:[1,4]}` | `del` | `/?a=2&b=1` |
| `/?a=1&a=2` | `{a:1, b:1}` | `toggle` | `/?a=2&b=1` |
| `/?a=1&a=2&b=1&b=2` | `{a:[2,3], b:[1,3]}` | `toggle` | `/?a=1&a=3&b=2&b=3` |
You can specify different modes for different query parameters.
```js
g1.url.parse('/?a=1&b=2&c=3&d=4') // Update this URL
.update({a:1, b:[2,3], c:6, d:7}, // With this object
'a=del&b=toggle&c=add') // Delete ?a, Toggle ?b, add ?c, update ?d (default)
// Returns /?b=3&c=3&c=6&d=7
```
## types
`g1.types(data)` returns the column data types. For example:
```js
var data = [
{a: 1, b: 1.1, c: 'c', d: '2014-04-04', e: true},
{a: 2, b: 2},
]
g1.types(data) // Returns {"a": "number", "b": "number", "c": "string", "d": "date", "e": "boolean"}
```
### types options
`types()` accepts 2 parameters:
- `data`: a list of objects
- `options`: a dictionary that may contain these keys:
- `convert`: converts values to the right type. For example, "1" is converted to 1. default: `false`
- `limit`: number of rows to evaluate. default: 1000
- `ignore`: list of values that should be ignored. default: `[null, undefined]`
Rules:
- Evaluate up to `limit` rows
- Ignore values that are keys in the `ignore` option. Only consider the rest
- If `convert` is `false`, then for each column:
- If all values are Date objects -> `date`
- Else if all values are numbers -> `number`
- Else if all values are strings -> `string`
- Else if all values are bools -> `boolean`
- Else if there are no values or is undefined or null -> `null`
- Else -> `mixed`
- Else if `convert` is `true`, then for each column:
- If all values can be converted to Date -> `date`
- Else if all values can be converted to numbers -> `number`
- Else if all values are bools -> `boolean`
- Else if there are no values or is undefined or null -> `null`
- Else -> `string`
## Interaction conventions
All interaction components use this naming convention:
- Interactions are enabled on a *container*, typically `body`. For example,
`$('body').urlfilter()`. Containers have these common attributes:
- `data-selector`: selector to identify triggers. e.g. `.urlfilter`, `.highlight`
- `data-target`: selector that all triggers act on by default
- `data-mode`: mode of interaction for all triggers
- `data-attr`: attribute that contains the interaction data, e.g. `href` for `.urlfilter`
- Interactions are triggered on a *trigger*. For example, `.urlfilter` for `$().urlfilter()`.
Clicking / hovering on / typing in a trigger triggers the interaction.
- `data-target`: selector that this trigger acts on
- `data-mode`: mode of interaction for this trigger
- Interactions change a *target*. For example, `urlfilter` changes `location.href` by default. The
`data-target` on containers and triggers define this.
- Interactions data is contained in an attribute. This is applied to the target. For example,
`.urlfilter` applied `href` to the target. The attribute name is stored in `data-attr`.
- Interactions have *modes*. This can be controlled using `data-mode=`.
All container `data-` attributes can also be passed as an option to the
function. For example, `<body data-selector=".link">` is the same as
`$('body').urlfilter({selector: '.link'})`.
## Contributing
Contributions are welcome.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment