diff options
Diffstat (limited to 'doc/development/fe_guide')
| -rw-r--r-- | doc/development/fe_guide/components.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/design_patterns.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/development_process.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/event_tracking.md | 91 | ||||
| -rw-r--r-- | doc/development/fe_guide/frontend_faq.md | 13 | ||||
| -rw-r--r-- | doc/development/fe_guide/graphql.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/index.md | 4 | ||||
| -rw-r--r-- | doc/development/fe_guide/performance.md | 2 | ||||
| -rw-r--r-- | doc/development/fe_guide/style_guide_js.md | 6 | ||||
| -rw-r--r-- | doc/development/fe_guide/style_guide_scss.md | 10 | ||||
| -rw-r--r-- | doc/development/fe_guide/vue.md | 10 | ||||
| -rw-r--r-- | doc/development/fe_guide/vuex.md | 2 |
12 files changed, 35 insertions, 111 deletions
diff --git a/doc/development/fe_guide/components.md b/doc/development/fe_guide/components.md index 096ce8ca25a..e88827f78c1 100644 --- a/doc/development/fe_guide/components.md +++ b/doc/development/fe_guide/components.md @@ -44,7 +44,7 @@ See also the [corresponding UX guide](https://design.gitlab.com/#/components/dro See also the [corresponding UX guide](https://design.gitlab.com/#/components/modals). -We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue) +We have a reusable Vue component for modals: [vue_shared/components/gl_modal.vue](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/javascripts/vue_shared/components/gl_modal.vue) Here is an example of how to use it: diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index 2f372f783f5..0893299540f 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -77,4 +77,4 @@ new Foo({ container: '.my-element' }); You can find an example of the above in this [class][container-class-example]; -[container-class-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js +[container-class-example]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js diff --git a/doc/development/fe_guide/development_process.md b/doc/development/fe_guide/development_process.md index 9224a2548ab..41513e6d57e 100644 --- a/doc/development/fe_guide/development_process.md +++ b/doc/development/fe_guide/development_process.md @@ -23,7 +23,7 @@ Please use your best judgement when to use it and please contribute new points t - [ ] Are all necessary UX specifications available that you will need in order to implement? Are there new UX components/patterns in the designs? Then contact the UI component team early on. How should error messages or validation be handled? - [ ] **Library usage** Use Vuex as soon as you have even a medium state to manage, use Vue router if you need to have different views internally and want to link from the outside. Check what libraries we already have for which occasions. - [ ] **Plan your implementation:** - - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-ce/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it. + - [ ] **Architecture plan:** Create a plan aligned with GitLab's architecture, how you are going to do the implementation, for example Vue application setup and its components (through [onion skinning](https://gitlab.com/gitlab-org/gitlab-foss/issues/35873#note_39994091)), Store structure and data flow, which existing Vue components can you reuse. It's a good idea to go through your plan with another engineer to refine it. - [ ] **Backend:** The best way is to kickoff the implementation in a call and discuss with the assigned Backend engineer what you will need from the backend and also when. Can you reuse existing API's? How is the performance with the planned architecture? Maybe create together a JSON mock object to already start with development. - [ ] **Communication:** It also makes sense to have for bigger features an own slack channel (normally called #f_{feature_name}) and even weekly demo calls with all people involved. - [ ] **Dependency Plan:** Are there big dependencies in the plan between you and others, then maybe create an execution diagram to show what is blocking which part and the order of the different parts. diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md index 1b417d4c8c2..13f107eebb1 100644 --- a/doc/development/fe_guide/event_tracking.md +++ b/doc/development/fe_guide/event_tracking.md @@ -1,88 +1,5 @@ -# Event tracking +--- +redirect_to: '../event_tracking/index.md' +--- -GitLab provides `Tracking`, an interface that wraps -[Snowplow](https://github.com/snowplow/snowplow) for tracking custom events. -It uses Snowplow's custom event tracking functions. - -The tracking interface can be imported in JS files as follows: - -```javascript -import Tracking from `~/tracking`; -``` - -## Tracking in HAML or Vue templates - -To avoid having to do create a bunch of custom javascript event handlers, when working within HAML or Vue templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have a `data-track-event` attribute to automatically have event tracking bound. - -Below is an example of `data-track-*` attributes assigned to a button in HAML: - -```haml -%button.btn{ data: { track_event: "click_button", track_label: "template_preview", track_property: "my-template", track_value: "" } } -``` - -We can then setup tracking for large sections of a page, or an entire page by telling the Tracking interface to bind to it. - -```javascript -import Tracking from '~/tracking'; - -// for the entire document -new Tracking().bind(); - -// for a container element -document.addEventListener('DOMContentLoaded', () => { - new Tracking('my_category').bind(document.getElementById('my-container')); -}); - -``` - -When you instantiate a Tracking instance you can provide a category. If none is provided, `document.body.dataset.page` will be used. When you bind the Tracking instance you can provide an element. If no element is provided to bind to, the `document` is assumed. - -Below is a list of supported `data-track-*` attributes: - -| attribute | required | description | -|:----------------------|:---------|:------------| -| `data-track-event` | true | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. | -| `data-track-label` | false | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). | -| `data-track-property` | false | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). | -| `data-track-value` | false | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. | - -## Tracking in raw Javascript - -Custom events can be tracked by directly calling the `Tracking.event` static function, which accepts the following arguments: - -| argument | type | default value | description | -|:-----------|:-------|:---------------------------|:------------| -| `category` | string | document.body.dataset.page | Page or subsection of a page that events are being captured within. | -| `event` | string | 'generic' | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. | -| `data` | 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). These will be set as empty strings if you don't provide them. | - -Tracking can be programmatically added to an event of interest in Javascript, and the following example demonstrates tracking a click on a button by calling `Tracking.event` manually. - -```javascript -import Tracking from `~/tracking`; - -document.getElementById('my_button').addEventListener('click', () => { - Tracking.event('dashboard:projects:index', 'click_button', { - label: 'create_from_template', - property: 'template_preview', - value: 'rails', - }); -}) -``` - -## Toggling tracking on or off - -Snowplow can be enabled by navigating to: - -- **Admin area > Settings > Integrations** in the UI. -- `admin/application_settings/integrations` in your browser. - -The following configuration is required: - -| Name | Value | -| ------------- | ------------------------- | -| Collector | `snowplow.trx.gitlab.net` | -| Site ID | `gitlab` | -| Cookie domain | `.gitlab.com` | - -Now the implemented tracking events can be inspected locally by looking at the network panel of the browser's development tools. +This document was moved to [another location](../event_tracking/frontend.md). diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 0d2aeffeac0..2ec3f8017a1 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -17,6 +17,8 @@ ### How do I find the Rails route for a page? +#### Check the 'page' data attribute + The easiest way is to type the following in the browser while on the page in question: @@ -24,7 +26,16 @@ question: document.body.dataset.page ``` -Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/gitlab-ce/blob/cc5095edfce2b4d4083a4fb1cdc7c0a1898b9921/app/views/layouts/application.html.haml#L4). +Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/gitlab-foss/blob/cc5095edfce2b4d4083a4fb1cdc7c0a1898b9921/app/views/layouts/application.html.haml#L4). + +#### Rails routes + +The `rake routes` command can be used to list all the routes available in the application, piping the output into `grep`, we can perform a search through the list of available routes. +The output includes the request types available, route parameters and the relevant controller. + +```sh +bundle exec rake routes | grep "issues" +``` ### `modal_copy_button` vs `clipboard_button` diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 4fc5dfc8c3d..366c2894b81 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -119,6 +119,6 @@ Read more about the [Apollo] client in the [Apollo documentation](https://www.ap [Apollo]: https://www.apollographql.com/ [vue-apollo]: https://github.com/Akryum/vue-apollo/ [feature-flags]: ../feature_flags.md -[default-client]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/lib/graphql.js +[default-client]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/javascripts/lib/graphql.js [vue-test-utils]: https://vue-test-utils.vuejs.org/ [apollo-link-state]: https://www.apollographql.com/docs/link/links/state.html diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index deaef8e768b..4cccd4aa5fb 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -69,10 +69,6 @@ How we use SVG for our Icons and Illustrations. How we use UI components. -## [Event Tracking](event_tracking.md) - -How we use Snowplow to track custom events. - ## Frontend FAQ Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information. diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 3a8ea04407f..bcd22a170e1 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -65,7 +65,7 @@ within the `pages` directory correspond to Rails controllers and actions. These auto-generated bundles will be automatically included on the corresponding pages. -For example, if you were to visit [gitlab.com/gitlab-org/gitlab-ce/issues](https://gitlab.com/gitlab-org/gitlab-ce/issues), +For example, if you were to visit [gitlab.com/gitlab-org/gitlab-foss/issues](https://gitlab.com/gitlab-org/gitlab-foss/issues), you would be accessing the `app/controllers/projects/issues_controller.rb` controller with the `index` action. If a corresponding file exists at `pages/projects/issues/index/index.js`, it will be compiled into a webpack diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index 125b11afcd0..db076243812 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -7,7 +7,7 @@ See the relevant style guides for our guidelines and for information on linting: We defer to [Airbnb][airbnb-js-style-guide] on most style-related conventions and enforce them with eslint. -See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc.yml) for specific rules and patterns. +See [our current .eslintrc](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/.eslintrc.yml) for specific rules and patterns. ### Common @@ -392,7 +392,7 @@ Please check this [rules][eslint-plugin-vue-rules] for more documentation. <component my-prop="prop" /> ``` -[#34371]: https://gitlab.com/gitlab-org/gitlab-ce/issues/34371 +[#34371]: https://gitlab.com/gitlab-org/gitlab-foss/issues/34371 #### Alignment @@ -713,7 +713,7 @@ The goal of this accord is to make sure we are all on the same page. - [SCSS](style_guide_scss.md) [airbnb-js-style-guide]: https://github.com/airbnb/javascript -[eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc +[eslintrc]: https://gitlab.com/gitlab-org/gitlab-foss/blob/master/.eslintrc [eslint-plugin-vue]: https://github.com/vuejs/eslint-plugin-vue [eslint-plugin-vue-rules]: https://github.com/vuejs/eslint-plugin-vue#bulb-rules [vue-order]: https://github.com/vuejs/eslint-plugin-vue/blob/master/docs/rules/order-in-components.md diff --git a/doc/development/fe_guide/style_guide_scss.md b/doc/development/fe_guide/style_guide_scss.md index 95c4a094c04..d5af19e0ea4 100644 --- a/doc/development/fe_guide/style_guide_scss.md +++ b/doc/development/fe_guide/style_guide_scss.md @@ -13,12 +13,12 @@ led by the [GitLab UI WG](https://gitlab.com/gitlab-com/www-gitlab-com/merge_req #### Where are utility classes defined? - [Bootstrap's Utility Classes](https://getbootstrap.com/docs/4.3/utilities/) -- [`common.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/framework/common.scss) (old) -- [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/utilities.scss) (new) +- [`common.scss`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/stylesheets/framework/common.scss) (old) +- [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/stylesheets/utilities.scss) (new) #### Where should I put new utility classes? -New utility classes should be added to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/stylesheets/utilities.scss). Existing classes include: +New utility classes should be added to [`utilities.scss`](https://gitlab.com/gitlab-org/gitlab-foss/blob/master/app/assets/stylesheets/utilities.scss). Existing classes include: | Name | Pattern | Example | |------|---------|---------| @@ -41,8 +41,8 @@ This encourages an organic growth of component classes and prevents the creation Examples of component classes that were created using "utility-first" include: -- [`.circle-icon-container`](https://gitlab.com/gitlab-org/gitlab-ce/blob/579fa8b8ec7eb38d40c96521f517c9dab8c3b97a/app/assets/stylesheets/framework/icons.scss#L85) -- [`.d-flex-center`](https://gitlab.com/gitlab-org/gitlab-ce/blob/900083d89cd6af391d26ab7922b3f64fa2839bef/app/assets/stylesheets/framework/common.scss#L425) +- [`.circle-icon-container`](https://gitlab.com/gitlab-org/gitlab-foss/blob/579fa8b8ec7eb38d40c96521f517c9dab8c3b97a/app/assets/stylesheets/framework/icons.scss#L85) +- [`.d-flex-center`](https://gitlab.com/gitlab-org/gitlab-foss/blob/900083d89cd6af391d26ab7922b3f64fa2839bef/app/assets/stylesheets/framework/common.scss#L425) Inspiration: diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 421b7265613..396467b47d1 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -6,9 +6,9 @@ To get started with Vue, read through [their documentation][vue-docs]. What is described in the following sections can be found in these examples: -- web ide: <https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/ide/stores> -- security products: <https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports> -- registry: <https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/registry/stores> +- web ide: <https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/ide/stores> +- security products: <https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/assets/javascripts/vue_shared/security_reports> +- registry: <https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/registry/stores> ## Vue architecture @@ -246,8 +246,8 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's - Knowledge about the existing Vue and Vuex applications and existing reusable components [vue-docs]: http://vuejs.org/guide/index.html -[issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards -[environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments +[issue-boards]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/boards +[environments-table]: https://gitlab.com/gitlab-org/gitlab-foss/tree/master/app/assets/javascripts/environments [page_specific_javascript]: ./performance.md#page-specific-javascript [component-system]: https://vuejs.org/v2/guide/#Composing-with-Components [state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 336ef4ab278..bb131746ecf 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -26,7 +26,7 @@ When using Vuex at GitLab, separate these concerns into different files to impro ``` The following example shows an application that lists and adds users to the state. -(For a more complex example implementation take a look at the security applications store in [here](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store)) +(For a more complex example implementation take a look at the security applications store in [here](https://gitlab.com/gitlab-org/gitlab/tree/master/ee/app/assets/javascripts/vue_shared/security_reports/store)) ### `index.js` |