diff options
Diffstat (limited to 'doc/development/fe_guide/view_component.md')
-rw-r--r-- | doc/development/fe_guide/view_component.md | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/doc/development/fe_guide/view_component.md b/doc/development/fe_guide/view_component.md new file mode 100644 index 00000000000..f4bb7ac3a2e --- /dev/null +++ b/doc/development/fe_guide/view_component.md @@ -0,0 +1,174 @@ +--- +stage: Ecosystem +group: Foundations +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# ViewComponent + +ViewComponent is a framework for creating reusable, testable & encapsulated view +components with Ruby on Rails, without the need for a JavaScript framework like Vue. +They are rendered server-side and can be seamlessly used with template languages like [Haml](haml.md). + +Refer to the official [documentation](https://viewcomponent.org/) to learn more or +watch this [introduction video](https://youtu.be/akRhUbvtnmo). + +## Pajamas components + +Some of the components of our [Pajamas](https://design.gitlab.com) design system are +available as a ViewComponent in `app/components/pajamas`. + +NOTE: +We have a small but growing number of Pajamas components. Reach out to the +[Foundations team](https://about.gitlab.com/handbook/engineering/development/dev/ecosystem/foundations/) +if the component you are looking for is not yet available. + +### Available components + +#### Alert + +The `Pajamas::AlertComponent` follows the [Pajamas Alert](https://design.gitlab.com/components/alert) specification. + +**Examples:** + +By default this creates a dismissible info alert with icon: + +```haml += render Pajamas::AlertComponent.new(title: "Almost done!") +``` + +You can set variant, hide the icons and more: + +```haml += render Pajamas::AlertComponent.new(title: "All done!", + variant: :success, + dismissible: :false, + show_icon: false) +``` + +For the full list of options, see its +[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/alert_component.rb). + +#### Banner + +The `Pajamas::BannerComponent` follows the [Pajamas Banner](https://design.gitlab.com/components/banner) specification. + +**Examples:** + +In its simplest form the banner component looks like this: + +```haml += render Pajamas::BannerComponent.new(button_text: 'Learn more', button_link: example_path, + svg_path: 'illustrations/example.svg') do |c| + - c.title { 'Hello world!' } + %p Content of your banner goes here... +``` + +If you have a need for more control, you can also use the `illustration` slot +instead of `svg_path` and the `primary_action` slot instead of `button_text` and `button_link`: + +```haml += render Pajamas::BannerComponent.new do |c| + - c.illustration do + = custom_icon('my_inline_svg') + - c.title do + Hello world! + - c.primary_action do + = render 'my_button_in_a_partial' +``` + +For the full list of options, see its +[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/banner_component.rb). + +#### Button + +The `Pajamas::ButtonComponent` follows the [Pajamas Button](https://design.gitlab.com/components/button) specification. + +**Examples:** + +The button component has a lot of options but all of them have good defaults, +so the simplest button looks like this: + +```haml += render Pajamas::ButtonComponent.new do |c| + = _('Button text goes here') +``` + +The following example shows most of the available options: + +```haml += render Pajamas::ButtonComponent.new(category: :secondary, + variant: :danger, + size: :small, + type: :submit, + disabled: true, + loading: false, + block: true) do |c| + Button text goes here +``` + +You can also create button-like looking `<a>` tags, like this: + +```haml += render Pajamas::ButtonComponent.new(href: root_path) do |c| + Go home +``` + +For the full list of options, see its +[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/button_component.rb). + +#### Card + +The `Pajamas::CardComponent` follows the [Pajamas Card](https://design.gitlab.com/components/card) specification. + +**Examples:** + +The card has one mandatory `body` slot and optional `header` and `footer` slots: + +```haml += render Pajamas::CardComponent.new do |c| + - c.header do + I'm the header. + - c.body do + %p Multiple line + %p body content. + - c.footer do + Footer goes here. +``` + +If you want to add custom attributes to any of these or the card itself, use the following options: + +```haml += render Pajamas::CardComponent.new(card_options: {id: "my-id"}, body_options: {data: { count: 1 }}) +``` + +`header_options` and `footer_options` are available, too. + +For the full list of options, see its +[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/card_component.rb). + +#### Toggle + +The `Pajamas::ToggleComponent` follows the [Pajamas Toggle](https://design.gitlab.com/components/toggle) specification. + +```haml += 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. +``` + +NOTE: +**The toggle ViewComponent is special as it depends on the Vue.js component.** +To actually initialize this component, make sure to call the `initToggle` helper from `~/toggles`. + +For the full list of options, see its +[source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/components/pajamas/toggle_component.rb). + +### Best practices + +- If you are about to create a new view in Haml, use the available components + over creating plain Haml tags with CSS classes. +- If you are making changes to an existing Haml view and see, for example, a + button that is still implemented with plain Haml, consider migrating it to use a ViewComponent. |