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

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
> **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/
> 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/
This document describes various guidelines to ensure consistency and quality
across GitLab's frontend team.
......@@ -32,32 +32,41 @@ For our currently-supported browsers, see our [requirements][requirements].
## [Development Process](
How we plan and execute the work on the frontend.
## [Architecture](
How we go about making fundamental design decisions in GitLab's frontend team
or make changes to our frontend development guidelines.
## [Testing](../testing_guide/
How we write frontend tests, run the GitLab test suite, and debug test related
## [Design Patterns](
Common JavaScript design patterns in GitLab's codebase.
## [Vue.js Best Practices](
Vue specific design patterns and practices.
## [Vuex](
Vuex specific design patterns and practices.
## [Axios](
Axios specific practices and gotchas.
## [GraphQL](
How to use GraphQL
## [Icons and Illustrations](
How we use SVG for our Icons and Illustrations.
## [Components](
......@@ -70,7 +79,7 @@ How we use UI components.
### [JavaScript Style Guide](
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
......@@ -81,23 +90,26 @@ Our SCSS conventions which are enforced through [scss-lint][scss-lint].
## [Performance](
Best practices for monitoring and maximizing frontend performance.
## [Security](
Frontend security practices.
## [Accessibility](
Our accessibility standards and resources.
## [Internationalization (i18n) and Translations](../i18n/
Frontend internationalization support is described in [this document](../i18n/).
The [externalization part of the guide](../i18n/ explains the helpers/methods available.
......@@ -116,6 +128,7 @@ The [externalization part of the guide](../i18n/ explains the
## [DropLab](droplab/
Our internal `DropLab` dropdown library.
- [DropLab](droplab/
# Event Tracking
We use [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:
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 `` 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]( | false |
Read more about instrumentation and the taxonomy in the [Product Handbook](
### 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:
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:
%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.
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 `` 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.
Style guides to keep our code consistent.
## [Event Tracking with Snowplow](
How we use Snowplow to track custom events.
## [Tips](
Tips from our frontend team to develop more efficiently and effectively.
Supports Markdown
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