머지 리퀘스트 위젯

요약

머지 리퀘스트 위젯을 사용하면 디자인 프레임워크에 맞는 새로운 기능을 추가할 수 있습니다. 일관된 룩앤필(look and feel). 위젯은 ~/vue_merge_request_widget/components/widget/widget.vue 컴포넌트를 사용하는 일반적인 Vue 컴포넌트입니다.

머지 리퀘스트 위젯을 사용하면 디자인 프레임워크에 맞는 새로운 기능을 추가할 수 있습니다. 이 위젯을 통해 큰 노력 없이도 다음과 같은 많은 이점을 기본으로 누릴 수 있습니다:

일관된 룩앤필(look and feel).
위젯이 열릴 때 추적 기능.
성능을 위한 가상 스크롤링.

사용법#

위젯은 ~/vue_merge_request_widget/components/widget/widget.vue 컴포넌트를 사용하는 일반적인 Vue 컴포넌트입니다. 사용 사례의 복잡성에 따라 구성 객체를 전달하거나, slot을 통해 컴포넌트를 확장할 수 있습니다.

슬롯을 사용하는 예시는 다음 파일을 참고하세요: ee/app/assets/javascripts/vue_merge_request_widget/widgets/security_reports/mr_widget_security_reports.vue

데이터 객체를 사용하는 예시는 다음 파일을 참고하세요: ee/app/assets/javascripts/vue_merge_request_widget/widgets/metrics/index.vue

다음은 Hello World 위젯을 렌더링하는 최소한의 예시입니다:

<script>
import MrWidget from '~/vue_merge_request_widget/components/widget/widget.vue';
import { __ } from '~/locale';

export default {
  name: 'WidgetHelloWorld',
  components: {
    MrWidget,
  },
  computed: {
    summary() {
      return { title: __('Hello World') };
    },
  },
};
</script>
<template>
  <mr-widget :summary="summary" :is-collapsible="false" :widget-name="$options.name" />
</template>

위젯 등록#

위의 예시는 페이지 어디에도 렌더링되지 않습니다. 머지 리퀘스트 위젯 섹션에 마운트하려면 다음 두 위치 중 하나 또는 둘 모두에 위젯을 등록해야 합니다:

app/assets/javascripts/vue_merge_request_widget/components/widget/app.vue (CE 위젯용)
ee/app/assets/javascripts/vue_merge_request_widget/components/widget/app.vue (CE 및 EE 위젯용)

컴포넌트 목록에 컴포넌트를 정의하고 widgets computed 속성에 이름을 추가하면 위젯이 마운트됩니다:

<script>
export default {
  components: {
    MrHelloWorldWidget: () =>
      import('ee/vue_merge_request_widget/widgets/hello_world/index.vue'),
  },
  computed: {
    mrHelloWorldWidget() {
      return this.mr.shouldRenderHelloWorldWidget ? 'MrHelloWorldWidget' : undefined;
    },
    widgets() {
      return [
        this.mrHelloWorldWidget,
      ].filter((w) => w);
    },
  },
};
</script>

데이터 페칭#

위젯이 마운트될 때 데이터를 가져오려면, :fetch-collapsed-data 속성에 API 호출을 수행하는 함수를 전달합니다.

함수는 response 객체로 resolve되는 Promise를 반환해야 합니다. 구현은 폴링을 계속하기 위해 POLL-INTERVAL 헤더에 의존하므로, 상태 코드와 헤더를 변경하지 않는 것이 중요합니다.

<script>
export default {
  // ...
  data() {
    return {
      collapsedData: [],
    };
  },
  methods: {
    fetchCollapsedData() {
      return axios.get('/my/path').then((response) => {
        this.collapsedData = response.data;
        return response;
      });
    },
  },
};
</script>
<template>
  <mr-widget :fetch-collapsed-data="fetchCollapsedData" />
</template>

:fetch-expanded-data도 동일한 방식으로 작동하지만, 사용자가 위젯을 펼칠 때만 호출됩니다.

데이터 구조#

content와 summary 속성을 사용하여 Widget을 렌더링할 수 있습니다. 아래는 두 속성에 대한 설명입니다:

// content
{
  text: '',           // 필수: 행의 메인 텍스트
  subtext: '',        // 선택: 메인 텍스트 아래에 표시할 더 작은 서브 텍스트
  supportingText: '', // 선택: 서브 텍스트 아래에 표시할 단락
  icon: {             // 선택: 아이콘 객체
    name: EXTENSION_ICONS.success, // 필수: 행의 아이콘 이름
  },
  badge: {            // 선택: 텍스트 다음에 표시되는 배지
    text: '',         // 필수: 배지 내부에 표시할 텍스트
    variant: '',      // 선택: GitLab UI 배지 variant, 기본값은 info
  },
  link: {             // 선택: 텍스트 다음에 표시되는 URL 링크
    text: '',         // 필수: 링크 텍스트
    href: '',         // 선택: 링크 URL
  },
  actions: [],        // 선택: 행에 대한 액션 버튼
  children: [],       // 선택: 렌더링할 하위 콘텐츠, 구조는 동일한 구조를 따름
  helpPopover: {      // 선택: 제공되면 콘텐츠 행 가장 오른쪽에 정보 아이콘이 표시됨
    options: {
      title: ''       // 필수: 팝오버의 제목
    },
    content: {
      text: '',           // 선택: 팝오버의 텍스트 콘텐츠
      learnMorePath: '',  // 선택: 문서 경로. 제공되면 더 알아보기 링크가 표시됨.
    }
  }
}

// summary
{
  title: '',    // 필수: summary 부분의 메인 텍스트
  subtitle: '', // 선택: summary 부분의 서브 텍스트
}

오류#

:fetch-collapsed-data 또는 :fetch-expanded-data 메서드에서 오류가 발생하는 경우. 오류 텍스트를 커스터마이즈하려면 :error-text 속성을 사용할 수 있습니다:

<template>
  <mr-widget :error-text="__('Failed to load.')" />
</template>

텔레메트리#

위젯 프레임워크의 기본 구현에는 일부 텔레메트리 이벤트가 포함되어 있습니다. 각 위젯은 다음을 보고합니다:

view: 화면에 렌더링될 때.
expand: 펼쳐질 때.
full_report_clicked: 전체 보고서를 보기 위해 (선택적) 입력이 클릭될 때.
결과(expand_success, expand_warning, 또는 expand_failed): 위젯이 펼쳐졌을 때의 상태와 관련된 세 가지 추가 이벤트 중 하나.

새 위젯 추가#

새 위젯을 추가할 때 위의 이벤트들은 known으로 표시되어야 하며, 보고 가능하도록 메트릭이 생성되어야 합니다.

EE 전용 이벤트는 아래 두 셸 명령어 끝에 --ee를 포함해야 합니다.

단일 위젯에 대한 known 이벤트를 생성하려면:

위젯 이름은 Widget${CamelName} 형식이어야 합니다.

예를 들어: Test Reports 위젯은 WidgetTestReports여야 합니다.

${CamelName}을 소문자 스네이크 케이스로 변환하여 위젯 이름 슬러그를 계산합니다.

앞의 예시는 test_reports가 됩니다.

새 위젯 이름 슬러그를 lib/gitlab/usage_data_counters/merge_request_widget_counter.rb의 WIDGETS 목록에 추가합니다.

GDK가 실행 중인지 확인합니다(gdk start).

다음 명령어로 커맨드 라인에서 known 이벤트를 생성합니다. test_reports를 적절한 이름 슬러그로 교체하세요:

bundle exec rails generate gitlab:usage_metric_definition \
counts.i_code_review_merge_request_widget_test_reports_count_view \
counts.i_code_review_merge_request_widget_test_reports_count_full_report_clicked \
counts.i_code_review_merge_request_widget_test_reports_count_expand \
counts.i_code_review_merge_request_widget_test_reports_count_expand_success \
counts.i_code_review_merge_request_widget_test_reports_count_expand_warning \
counts.i_code_review_merge_request_widget_test_reports_count_expand_failed \
--dir=all

새로 생성된 각 파일을 머지 리퀘스트 위젯 확장 텔레메트리용 기존 파일과 일치하도록 수정합니다.

글로브 검색으로 기존 예시를 찾을 수 있습니다: metrics/**/*_i_code_review_merge_request_widget_*

대략적으로 각 파일에는 다음 값이 있어야 합니다:

description = 이 값에 대한 영문 설명. 예시는 기존 위젯 확장 텔레메트리 파일을 참고하세요.

product_section = dev
product_stage = create
product_group = code_review
introduced_by_url = '[your MR]'
options.events = (위 명령어에서 이 파일을 생성한 이벤트, 예: i_code_review_merge_request_widget_test_reports_count_view)

이 값은 텔레메트리 이벤트가 "메트릭"에 연결되는 방식으로, 아마도 더 중요한 값 중 하나입니다.

data_source = redis
data_category = optional

다음 명령어로 커맨드 라인에서 known HLL 이벤트를 생성합니다. test_reports를 적절한 이름 슬러그로 교체하세요.

bundle exec rails generate gitlab:usage_metric_definition:redis_hll code_review \
i_code_review_merge_request_widget_test_reports_view \
i_code_review_merge_request_widget_test_reports_full_report_clicked \
i_code_review_merge_request_widget_test_reports_expand \
i_code_review_merge_request_widget_test_reports_expand_success \
i_code_review_merge_request_widget_test_reports_expand_warning \
i_code_review_merge_request_widget_test_reports_expand_failed \
--class_name=RedisHLLMetric

6단계를 반복하되 data_source를 redis_hll로 변경합니다.

7단계의 명령어에 나열된 각 이벤트(test_reports를 적절한 이름 슬러그로 교체)를 다음 집계 파일에 추가합니다:

config/metrics/counts_7d/{timestamp}_code_review_category_monthly_active_users.yml

config/metrics/counts_7d/{timestamp}_code_review_group_monthly_active_users.yml
config/metrics/counts_28d/{timestamp}_code_review_category_monthly_active_users.yml
config/metrics/counts_28d/{timestamp}_code_review_group_monthly_active_users.yml

새 이벤트 추가#

known 이벤트에 새 이벤트를 추가하는 경우, lib/gitlab/usage_data_counters/merge_request_widget_extension_counter.rb의 KNOWN_EVENTS 목록에 새 이벤트를 포함시킵니다.

아이콘#

레벨 1 및 이후의 모든 레벨은 자체 상태 아이콘을 가질 수 있습니다. 디자인 프레임워크를 준수하려면 constants.js 파일에서 EXTENSION_ICONS 상수를 가져옵니다:

import { EXTENSION_ICONS } from '~/vue_merge_request_widget/constants.js';

이 상수에는 사용 가능한 아래 아이콘들이 있습니다. 디자인 프레임워크에 따라 이 아이콘 중 일부만 레벨 1에서 사용해야 합니다:

failed
warning
success
neutral
error
notice
severityCritical
severityHigh
severityMedium
severityLow
severityInfo
severityUnknown

액션 버튼#

각 확장의 레벨 1과 2 모두에 액션 버튼을 추가할 수 있습니다. 이 버튼들은 각 행에 대한 링크나 액션을 제공하는 방법으로 사용됩니다:

레벨 1의 액션 버튼은 tertiaryButtons computed 속성을 통해 설정할 수 있습니다. 이 속성은 각 액션 버튼에 대한 객체 배열을 반환해야 합니다.
레벨 2의 액션 버튼은 레벨 2 행 객체에 actions 키를 추가하여 설정할 수 있습니다. 이 키의 값도 각 액션 버튼에 대한 객체 배열이어야 합니다.

링크는 다음 구조를 따라야 합니다:

{
  text: 'Click me',
  href: this.someLinkHref,
  target: '_blank', // 선택 사항
}

내부 액션 버튼의 경우 다음 구조를 따릅니다:

{
  text: 'Click me',
  onClick() {}
}

데모#

모든 위젯이 함께 표시된 예시를 보려면 GitLab MR Widgets Demo를 방문하세요.