Skip to content
GitLab
Menu
Projects
Groups
Snippets
Loading...
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
cto
g1
Commits
2d0cfd28
Commit
2d0cfd28
authored
Nov 24, 2018
by
S Anand
Browse files
DOC: refactor documentation [skip ci]
parent
5076c788
Pipeline
#68408
skipped
Changes
1
Pipelines
1
Hide whitespace changes
Inline
Side-by-side
README.md
View file @
2d0cfd28
...
...
@@ -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
](
#
g1
urlparse
)
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 c
omponents:
C
omponents:
-
[
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
](
#
g1
datafilter
)
filters the data based on the options
-
Type detection library:
[
types.min.js
](
dist/types.min.js
)
-
[
g1.types
](
#
g1
types
)
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.
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment