diff options
Diffstat (limited to 'doc/development/new_fe_guide')
| -rw-r--r-- | doc/development/new_fe_guide/development/design_patterns.md | 3 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/development/index.md | 12 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/development/network_requests.md | 3 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/development/security.md | 14 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/event_tracking.md | 91 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/index.md | 11 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/initiatives.md | 3 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/principles.md | 35 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/style/html.md | 28 | ||||
| -rw-r--r-- | doc/development/new_fe_guide/tips.md | 16 |
10 files changed, 28 insertions, 188 deletions
diff --git a/doc/development/new_fe_guide/development/design_patterns.md b/doc/development/new_fe_guide/development/design_patterns.md deleted file mode 100644 index ee06566ed30..00000000000 --- a/doc/development/new_fe_guide/development/design_patterns.md +++ /dev/null @@ -1,3 +0,0 @@ -# Design patterns - -> TODO: Add content diff --git a/doc/development/new_fe_guide/development/index.md b/doc/development/new_fe_guide/development/index.md index cee8e43ebad..5dced3dc466 100644 --- a/doc/development/new_fe_guide/development/index.md +++ b/doc/development/new_fe_guide/development/index.md @@ -1,9 +1,5 @@ # Development -## [Design patterns](design_patterns.md) - -Examples of proven design patterns used in our codebase. - ## [Components](components.md) Documentation on existing components and how to best create a new component. @@ -12,14 +8,6 @@ Documentation on existing components and how to best create a new component. Learn how to implement an accessible frontend. -## [Network requests](network_requests.md) - -Learn how to handle network requests in our codebase. - -## [Security](security.md) - -Learn how to ensure that our frontend is secure. - ## [Performance](performance.md) Learn how to keep our frontend performant. diff --git a/doc/development/new_fe_guide/development/network_requests.md b/doc/development/new_fe_guide/development/network_requests.md deleted file mode 100644 index 047c00313bc..00000000000 --- a/doc/development/new_fe_guide/development/network_requests.md +++ /dev/null @@ -1,3 +0,0 @@ -# Network requests - -> TODO: Add content diff --git a/doc/development/new_fe_guide/development/security.md b/doc/development/new_fe_guide/development/security.md deleted file mode 100644 index 5bb38f17988..00000000000 --- a/doc/development/new_fe_guide/development/security.md +++ /dev/null @@ -1,14 +0,0 @@ -# Security - -## Avoid inline scripts and styles - -Inline scripts and styles should be avoided in almost all cases. In an effort to protect users from [XSS vulnerabilities](https://en.wikipedia.org/wiki/Cross-site_scripting), we will be disabling inline scripts using Content Security Policy. - -## Including external resources - -External fonts, CSS, and JavaScript should never be used with the exception of Google Analytics and Piwik - and only when the instance has enabled it. Assets should always be hosted and served locally from the GitLab instance. Embedded resources via `iframes` should never be used except in certain circumstances such as with ReCaptcha, which cannot be used without an `iframe`. - -## Resources for security testing - -- [Mozilla's HTTP Observatory CLI](https://github.com/mozilla/http-observatory-cli) -- [Qualys SSL Labs Server Test](https://www.ssllabs.com/ssltest/analyze.html) diff --git a/doc/development/new_fe_guide/event_tracking.md b/doc/development/new_fe_guide/event_tracking.md deleted file mode 100644 index 6ab3fa4acf3..00000000000 --- a/doc/development/new_fe_guide/event_tracking.md +++ /dev/null @@ -1,91 +0,0 @@ -# Event Tracking - -We use [Snowplow](https://github.com/snowplow/snowplow) for tracking custom events (available in GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) only). - -## 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. - -## Testing - -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. diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index 5fd5af252ef..0e8f5486861 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -3,14 +3,6 @@ This guide contains all the information to successfully contribute to GitLab's frontend. This is a living document, and we welcome contributions, feedback and suggestions. -## [Principles](principles.md) - -Ensure that your frontend contribution starts off in the right direction. - -## [Initiatives](initiatives.md) - -High level overview of where we are going from a frontend perspective. - ## [Development](development/index.md) Guidance on topics related to development. @@ -27,9 +19,6 @@ Learn about all the internal JavaScript modules that make up our frontend. 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) diff --git a/doc/development/new_fe_guide/initiatives.md b/doc/development/new_fe_guide/initiatives.md deleted file mode 100644 index c81ed3579f0..00000000000 --- a/doc/development/new_fe_guide/initiatives.md +++ /dev/null @@ -1,3 +0,0 @@ -# Initiatives - -> TODO: Add Initiatives diff --git a/doc/development/new_fe_guide/principles.md b/doc/development/new_fe_guide/principles.md deleted file mode 100644 index 0af5f506a91..00000000000 --- a/doc/development/new_fe_guide/principles.md +++ /dev/null @@ -1,35 +0,0 @@ -# Principles - -These principles will ensure that your frontend contribution starts off in the right direction. - -## Discuss architecture before implementation - -Discuss your architecture design in an issue before writing code. This helps decrease the review time and also provides good practice for writing and thinking about system design. - -## Be consistent - -There are multiple ways of writing code to accomplish the same results. We should be as consistent as possible in how we write code across our codebases. This will make it more easier us to maintain our code across GitLab. - -## Enhance progressively - -Whenever you see with existing code that does not follow our current style guide, update it proactively. Refrain from changing everything but each merge request should progressively enhance our codebase and reduce technical debt. - -## When to use Vue - -- Use Vue for feature that make use of heavy DOM manipulation -- Use Vue for reusable components - -## When to use jQuery - -- Use jQuery to interact with Bootstrap JavaScript components -- Avoid jQuery when a better alternative exists. We are slowly moving away from it [#43559][jquery-future] - -## Mixing Vue and jQuery - -- Mixing Vue and jQuery is not recommended. -- If you need to use a specific jQuery plugin in Vue, [create a wrapper around it][select2]. -- It is acceptable for Vue to listen to existing jQuery events using jQuery event listeners. -- It is not recommended to add new jQuery events for Vue to interact with jQuery. - -[jquery-future]: https://gitlab.com/gitlab-org/gitlab-ce/issues/43559 -[select2]: https://vuejs.org/v2/examples/select2.html diff --git a/doc/development/new_fe_guide/style/html.md b/doc/development/new_fe_guide/style/html.md index 035fcbb28df..e8c9c2ccebf 100644 --- a/doc/development/new_fe_guide/style/html.md +++ b/doc/development/new_fe_guide/style/html.md @@ -2,11 +2,11 @@ ## Buttons -<a name="button-type"></a><a name="1.1"></a> +### Button type -- [1.1](#button-type) **Use button type** Button tags requires a `type` attribute according to the [W3C HTML specification][button-type-spec]. +Button tags requires a `type` attribute according to the [W3C HTML specification](https://www.w3.org/TR/2011/WD-html5-20110525/the-button-element.html#dom-button-type). -``` +```html // bad <button></button> @@ -14,11 +14,11 @@ <button type="button"></button> ``` -<a name="button-role"></a><a name="1.2"></a> +### Button role -- [1.2](#button-role) **Use button role for non buttons** If an HTML element has an onClick handler but is not a button, it should have `role="button"`. This is more [accessible][button-role-accessible]. +If an HTML element has an `onClick` handler but is not a button, it should have `role="button"`. This is [more accessible](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role). -``` +```html // bad <div onClick="doSomething"></div> @@ -28,11 +28,11 @@ ## Links -<a name="blank-links"></a><a name="2.1"></a> +### Blank target -- [2.1](#blank-links) **Use rel for target blank** Use `rel="noopener noreferrer"` whenever your links open in a new window i.e. `target="_blank"`. This prevents [the following][jitbit-target-blank] security vulnerability documented by JitBit +Use `rel="noopener noreferrer"` whenever your links open in a new window, i.e. `target="_blank"`. This prevents a security vulnerability [documented by JitBit](https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/). -``` +```html // bad <a href="url" target="_blank"></a> @@ -40,18 +40,14 @@ <a href="url" target="_blank" rel="noopener noreferrer"></a> ``` -<a name="fake-links"></a><a name="2.2"></a> +### Fake links -- [2.2](#fake-links) **Do not use fake links** Use a button tag if a link only invokes JavaScript click event handlers. This is more semantic. +**Do not use fake links.** Use a button tag if a link only invokes JavaScript click event handlers, which is more semantic. -``` +```html // bad <a class="js-do-something" href="#"></a> // good <button class="js-do-something" type="button"></button> ``` - -[button-type-spec]: https://www.w3.org/TR/2011/WD-html5-20110525/the-button-element.html#dom-button-type -[button-role-accessible]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_button_role -[jitbit-target-blank]: https://www.jitbit.com/alexblog/256-targetblank---the-most-underestimated-vulnerability-ever/ diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md index 881ad1662ae..889a5aab2b7 100644 --- a/doc/development/new_fe_guide/tips.md +++ b/doc/development/new_fe_guide/tips.md @@ -7,3 +7,19 @@ To clear production compiled assets created with `yarn webpack-prod` you can run ``` yarn clean ``` + +## Creating feature flags in development + +The process for creating a feature flag is the same as [enabling a feature flag in development](https://docs.gitlab.com/ee/development/feature_flags.html#enabling-a-feature-flag-in-development). + +Your feature flag can now be: + +- [made available to the frontend](https://docs.gitlab.com/ee/development/feature_flags.html#frontend) via the `gon` +- queried in [tests](https://docs.gitlab.com/ee/development/feature_flags.html#specs) +- queried in HAML templates and ruby files via the `Feature.enabled?(:my_shiny_new_feature_flag)` method + +### More on feature flags + +- [Deleting a feature flag](https://docs.gitlab.com/ee/api/features.html#delete-a-feature) +- [Manage feature flags](https://docs.gitlab.com/ee/development/feature_flags.html) +- [Feature flags API](https://docs.gitlab.com/ee/api/features.html) |