Commit 3825bd1b authored by Phil Hughes's avatar Phil Hughes

Merge branch...

Merge branch '57382-add-documentation-how-to-track-an-event-to-frontend-documentation' into 'master'

Resolve "Add documentation "How to track an event" to Frontend documentation"

Closes #57382

See merge request gitlab-org/gitlab-ce!24995
parents d5f4a8dc 06934627
# Frontend Development Guidelines # Frontend Development Guidelines
> **Notice:** > **Notice:**
We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md) > We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md)
This document describes various guidelines to ensure consistency and quality This document describes various guidelines to ensure consistency and quality
across GitLab's frontend team. across GitLab's frontend team.
...@@ -32,32 +32,41 @@ For our currently-supported browsers, see our [requirements][requirements]. ...@@ -32,32 +32,41 @@ For our currently-supported browsers, see our [requirements][requirements].
--- ---
## [Development Process](development_process.md) ## [Development Process](development_process.md)
How we plan and execute the work on the frontend. How we plan and execute the work on the frontend.
## [Architecture](architecture.md) ## [Architecture](architecture.md)
How we go about making fundamental design decisions in GitLab's frontend team How we go about making fundamental design decisions in GitLab's frontend team
or make changes to our frontend development guidelines. or make changes to our frontend development guidelines.
## [Testing](../testing_guide/frontend_testing.md) ## [Testing](../testing_guide/frontend_testing.md)
How we write frontend tests, run the GitLab test suite, and debug test related How we write frontend tests, run the GitLab test suite, and debug test related
issues. issues.
## [Design Patterns](design_patterns.md) ## [Design Patterns](design_patterns.md)
Common JavaScript design patterns in GitLab's codebase. Common JavaScript design patterns in GitLab's codebase.
## [Vue.js Best Practices](vue.md) ## [Vue.js Best Practices](vue.md)
Vue specific design patterns and practices. Vue specific design patterns and practices.
## [Vuex](vuex.md) ## [Vuex](vuex.md)
Vuex specific design patterns and practices. Vuex specific design patterns and practices.
## [Axios](axios.md) ## [Axios](axios.md)
Axios specific practices and gotchas. Axios specific practices and gotchas.
## [GraphQL](graphql.md) ## [GraphQL](graphql.md)
How to use GraphQL How to use GraphQL
## [Icons and Illustrations](icons.md) ## [Icons and Illustrations](icons.md)
How we use SVG for our Icons and Illustrations. How we use SVG for our Icons and Illustrations.
## [Components](components.md) ## [Components](components.md)
...@@ -70,7 +79,7 @@ How we use UI components. ...@@ -70,7 +79,7 @@ How we use UI components.
### [JavaScript Style Guide](style_guide_js.md) ### [JavaScript Style Guide](style_guide_js.md)
We use eslint to enforce our JavaScript style guides. Our guide is based on We use eslint to enforce our JavaScript style guides. Our guide is based on
the excellent [Airbnb][airbnb-js-style-guide] style guide with a few small the excellent [Airbnb][airbnb-js-style-guide] style guide with a few small
changes. changes.
...@@ -81,23 +90,26 @@ Our SCSS conventions which are enforced through [scss-lint][scss-lint]. ...@@ -81,23 +90,26 @@ Our SCSS conventions which are enforced through [scss-lint][scss-lint].
--- ---
## [Performance](performance.md) ## [Performance](performance.md)
Best practices for monitoring and maximizing frontend performance. Best practices for monitoring and maximizing frontend performance.
--- ---
## [Security](security.md) ## [Security](security.md)
Frontend security practices. Frontend security practices.
--- ---
## [Accessibility](accessibility.md) ## [Accessibility](accessibility.md)
Our accessibility standards and resources. Our accessibility standards and resources.
## [Internationalization (i18n) and Translations](../i18n/externalization.md) ## [Internationalization (i18n) and Translations](../i18n/externalization.md)
Frontend internationalization support is described in [this document](../i18n/). Frontend internationalization support is described in [this document](../i18n/).
The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available. The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available.
[rails]: http://rubyonrails.org/ [rails]: http://rubyonrails.org/
[haml]: http://haml.info/ [haml]: http://haml.info/
[hamlit]: https://github.com/k0kubun/hamlit [hamlit]: https://github.com/k0kubun/hamlit
...@@ -116,6 +128,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the ...@@ -116,6 +128,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the
--- ---
## [DropLab](droplab/droplab.md) ## [DropLab](droplab/droplab.md)
Our internal `DropLab` dropdown library. Our internal `DropLab` dropdown library.
- [DropLab](droplab/droplab.md) - [DropLab](droplab/droplab.md)
......
# Event Tracking
We use [Snowplow](https://github.com/snowplow/snowplow) for tracking custom events.
## Generic tracking function
In addition to Snowplow's built-in method for tracking page views, we use a generic tracking function which enables us to selectively apply listeners to events.
The generic tracking function can be imported in EE-specific JS files as follows:
```javascript
import { trackEvent } from `ee/stats`;
```
This gives the user access to the `trackEvent` method, which takes the following parameters:
| parameter | type | description | required |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `category` | string | Describes the page that you're capturing click events on. Unless infeasible, please use the Rails page attribute `document.body.dataset.page` by default. | true |
| `eventName` | string | Describes the action the user is taking. The first word should always describe the action. For example, clicks should be `click` and activations should be `activate`. Use underscores to describe what was acted on. For example, activating a form field would be `activate_form_input`. Clicking on a dropdown is `click_dropdown`. | true |
| `additionalData` | object | Additional data such as `label`, `property`, and `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). | false |
Read more about instrumentation and the taxonomy in the [Product Handbook](https://about.gitlab.com/handbook/product/feature-instrumentation).
### Tracking in `.js` and `.vue` files
The most simple use case is to add tracking programmatically to an event of interest in Javascript.
The following example demonstrates how to track a click on a button in Javascript by calling the `trackEvent` method explicitly:
```javascript
import { trackEvent } from `ee/stats`;
trackEvent('dashboard:projects:index', 'click_button', {
label: 'create_from_template',
property: 'template_preview',
value: 'rails',
});
```
### Tracking in HAML templates
Sometimes we want to track clicks for multiple elements on a page. Creating event handlers for all elements could soon turn into a tedious task.
There's a more convenient solution to this problem. When working with HAML templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have both `data-track-label` and `data-track-event` attributes assigned get marked for event tracking. All we have to do is call the `bindTrackableContainer` method on a container which allows for better scoping.
Below is an example of `data-track-*` attributes assigned to a button in HAML:
```ruby
%button.btn{ data: { track_label: "create_from_template", track_property: "template_preview", track_event: "click_button", track_value: "my-template" } }
```
By calling `bindTrackableContainer('.my-container')`, click handlers get bound to all elements located in `.my-container` provided that they have the necessary `data-track-*` attributes assigned to them.
```javascript
import Stats from 'ee/stats';
document.addEventListener('DOMContentLoaded', () => {
Stats.bindTrackableContainer('.my-container', 'category');
});
```
The second parameter in `bindTrackableContainer` is optional. If omitted, the value of `document.body.dataset.page` will be used as category instead.
Below is a list of supported `data-track-*` attributes:
| attribute | description | required |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `data-track-label` | The `label` in `trackEvent` | true |
| `data-track-event` | The `eventName` in `trackEvent` | true |
| `data-track-property` | The `property` in `trackEvent`. If omitted, an empty string will be used as a default value. | false |
| `data-track-value` | The `value` in `trackEvent`. If omitted, this will be `target.value` or empty string. For checkboxes, the default value being tracked will be the element's checked attribute if `data-track-value` is omitted. | false |
Since Snowplow is an Enterprise Edition feature, it's necessary to create a CE backport when adding `data-track-*` attributes to HAML templates in most cases.
...@@ -27,6 +27,10 @@ Learn about all the internal JavaScript modules that make up our frontend. ...@@ -27,6 +27,10 @@ Learn about all the internal JavaScript modules that make up our frontend.
Style guides to keep our code consistent. Style guides to keep our code consistent.
## [Event Tracking with Snowplow](event_tracking.md)
How we use Snowplow to track custom events.
## [Tips](tips.md) ## [Tips](tips.md)
Tips from our frontend team to develop more efficiently and effectively. Tips from our frontend team to develop more efficiently and effectively.
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