ビューコンポーネント
ViewComponentは、VueのようなJavaScriptフレームワークを使うことなく、Ruby on Railsで再利用可能でテスト可能かつカプセル化されたビューコンポーネントを作成するためのフレームワークです。ビューコンポーネントはサーバサイドでレンダリングされ、Hamlのようなテンプレート言語とシームレスに使用できます。
Lookbookでコンポーネントをブラウズ
ViewComponentのプレビューをブラウズして操作するために、http://gdk.test:3000/rails/lookbook （開発者のみ使用可能）にLookbookがあります。
パジャマコンポーネント
Pajamasデザインシステムのコンポーネントの一部は、app/components/pajamas のViewComponentとして利用できます。
利用可能なコンポーネント
このリストはベストエフォートです。完全なリストはapp/components/pajamasにあります。また、当社のコンポーネントをよりインタラクティブに閲覧するには、当社のルックブック(http://gdk.test:3000/rails/lookbook)を参照してください。
アラート
Pajamas::AlertComponent はパジャマ・アラート仕様に準拠しています。
例
デフォルトでは、アイコンの付いた解除可能な情報アラートが作成されます：
= render Pajamas::AlertComponent.new(title: "Almost done!")
バリアントの設定、アイコンの非表示などができます：
= render Pajamas::AlertComponent.new(title: "All done!",
variant: :success,
dismissible: :false,
show_icon: false)
オプションの完全なリストについては、ソースを参照してください。
バナー
Pajamas::BannerComponent はパジャマバナーの仕様に準じます。
例
最も単純なバナーコンポーネントは次のようになります：
= 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 はパジャマボタンの仕様に準拠しています。
例
ボタン・コンポーネントにはたくさんのオプションがありますが、どれもデフォルトが良いので、最も単純なボタンは次のようになります：
= render Pajamas::ButtonComponent.new do |c|
= _('Button text goes here')
次の例は、利用可能なオプションのほとんどを示しています：
= render Pajamas::ButtonComponent.new(category: :secondary,
variant: :danger,
size: :small,
type: :submit,
disabled: true,
loading: false,
block: true) do |c|
Button text goes here
このように、ボタンのような<a> タグを作成することもできます：
= render Pajamas::ButtonComponent.new(href: root_path) do |c|
Go home
オプションの完全なリストについては、ソースを参照してください。
カード
Pajamas::CardComponent はパジャマカードの仕様に準拠しています。
例
このカードには、必須のbody スロットが1つ、オプションのheader とfooter スロットがあります：
= render Pajamas::CardComponent.new do |c|
- c.with_header do
I'm the header.
- c.with_body do
%p Multiple line
%p body content.
- c.with_footer do
Footer goes here.
これらのスロットやカード自体にカスタム属性を追加したい場合は、以下のオプションを使います：
= render Pajamas::CardComponent.new(card_options: {id: "my-id"}, body_options: {data: { count: 1 }})
header_options やfooter_options 。
オプションの完全なリストについては、ソースを参照してください。
チェックボックスタグ
Pajamas::CheckboxTagComponent はパジャマチェックボックスの仕様に従っています。
name 引数とlabel スロットは必須です。
使用例：
= render Pajamas::CheckboxTagComponent.new(name: 'project[initialize_with_sast]',
checkbox_options: { data: { qa_selector: '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|Enable Static Application Security Testing (SAST)')
- c.with_help_text do
= s_('ProjectsNew|Analyze your source code for known security vulnerabilities.')
= link_to _('Learn more.'), help_page_path('user/application_security/sast/index'), target: '_blank', rel: 'noopener noreferrer', data: { track_action: 'followed' }
オプションの完全なリストについては、ソースを参照してください。
チェックボックス
Pajamas::CheckboxComponent はパジャマチェックボックスの仕様に従っています。
Pajamas::CheckboxComponent はGitLab UI フォームビルダー内部で使用され、form 引数としてActionView::Helpers::FormBuilderのインスタンスを渡す必要があります。この ViewComponent のレンダリングにはgitlab_ui_checkbox_component メソッドを使用するのが望ましいです。ActionView::Helpers::FormBuilderのインスタンスなしでチェックボックスを使用するには、Pajamas::CheckboxComponentCheckboxTagComponentをPajamas::CheckboxComponent使用してください。オプションの完全なリストについては、ソースを参照してください。
トグル
Pajamas::ToggleComponent はパジャマトグルの仕様に準拠しています。
= 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)
Leverage this block to render a rich help text. To render a plain text help text, prefer the `help` parameter.
~/toggles からinitToggle ヘルパーを呼び出してください。オプションの完全なリストについては、ソースを参照してください。
レイアウト
レイアウトコンポーネントは、GitLabで使用される一般的なレイアウトパターンを作成するために使用することができます。
利用可能なコンポーネント
水平セクション
多くの設定ページでは、タイトルと説明が左にあり、設定フィールドが右にあるレイアウトが使われています。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
オプションの完全なリストについては、ソースを参照してください。
ベストプラクティス
- Hamlで新しいビューを作成する場合、CSSクラスでプレーンなHamlタグを作成するよりも、利用可能なコンポーネントを使用してください。
- 既存のHamlビューに変更を加える場合、例えばボタンがまだプレーンなHamlで実装されている場合は、ViewComponentを使用するようにマイグレーションすることを検討してください。
- 新しいコンポーネントを作成する場合は、プレビューの作成も検討してください。そうすることで、他の人がLookbookであなたのコンポーネントを発見するのに役立ちますし、異なる状態をテストするのがより簡単になります。