Commit 2d0cfd28 authored by S Anand's avatar S Anand
Browse files

DOC: refactor documentation [skip ci]

parent 5076c788
Pipeline #68408 skipped
......@@ -17,35 +17,41 @@ functions. [g.js](dist/g.js) is an un-minified version for debugging.
Interactions:
- [urlfilter.min.js](dist/urlfilter.min.js): URL filtering library
- URL filtering: [urlfilter.min.js](dist/urlfilter.min.js)
- [$.urlfilter](#urlfilter) changes URL query parameters when clicked. Used to filter data.
- [g1.url.parse](#urlparse) parses a URL into a structured object
- [g1.url.join](#urljoin) joins two URLs
- [g1.url.update](#urlupdate) updates a URL's query parameters
- [urlchange.min.js](dist/urlchange.min.js): URL state change events
- [g1.url.parse](#g1urlparse) parses a URL into a structured object
- [url.join](#urljoin) joins two URLs
- [url.update](#urlupdate) updates a URL's query parameters
- URL state change events: [urlchange.min.js](dist/urlchange.min.js)
- [$.urlchange](#urlchange) listens to hash changes and routes events
- [highlight.min.js](dist/highlight.min.js): highlighting library
- Highlighting: [highlight.min.js](dist/highlight.min.js)
- [$.highlight](#highlight) toggles classes on elements when clicked or hover
Data components:
Components:
- [formhandler.min.js](dist/formhandler.min.js): Table renderer using [FormHandler](https://learn.gramener.com/guide/formhandler/)
- Table renderer using [FormHandler](https://learn.gramener.com/guide/formhandler/): [formhandler.min.js](dist/formhandler.min.js)
- [$.formhandler](#formhandler) renders a HTML table from a [FormHandler URL](https://learn.gramener.com/guide/formhandler/)
- [leaflet.min.js](dist/leaflet.min.js): Leaflet utilities
- Leaflet utilities: [leaflet.min.js](dist/leaflet.min.js)
- [L.TopoJSON](#ltopojson) loads TopoJSON files just like GeoJSON. Requires [topojson](https://github.com/topojson/topojson)
- Sand dance transitions: [sanddance.min.js](dist/sanddance.min.js)
- [g1.sanddance](#g1sanddance) moves DOM elements smoothly based on data
- Map viewer component: [mapviewer.min.js](dist/mapviewer.min.js)
- [g1.mapviewer](#g1mapviewer) renders leaflet maps and simplifies adding layers from data
Utilities:
- [template.min.js](dist/template.min.js): template library
- Template library: [template.min.js](dist/template.min.js)
- [$.template](#template) renders lodash templates. Requires [lodash](https://lodash.com/)
- [event.min.js](dist/event.min.js): event library
- Event library: [event.min.js](dist/event.min.js)
- [$.dispatch](#dispatch) is like [trigger](https://api.jquery.com/trigger/) but sends a native event (triggers non-jQuery events too)
- [datafilter.min.js](dist/datafilter.min.js): filtering data library
- [g1.datafilter](#datafilter) filters the data based on the options
- [types.min.js](dist/types.min.js): type detection library
- [g1.types](#types) returns the data types of columns in a DataFrames
- Data filtering library: [datafilter.min.js](dist/datafilter.min.js)
- [g1.datafilter](#g1datafilter) filters the data based on the options
- Type detection library: [types.min.js](dist/types.min.js)
- [g1.types](#g1types) returns the data types of columns in a DataFrames
## $.urlfilter
<!-- ----------------------------------------------------------------------- -->
# $.urlfilter
Example:
......@@ -88,7 +94,7 @@ For example:
</script>
```
### $.urlfilter attributes
## $.urlfilter attributes
URLFilter triggers use these attributes:
......@@ -115,16 +121,27 @@ URLFilter containers uses these attributes:
every `.urlfilter` trigger.
## url.parse
## $.urlfilter events
- `urlfilter` is fired on the trigger when the URL is changed.
Note: if the page is reloaded (e.g. if there is no `data-target=`),
the page is reloaded and the event is lost. 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
<!-- ----------------------------------------------------------------------- -->
# g1.url.parse
`g1.url` provides URL manipulation utilities.
## url attributes
```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 |
......@@ -167,7 +184,7 @@ var url = g1.url.parse('?a=1&a=2&b=3%2E&d#hash')
These attributes are **not mutable**. To change the URL, use
[url.join](#urljoin) or [url.update](#urlupdate).
### url object methods
## url.toString
The url object has a `.toString()` method that converts the object back into a
string.
......@@ -245,7 +262,8 @@ g1.url.parse('/?a=1&b=2&c=3&d=4') // Update this URL
// Returns /?b=3&c=3&c=6&d=7
```
## Interaction conventions
<!-- ----------------------------------------------------------------------- -->
# Interaction conventions
All interaction components use this naming convention:
......@@ -271,17 +289,8 @@ 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.
Note: if the page is reloaded (e.g. if there is no `data-target=`),
the page is reloaded and the event is lost. 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
## $.urlchange
<!-- ----------------------------------------------------------------------- -->
# $.urlchange
$.urlchange triggers custom events when the URL changes. This makes it easy to
build URL-driven applications.
......@@ -333,7 +342,7 @@ Examples:
- `.on('#?x', function(e, val) { val == '1' && e.vals == ['1', '2'] })`
- The `#?x` event is fired since x has a new value
### $.urlchange events
## $.urlchange events
- `#?` is fired when the URL hash changes. Event attributes are:
- `hash`: a [g1.url.parse](#urlparse) object that holds the parsed URL hash
......@@ -344,7 +353,8 @@ Examples:
- `val`: the first value of `vals`.
## $.dropdown
<!-- ----------------------------------------------------------------------- -->
# $.dropdown
Dropdown component that integrates well with g1.urlfilter
......@@ -411,7 +421,7 @@ To use bootstrap-select options, use `options:`
```
### $.dropdown events
## $.dropdown events
- `load` is triggered after dropdown is rendered
- `change` is triggered whenever dropdown value is changed
......@@ -433,7 +443,7 @@ To use bootstrap-select options, use `options:`
```
### $.dropdown options
## $.dropdown options
- `data`: Array of values.
- `url`: End point that returns the `data`. If `data:` is also given, `data` takes priority.
- `target`: defines how URL is updated. Can be `''` (Default), `#` or `pushState`
......@@ -442,7 +452,8 @@ To use bootstrap-select options, use `options:`
- `options`: Supports same options as [bootstrap-select options](https://silviomoreto.github.io/bootstrap-select/options/)
## $.highlight
<!-- ----------------------------------------------------------------------- -->
# $.highlight
Highlight elements when hovering on or clicking another element.
......@@ -459,7 +470,7 @@ Example:
</script>
```
### $.highlight attributes
## $.highlight attributes
Highlight triggers use these attributes:
......@@ -475,13 +486,14 @@ Highlight containers use these attributes:
- `data-attr` is the attribute that defines classes to toggle. Default: `data-classes`
- `data-classes=` is the same as specifiying the data-classes on every highlighter. Default: `active`
### $.highlight events
## $.highlight events
- `highlight` is fired on the trigger when activated. Attributes:
- `target`: elements that match the `data-target=` selector
## types
<!-- ----------------------------------------------------------------------- -->
# g1.types
`g1.types(data)` returns the column data types. For example:
......@@ -493,7 +505,7 @@ var data = [
g1.types(data) // Returns {"a": "number", "b": "number", "c": "string", "d": "date", "e": "boolean"}
```
### types options
## g1.types options
`types()` accepts 2 parameters:
......@@ -522,7 +534,8 @@ Rules:
- Else -> `string`
## g1.datafilter
<!-- ----------------------------------------------------------------------- -->
# g1.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.
......@@ -602,7 +615,8 @@ g1.datafilter(data2, {
[formhandler-filters]: https://learn.gramener.com/guide/formhandler/#formhandler-filters
## $.formhandler
<!-- ----------------------------------------------------------------------- -->
# $.formhandler
An interactive table component for [FormHandler][formhandler] data.
......@@ -620,7 +634,7 @@ In the above example, `data-page-size="10"` over-rides `pageSize: 20`.
[formhandler]: https://learn.gramener.com/guide/formhandler/
### $.formhandler options
## $.formhandler options
The full list of options is below. Simple options can be specified as `data-` attributes as well.
......@@ -762,7 +776,7 @@ Features to be implemented:
- Full text search
- URL targets other than '#', e.g. pushState
### $.formhandler events
## $.formhandler events
- `load` is fired on the source when the template is rendered. Attributes:
- `formdata`: the FormHandler data
......@@ -774,7 +788,7 @@ Features to be implemented:
- `editmode` is fired on the source when the Edit button is clicked and table changes to edit mode.
### $.formhandler examples
## $.formhandler examples
Render a table using the FormHandler at `./data`:
......@@ -885,9 +899,8 @@ In edit mode, show HTML input bindings like Dropdown, Datepicker, Number fields.
</script>
```
## $.template
<!-- ----------------------------------------------------------------------- -->
# $.template
```html
<script type="text/html">Your platform is <%= navigator.userAgent %></script>
......@@ -918,7 +931,7 @@ using as `.template({var1: value, var2: value, ...})`. For example:
To re-render the template, run `.template(data)` again with different data.
### $.template options
## $.template options
To re-use the template or render the same template on a different DOM node,
run `.template(data, {target: selector})`. This allows you to declare templates
......@@ -960,7 +973,7 @@ an existing target. For example:
```
### $.template attributes
## $.template attributes
Template containers can have an `src=` attribute that loads the template from a file:
......@@ -1009,7 +1022,7 @@ Or you can directly render templates using
</script>
```
### $.template events
## $.template events
- `template` is fired on the source when the template is rendered. Attributes:
- `templatedata`: the passed data
......@@ -1027,7 +1040,8 @@ $('script[type="text/html"]')
.template() // Trigger the template AFTER binding the event handler
```
## $.dispatch
<!-- ----------------------------------------------------------------------- -->
# $.dispatch
Triggers a native JavaScript event. For example:
......@@ -1038,7 +1052,7 @@ $('a.action').dispatch('click')
sends a click to `a.action`. Like [$.trigger](https://api.jquery.com/trigger/),
but this will fire non-jQuery event handlers as well.
### $.dispatch options
## $.dispatch options
You can add an optional dict as the second parameter. It can have any
[event properties](https://developer.mozilla.org/en-US/docs/Web/API/Event#Properties)
......@@ -1055,7 +1069,8 @@ $('a.action').dispatch('click', {bubbles: true, cancelable: false})
https://developer.mozilla.org/en-US/docs/Web/Guide/Events/Creating_and_triggering_events
## L.TopoJSON
<!-- ----------------------------------------------------------------------- -->
# L.TopoJSON
```js
var layer = new L.TopoJSON(topojson_data).addTo(map)
......@@ -1075,11 +1090,12 @@ $.get('topojson-file.json')
```
## sanddance
<!-- ----------------------------------------------------------------------- -->
# g1.sanddance
Transitions elements with flexible timing controls.
### sanddance options
## g1.sanddance options
It accepts 2 parameters
......@@ -1128,7 +1144,7 @@ var selection_filtered = g1.sanddance({fill: 'red'}, {duration: 100, filter: fun
selection.call(selection_filtered)
```
### sanddance.chain
## g1.sanddance.chain
To apply a sequence of sanddances one after another, use `g1.sanddance.chain`. For example:
......@@ -1142,9 +1158,7 @@ selection.call(
)
```
### sanddance layouts
#### 1. grid
## g1.sanddance grid layout
Returns a sanddance that moves elements into a grid. Usage:
......@@ -1230,7 +1244,7 @@ selection.call(
)
```
#### 2. hexpack
## g1.sanddance hexpack layout
Returns a sanddance that moves elements into a hexpack. Usage:
......@@ -1250,7 +1264,7 @@ selection.call(
```
The values can also be specified as a scale config and the options definitions are same as grid.
### sanddance methods
## g1.sanddance methods
`sanddance.update(new_attrs, new_options)` returns a new sanddance that updates
the old `attrs` with `new_attrs` and the old `options` with `new_options`.
......@@ -1265,7 +1279,7 @@ g1.sanddance({}, { delay: 100 }).update({}, { duration: 100 }),
g1.sanddance({}, { duration: 100, delay: 100 })
```
### sanddance events
## g1.sanddance events
These events are triggered by the sanddance object.
......@@ -1285,7 +1299,8 @@ selection.call(
)
```
## g1.mapviewer
<!-- ----------------------------------------------------------------------- -->
# g1.mapviewer
Mapviewer is an abstraction over [Leaflet](http://leafletjs.com/) that can
create common GIS applications using configurations.
......@@ -1506,7 +1521,7 @@ Drilldown feature example:
**Note**: You can use `type: 'topojson'` when loading TopoJSON maps.
### g1.mapviewer options
## g1.mapviewer options
- `id`: ID of the map DOM element (example: `mapid`), or the DOM element
- `map`:
......@@ -1587,19 +1602,20 @@ Drilldown feature example:
- `shapePadding`: padding of legend cell. Default `20`
- `labelOffset`: value to determine distance of label from each legend cell. Default `20`
### g1.mapviewer methods
## g1.mapviewer methods
`fitToLayer(layerName, options)`
Zooms map view to fit the layer. Supports same options as [fitBounds options](http://leafletjs.com/reference-1.3.0.html#fitbounds-options)
`zoomHandler(layerName, minZoomLevel, maxZoomLevel(optional) )`
Shows the layer with `layerName` only between `minZoomLevel` and `maxZoomLevel`.
### g1.mapviewer events
## g1.mapviewer events
- `layersloaded` is fired when all layers are saved in mapviewer.gLayers (used interally).
- tooltip is rendered on each layer only after `layersload` is fired
- `layerName + 'loaded'` is fired for each layer with name as `layerName`
<!-- ----------------------------------------------------------------------- -->
## 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