Skip to content

Commit 1cf708b

Browse files
kanchana-mongodbjeff-allen-mongo
kanchana-mongodb
authored and
jeff-allen-mongo
committed
DOCSP-13926 doc for click events (#449)
* DOCSP-13926 doc for click events * DOCSP-13926 updates for copy review feedback * DOCSP-13926 updates per follow-up review * DOCSP-13926 updates per external review feedback
1 parent 3e80b03 commit 1cf708b

File tree

2 files changed

+301
-3
lines changed

2 files changed

+301
-3
lines changed

‎source/embedding-charts-sdk.txt

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,9 +34,17 @@ Installation
3434
------------
3535

3636
If you have a simple web app, you can reference the Embedding SDK from a
37-
script tag, and no installation is needed. If you are building a more complex
38-
web app and are using ``npm`` or ``yarn``, you can install the Embedding SDK
39-
so that it can be used directly from your script files.
37+
script tag, and no installation is needed. You can use the :abbr:`UMD
38+
(Universal Module Definition)` to run ``@mongodb-js/charts-embed-sdk``
39+
directly in the browser.
40+
41+
.. code-block:: none
42+
43+
<script src="https://unpkg.com/@mongodb-js/charts-embed-dom"></script>
44+
45+
If you are building a more complex web app and are using ``npm`` or
46+
``yarn``, you can install the Embedding SDK so that it can be used
47+
directly from your script files.
4048

4149
To install the embedding SDK with ``npm``, use the following command:
4250

@@ -99,5 +107,6 @@ Other examples are available in the :github:`MongoDB Embedding SDK Examples
99107
:titlesonly:
100108

101109
/configure-auth-providers
110+
/handle-click-events
102111
/embedding-tutorials
103112
Embedding SDK Reference <https://www.npmjs.com/package/@mongodb-js/charts-embed-dom>

‎source/handle-click-events.txt

Lines changed: 289 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,289 @@
1+
.. _handle-click-events:
2+
3+
===================
4+
Handle Click Events
5+
===================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. note::
16+
17+
Click Events in the `Charts Embedding SDK
18+
<https://github.com/mongodb-js/charts-embed-sdk>`__ is available as
19+
a beta feature. It is only available with Charts Embedding
20+
JavaScript SDK v1.2.0-beta.1.
21+
22+
The Charts Embedding JavaScript SDK includes a click event handler that
23+
allows you to subscribe to click events. When you click on a particular
24+
element on your chart, the click event handler captures details of the
25+
element that you clicked. Use this feature to build interactive
26+
experiences similar to the following in your application:
27+
28+
- Click on an element on a chart and open a pane with more details on
29+
the clicked element.
30+
- Create a filter for another chart.
31+
32+
.. _click-event-prereqs:
33+
34+
Prerequisites
35+
-------------
36+
37+
Before you begin, :ref:`install <embedding-charts-sdk>` the Charts
38+
Embedding JavaScript SDK.
39+
40+
.. _click-event-syntax:
41+
42+
Click Event Syntax
43+
------------------
44+
45+
The event handler takes an event type, ``click``, and a callback
46+
function that contains information about the click event and the
47+
clicked element as a single :ref:`payload <click-event-payload>`
48+
object. The click event handler syntax looks similar to the following:
49+
50+
.. code-block:: sh
51+
:copyable: false
52+
53+
chart.addEventListener("click", callback);
54+
55+
.. _click-event-payload:
56+
57+
Payload
58+
-------
59+
60+
You can use the click event payload to construct a custom filter that
61+
you can apply on another chart or charts in your application. The
62+
syntax of the payload object for the callback function looks similar to
63+
the following:
64+
65+
.. code-block:: sh
66+
:copyable: false
67+
68+
chart.addEventListener("click", (payload) => {
69+
// handle events
70+
}
71+
72+
The following example payload object shows the elements inside the
73+
payload:
74+
75+
.. example::
76+
77+
.. code-block:: sh
78+
:copyable: false
79+
80+
chart.addEventListener("click", (payload) => {
81+
"chartId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
82+
"event": { // information about the mouse event. For example:
83+
"type": "click", // event type
84+
85+
"altKey": false, // modifier keys
86+
"ctrlKey": false,
87+
"shiftKey": false,
88+
"metaKey": false,
89+
90+
"offsetX": 152, // element coordinates
91+
"offsetY": 176,
92+
93+
"clientX": 172, // coordinates from application viewpoint
94+
"clientY": 241,
95+
96+
"pageX": 172, // coordinates relative to the page
97+
"pageY": 241,
98+
99+
"screenX": 172, // coordinates relative to screen
100+
"screenY": 312
101+
},
102+
"data": { // information about the clicked chart element. For example:
103+
"y": {
104+
"label": "unwind array 'genres'",
105+
"value": "Adventure"
106+
},
107+
"x": {
108+
"label": "count ( _id )",
109+
"value": 659
110+
},
111+
"color": {
112+
"label": "year",
113+
"value": "2000 - 2010",
114+
"lowerBound": 2000,
115+
"upperBound": 2010
116+
}
117+
},
118+
selectionFilter: {
119+
// category data expressed as MQL filter query that
120+
// interactive filters would output to filter other charts.
121+
// For example:
122+
123+
genres: 'Adventure',
124+
year: {
125+
$gte: 2000,
126+
$lt: 2010,
127+
},
128+
},
129+
"target": { // information about the clicked target. For example:
130+
"type": "rect", // type of mark, such as rect, line, etc.
131+
"role": "mark", // role of mark, such as mark, legend, etc.
132+
"fill": "#8CB6F2" // fill color of the mark
133+
},
134+
"apiVersion": 1 // API version of event payload
135+
});
136+
137+
To learn more about the elements inside the payload object, see:
138+
139+
- :ref:`click-event-payload-event`
140+
- :ref:`click-event-payload-data`
141+
- :ref:`click-event-payload-selection-filter`
142+
- :ref:`click-event-payload-target`
143+
144+
.. _click-event-payload-event:
145+
146+
``event`` Element
147+
~~~~~~~~~~~~~~~~~
148+
149+
The ``event`` element of the :ref:`payload <click-event-payload>`
150+
contains information about the mouse event including:
151+
152+
- The type of mouse event, which must be ``click``
153+
- The modifier keys used to trigger a click event such as ``altKey``,
154+
``ctrlKey``, ``shiftKey``, ``metaKey``
155+
- The ``X`` and ``Y`` coordinates:
156+
157+
- Relative to the canvas element of the chart
158+
- From the application viewpoint
159+
- Relative to the page
160+
- Relative to the screen
161+
162+
.. _click-event-payload-data:
163+
164+
``data`` Element
165+
~~~~~~~~~~~~~~~~
166+
167+
The ``data`` element of the :ref:`payload <click-event-payload>`
168+
contains information about the clicked chart element. For each encoded
169+
data field (``x``, ``y``, ``series``, ``intensity``, ``color``,
170+
``shape``, ``size``, ``label``, ``arc``, ``value``, ``target``,
171+
``number``, ``display``, ``text``, ``location``), the ``data`` element
172+
contains:
173+
174+
- The channel ``label``
175+
- The ``value`` of the clicked element
176+
- The lower bound for numeric or date binning only
177+
178+
.. _click-event-payload-selection-filter:
179+
180+
``selectionFilter`` Element
181+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
182+
183+
The ``selectionFilter`` element of the :ref:`payload
184+
<click-event-payload>` must contain a valid :abbr:`MQL (MongoDB Query
185+
Language)` filter document, which represents the filter that
186+
corresponds to the clicked mark's category channels or ``x`` value
187+
channel on a continuous chart. You can modify or implement your own
188+
``selectionFilter``.
189+
190+
The filter object represents a single clicked item:
191+
192+
- A string or unbinned number or date, which becomes an equality match
193+
query ``({field: value})`` or a query using ``$eq``, ``$ne``, ``$in``, or ``$nin`` operators.
194+
- A binned number or date, which becomes a query using ``gt``,
195+
``$gte``, ``$lt``, or ``lte`` operators. Periodic dates are ignored.
196+
197+
.. example::
198+
199+
.. code-block:: sh
200+
:copyable: false
201+
202+
{ field: 'value' }
203+
{ field1: 'value1', field2: 'value2' }
204+
{ field: { $in: [ 'a', 'b', 'c' ] } }
205+
{ field: { $nin: [ 'x', 'y', 'z' ] } }
206+
{ field: { $gt: 10 } }
207+
{ field: { $gt: 13, $lte: 30 } }
208+
{ field: { $gt: Date("2020-01-01"), $lt: Date("2020-03-31") } }
209+
210+
The ``selectionFilter`` document can have several key and value
211+
filters. For example, if a mark of a multi-series chart is clicked, the
212+
filter document contains both the category and series filter pairs.
213+
Each filter must reference the actual data source fields used and not
214+
their labels.
215+
216+
.. _click-event-payload-target:
217+
218+
``target`` Element
219+
~~~~~~~~~~~~~~~~~~
220+
221+
The ``target`` element of the :ref:`payload <click-event-payload>`
222+
contains information about the clicked target including:
223+
224+
- The type of mark, such as ``rect``, ``line``, ``arc``, ``symbol``,
225+
etc.
226+
- The role of mark, such as ``mark``, ``legend``, ``axis-label``, etc.
227+
- The fill color of the mark
228+
229+
.. _click-event-egs:
230+
231+
Examples
232+
--------
233+
234+
The Charts Embedding JavaScript SDK includes examples that demonstrate
235+
common uses for click events in an application. The first example shows
236+
basic click events and payload handling. The second example shows
237+
interactive filtering of clicked chart elements.
238+
239+
To learn more about installing the Embedding SDK and running the
240+
example app with your own data or sample data, see `MongoDB Charts
241+
Embedding Example for Click Events on GitHub
242+
<https://github.com/mongodb-js/charts-embed-sdk/tree/master/examples/click-events-basic>`__.
243+
Each example app is configured with a chart ID and base URL which are
244+
particular to the app. Be sure to configure your own apps with the
245+
correct chart ID and base URL.
246+
247+
.. _click-event-eg-basic:
248+
249+
Basic Handling of Click Events
250+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
251+
252+
In the `example app
253+
<https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/click-events-basic>`__
254+
for basic handling of click events, when you click on an element on the
255+
``Movie Genres`` chart, the click event handler displays data based on
256+
the clicked element.
257+
258+
Each time you click on an element in the chart, the click event
259+
listener refreshes the ``payload`` to reflect data from the ``x`` and
260+
``y`` axis. When you click on an element that represents a specific
261+
genre and decade in the ``Movie Genres`` chart, the ``Clicked Element``
262+
and ``Full Event Payload`` displays details on that movie genre and
263+
decade including:
264+
265+
- Fields that represent data for the clicked element.
266+
- Mark type, role, and fill color.
267+
268+
Refer to the example app to view the full event payload.
269+
270+
.. _click-event-eg-interactive:
271+
272+
Interactive Filtering for Click Events
273+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
274+
275+
In the `example app
276+
<https://codesandbox.io/s/github/mongodb-js/charts-embed-sdk/tree/master/examples/click-events-filtering>`__
277+
for interactive filtering, when you click on an element on the ``Movie
278+
Genres`` chart, the embedding SDK generates a filter based on the
279+
element on which you clicked and then applies the filter to a second
280+
chart.
281+
282+
The click event listener generates a filter based on the ``y`` axis,
283+
which represents the movie genres, and the lower and upper bound range,
284+
which represents the decade. Each time you click on an element that
285+
represents a specific genre and decade on the ``Movie Genres`` chart,
286+
the ``Movie Details`` data table is filtered by the clicked element and
287+
changes to display the movies available in that genre and decade.
288+
289+
Refer to the example app to view the full event payload.

0 commit comments

Comments
 (0)