ViewComponent
ViewComponent는 Ruby on Rails로 재사용 가능하고, 테스트 가능하며, 캡슐화된 뷰 컴포넌트를 생성하기 위한 프레임워크로, Vue와 같은 JavaScript 프레임워크가 필요하지 않습니다.
서버 측에서 렌더링되며, Haml과 같은 템플릿 언어와 원활하게 사용될 수 있습니다.
자세한 내용은 공식 문서 또는 이 소개 영상을 참조하세요.
Lookbook으로 컴포넌트 탐색하기
http://gdk.test:3000/rails/lookbook
(개발 모드에서만 사용 가능)에서 ViewComponent 미리보기를 탐색하고 상호작용할 수 있는 Lookbook이 있습니다.
Pajamas 컴포넌트
우리의 Pajamas 디자인 시스템의 일부 컴포넌트가 app/components/pajamas
에서 ViewComponent로 제공됩니다.
사용 가능한 컴포넌트
이 목록은 최선을 다한 노력입니다. 전체 목록은 app/components/pajamas
에서 확인할 수 있습니다. 또한 우리 컴포넌트를 더욱 인터랙티브하게 탐색할 수 있는 Lookbook(http://gdk.test:3000/rails/lookbook
)도 확인하시기 바랍니다.
Alert
Pajamas::AlertComponent
는 Pajamas Alert 사양을 따릅니다.
예시:
기본적으로 이는 아이콘이 포함된 닫을 수 있는 정보 알림을 생성합니다:
= render Pajamas::AlertComponent.new(title: "Almost done!")
변형을 설정하거나 아이콘을 숨기는 등 더 많은 옵션을 설정할 수 있습니다:
= render Pajamas::AlertComponent.new(title: "All done!",
variant: :success,
dismissible: :false,
show_icon: false)
옵션의 전체 목록은 그 소스에서 확인하세요.
Banner
Pajamas::BannerComponent
는 Pajamas Banner 사양을 따릅니다.
예시:
가장 간단한 형태의 배너 컴포넌트는 다음과 같습니다:
= render Pajamas::BannerComponent.new(button_text: 'Learn more', button_link: example_path,
svg_path: 'illustrations/example.svg') do |c|
- c.with_title { 'Hello world!' }
%p Content of your banner goes here...
더 많은 제어가 필요한 경우 svg_path
대신 illustration
슬롯을, button_text
및 button_link
대신 primary_action
슬롯을 사용할 수 있습니다:
= render Pajamas::BannerComponent.new do |c|
- c.with_illustration do
= custom_icon('my_inline_svg')
- c.with_title do
Hello world!
- c.with_primary_action do
= render 'my_button_in_a_partial'
옵션의 전체 목록은 그 소스에서 확인하세요.
버튼
Pajamas::ButtonComponent
는 Pajamas Button 사양을 따릅니다.
예시:
버튼 컴포넌트는 많은 옵션이 있지만 모두 좋은 기본값을 가지고 있어, 가장 간단한 버튼은 다음과 같습니다:
= render Pajamas::ButtonComponent.new do |c|
= _('버튼 텍스트가 여기에 들어갑니다')
다음 예시는 사용 가능한 대부분의 옵션을 보여줍니다:
= render Pajamas::ButtonComponent.new(category: :secondary,
variant: :danger,
size: :small,
type: :submit,
disabled: true,
loading: false,
block: true) do |c|
버튼 텍스트가 여기에 들어갑니다
다음과 같이 버튼처럼 보이는 <a>
태그도 만들 수 있습니다:
= render Pajamas::ButtonComponent.new(href: root_path) do |c|
집으로 가기
전체 옵션 목록은 다음 소스를 참조하세요.
카드
Pajamas::CardComponent
는 Pajamas Card 사양을 따릅니다.
예시:
카드는 필수 body
슬롯과 선택적 header
및 footer
슬롯을 가지고 있습니다:
= render Pajamas::CardComponent.new do |c|
- c.with_header do
나는 헤더입니다.
- c.with_body do
%p 여러 줄
%p 본문 내용.
- c.with_footer do
바닥글이 여기에 있습니다.
이러한 슬롯들 또는 카드 자체에 사용자 정의 속성을 추가하려면 다음 옵션을 사용하세요:
= render Pajamas::CardComponent.new(card_options: {id: "my-id"}, body_options: {data: { count: 1 }})
header_options
와 footer_options
도 사용할 수 있습니다.
전체 옵션 목록은 다음 소스를 참조하세요.
체크박스 태그
Pajamas::CheckboxTagComponent
는 Pajamas Checkbox 사양을 따릅니다.
name
인자와 label
슬롯은 필수입니다.
예를 들어:
= render Pajamas::CheckboxTagComponent.new(name: 'project[initialize_with_sast]',
checkbox_options: { data: { testid: 'initialize-with-sast-checkbox', track_label: track_label, track_action: 'activate_form_input', track_property: 'init_with_sast' } }) do |c|
- c.with_label do
= s_('ProjectsNew|정적 애플리케이션 보안 테스트 (SAST) 활성화')
- c.with_help_text do
= s_('ProjectsNew|알려진 보안 취약점에 대해 소스 코드를 분석합니다.')
= link_to _('자세히 알아보기.'), help_page_path('user/application_security/sast/index'), target: '_blank', rel: 'noopener noreferrer', data: { track_action: 'followed' }
전체 옵션 목록은 다음 소스를 참조하세요.
체크박스
Pajamas::CheckboxComponent
는 Pajamas Checkbox 사양을 따릅니다.
참고:
Pajamas::CheckboxComponent
는 GitLab UI 폼 빌더에서 내부적으로 사용되며, form
인자로 ActionView::Helpers::FormBuilder의 인스턴스가 필요합니다.
gitlab_ui_checkbox_component
메서드를 사용하여 이 ViewComponent를 렌더링하는 것이 선호됩니다.
ActionView::Helpers::FormBuilder 인스턴스 없이 체크박스를 사용하려면 CheckboxTagComponent를 사용하세요.
전체 옵션 목록은 다음 소스를 참조하세요.
토글
Pajamas::ToggleComponent
는 Pajamas Toggle 사양을 따릅니다.
= render Pajamas::ToggleComponent.new(classes: 'js-force-push-toggle',
label: s_("ProtectedBranch|Toggle allowed to force push"),
is_checked: protected_branch.allow_force_push,
label_position: :hidden) do
이 블록을 활용하여 풍부한 도움말 텍스트를 렌더링합니다. 일반 텍스트 도움말 텍스트를 렌더링하려면 `help` 매개변수를 선호하세요.
참고:
토글 ViewComponent는 Vue.js 구성 요소에 의존하기 때문에 특수합니다.
이 구성 요소를 실제로 초기화하려면 ~/toggles
에서 initToggle
헬퍼를 호출해야 합니다.
전체 옵션 목록은 해당
source를 참조하세요.
레이아웃
레이아웃 구성 요소는 GitLab에서 사용되는 일반 레이아웃 패턴을 만드는 데 사용할 수 있습니다.
사용 가능한 구성 요소
페이지 제목
페이지 제목과 선택적 작업이 포함된 표준 페이지 헤더입니다.
예제:
= render ::Layouts::PageHeadingComponent.new(_('Page title')) do |c|
- c.with_actions do
= buttons
전체 옵션 목록은 해당
source를 참조하세요.
CRUD 구성 요소
테이블이나 목록을 호스팅하고 생성, 읽기, 업데이트, 삭제와 같은 사용자 작업을 포함하는 목록 컨테이너입니다.
예제:
= render ::Layouts::CrudComponent.new(_('CRUD title'), icon: 'ICONNAME', count: COUNT) do |c|
- c.with_description do
= description
- c.with_actions do
= buttons
- c.with_form do
= add item form
- c.with_body do
= body
- c.with_pagination do
= pagination component
- c.with_footer do
= optional footer
전체 옵션 목록은 해당
source를 참조하세요.
수평 섹션
많은 설정 페이지는 제목과 설명이 왼쪽에 있고 설정 필드가 오른쪽에 있는 레이아웃을 사용합니다. Layouts::HorizontalSectionComponent
를 사용하여 이 레이아웃을 만들 수 있습니다.
예제:
= render ::Layouts::HorizontalSectionComponent.new(options: { class: 'gl-mb-6' }) do |c|
- c.with_title { _('Naming, visibility') }
- c.with_description do
= _('Update your group name, description, avatar, and visibility.')
= link_to _('Learn more about groups.'), help_page_path('user/group/index')
- c.with_body do
.form-group.gl-form-group
= f.label :name, _('New group name')
= f.text_field :name
전체 옵션 목록은 해당
source를 참조하세요.
설정 블록
관련 설정을 그룹화하는 설정 블록(아코디언)입니다.
예제:
= render ::Layouts::SettingsBlock.new(_('Settings block heading')) do |c|
- c.with_description do
= description
- c.with_body do
= body
전체 옵션 목록은 해당
source를 참조하세요.
설정 섹션
SettingsBlock과 유사하게 이 구성 요소는 관련 설정을 함께 그룹화하는 데 사용됩니다. SettingsBlock과는 달리 아코디언 기능을 제공하지 않습니다. 스티키 헤더를 사용합니다.
예시:
= render ::Layouts::SettingsSection.new(_('설정 섹션 제목')) do |c|
- c.with_description do
= description
- c.with_body do
= body
전체 옵션 목록은 source를 참조하세요.
모범 사례
-
Haml에서 새 보기 생성이 필요할 경우, 일반 Haml 태그와 CSS 클래스를 사용하는 것보다 사용 가능한 구성 요소를 사용하세요.
-
기존 Haml 보기를 변경하는 경우 예를 들어, 여전히 일반 Haml로 구현된 버튼을 발견하면, 이를 ViewComponent로 마이그레이션하는 것을 고려하세요.
-
새로운 구성 요소를 생성하기로 결정하면, 해당 구성 요소에 대한 미리보기를 생성하는 것도 고려하세요.
이는 다른 사람들이 Lookbook으로 귀하의 구성 요소를 발견하는 데 도움이 되며, 다양한 상태를 테스트하는 것도 훨씬 더 쉽게 만듭니다.
미리보기 레이아웃
ViewComponent 미리보기에 맞춤 레이아웃이 필요하면 레이아웃 코드에 대해 이러한 경로를 사용하는 것을 고려하세요:
-
app/views/layouts/lookbook
— 레이아웃 HAML 파일용 -
app/assets/javascripts/entrypoints/lookbook
— 사용자 정의 JavaScript 코드용 -
app/assets/stylesheets/lookbook
— 사용자 정의 SASS 코드용
JavaScript 및 SASS 코드는 레이아웃에 수동으로 포함해야 함을 유의하세요.