139 lines
6.8 KiB
Markdown
139 lines
6.8 KiB
Markdown
---
|
|
stage: none
|
|
group: unassigned
|
|
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
|
|
---
|
|
|
|
# HAML
|
|
|
|
[HAML](https://haml.info/) is the [Ruby on Rails](https://rubyonrails.org/) template language that GitLab uses.
|
|
|
|
## HAML and our Pajamas Design System
|
|
|
|
[GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/) is a Vue component library that conforms
|
|
to the [Pajamas design system](https://design.gitlab.com/). Many of these components
|
|
rely on JavaScript and therefore can only be used in Vue.
|
|
|
|
However, some of the simpler components (such as buttons, checkboxes, or form inputs) can be
|
|
used in HAML:
|
|
|
|
- Some of the Pajamas components are available as a [ViewComponent](view_component.md#pajamas-components). Use these when possible.
|
|
- If no ViewComponent exists, why not go ahead and create it? Talk to the Foundations team if you need help.
|
|
- As a fallback, this can be done by applying the correct CSS classes to the elements.
|
|
- A custom
|
|
[Ruby on Rails form builder](https://gitlab.com/gitlab-org/gitlab/-/blob/7c108df101e86d8a27d69df2b5b1ff1fc24133c5/lib/gitlab/form_builders/gitlab_ui_form_builder.rb) exists to help use GitLab UI components in HAML forms.
|
|
|
|
### Use the GitLab UI form builder
|
|
|
|
To use the GitLab UI form builder:
|
|
|
|
1. Change `form_for` to `gitlab_ui_form_for`.
|
|
1. Change `f.check_box` to `f.gitlab_ui_checkbox_component`.
|
|
1. Remove `f.label` and instead pass the label as the second argument in `f.gitlab_ui_checkbox_component`.
|
|
|
|
For example:
|
|
|
|
- Before:
|
|
|
|
```haml
|
|
= form_for @group do |f|
|
|
.form-group.gl-mb-3
|
|
.gl-form-checkbox.custom-control.custom-checkbox
|
|
= f.check_box :prevent_sharing_groups_outside_hierarchy, disabled: !can_change_prevent_sharing_groups_outside_hierarchy?(@group), class: 'custom-control-input'
|
|
= f.label :prevent_sharing_groups_outside_hierarchy, class: 'custom-control-label' do
|
|
%span
|
|
= s_('GroupSettings|Prevent members from sending invitations to groups outside of %{group} and its subgroups.').html_safe % { group: link_to_group(@group) }
|
|
%p.help-text= prevent_sharing_groups_outside_hierarchy_help_text(@group)
|
|
|
|
.form-group.gl-mb-3
|
|
.gl-form-checkbox.custom-control.custom-checkbox
|
|
= f.check_box :lfs_enabled, checked: @group.lfs_enabled?, class: 'custom-control-input'
|
|
= f.label :lfs_enabled, class: 'custom-control-label' do
|
|
%span
|
|
= _('Allow projects within this group to use Git LFS')
|
|
= link_to sprite_icon('question-o'), help_page_path('topics/git/lfs/index')
|
|
%p.help-text= _('This setting can be overridden in each project.')
|
|
```
|
|
|
|
- After:
|
|
|
|
```haml
|
|
= gitlab_ui_form_for @group do |f|
|
|
.form-group.gl-mb-3
|
|
= f.gitlab_ui_checkbox_component :prevent_sharing_groups_outside_hierarchy,
|
|
s_('GroupSettings|Prevent members from sending invitations to groups outside of %{group} and its subgroups.').html_safe % { group: link_to_group(@group) },
|
|
help_text: prevent_sharing_groups_outside_hierarchy_help_text(@group),
|
|
checkbox_options: { disabled: !can_change_prevent_sharing_groups_outside_hierarchy?(@group) }
|
|
|
|
.form-group.gl-mb-3
|
|
= f.gitlab_ui_checkbox_component :lfs_enabled, checkbox_options: { checked: @group.lfs_enabled? } do |c|
|
|
= c.label do
|
|
= _('Allow projects within this group to use Git LFS')
|
|
= link_to sprite_icon('question-o'), help_page_path('topics/git/lfs/index')
|
|
= c.help_text do
|
|
= _('This setting can be overridden in each project.')
|
|
```
|
|
|
|
### Available components
|
|
|
|
When using the GitLab UI form builder, the following components are available for use in HAML.
|
|
|
|
NOTE:
|
|
Currently only the listed components are available but more components are planned.
|
|
|
|
<!-- vale gitlab.Spelling = NO -->
|
|
|
|
#### gitlab_ui_checkbox_component
|
|
|
|
<!-- vale gitlab.Spelling = YES -->
|
|
|
|
[GitLab UI Docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-form-form-checkbox--default)
|
|
|
|
##### Arguments
|
|
|
|
| Argument | Description | Type | Required (default value) |
|
|
|---|---|---|---|
|
|
| `method` | Attribute on the object passed to `gitlab_ui_form_for`. | `Symbol` | `true` |
|
|
| `label` | Checkbox label. `label` slot can be used instead of this argument if HTML is needed. | `String` | `false` (`nil`) |
|
|
| `help_text` | Help text displayed below the checkbox. `help_text` slot can be used instead of this argument if HTML is needed. | `String` | `false` (`nil`) |
|
|
| `checkbox_options` | Options that are passed to [Rails `check_box` method](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-check_box). | `Hash` | `false` (`{}`) |
|
|
| `checked_value` | Value when checkbox is checked. | `String` | `false` (`'1'`) |
|
|
| `unchecked_value` | Value when checkbox is unchecked. | `String` | `false` (`'0'`) |
|
|
| `label_options` | Options that are passed to [Rails `label` method](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-label). | `Hash` | `false` (`{}`) |
|
|
|
|
##### Slots
|
|
|
|
This component supports [ViewComponent slots](https://viewcomponent.org/guide/slots.html).
|
|
|
|
| Slot | Description
|
|
|---|---|
|
|
| `label` | Checkbox label content. This slot can be used instead of the `label` argument. |
|
|
| `help_text` | Help text content displayed below the checkbox. This slot can be used instead of the `help_text` argument. |
|
|
|
|
<!-- vale gitlab.Spelling = NO -->
|
|
|
|
#### gitlab_ui_radio_component
|
|
|
|
<!-- vale gitlab.Spelling = YES -->
|
|
|
|
[GitLab UI Docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-form-form-radio--default)
|
|
|
|
##### Arguments
|
|
|
|
| Argument | Description | Type | Required (default value) |
|
|
|---|---|---|---|
|
|
| `method` | Attribute on the object passed to `gitlab_ui_form_for`. | `Symbol` | `true` |
|
|
| `value` | The value of the radio tag. | `Symbol` | `true` |
|
|
| `label` | Radio label. `label` slot can be used instead of this argument if HTML content is needed inside the label. | `String` | `false` (`nil`) |
|
|
| `help_text` | Help text displayed below the radio button. `help_text` slot can be used instead of this argument if HTML content is needed inside the help text. | `String` | `false` (`nil`) |
|
|
| `radio_options` | Options that are passed to [Rails `radio_button` method](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-radio_button). | `Hash` | `false` (`{}`) |
|
|
| `label_options` | Options that are passed to [Rails `label` method](https://api.rubyonrails.org/classes/ActionView/Helpers/FormBuilder.html#method-i-label). | `Hash` | `false` (`{}`) |
|
|
|
|
##### Slots
|
|
|
|
This component supports [ViewComponent slots](https://viewcomponent.org/guide/slots.html).
|
|
|
|
| Slot | Description
|
|
|---|---|
|
|
| `label` | Checkbox label content. This slot can be used instead of the `label` argument. |
|
|
| `help_text` | Help text content displayed below the radio button. This slot can be used instead of the `help_text` argument. |
|