mirror of
https://github.com/opf/openproject.git
synced 2026-06-14 03:30:14 +00:00
Henriette Darge
101 lines
4.5 KiB
Plaintext
101 lines
4.5 KiB
Plaintext
The Status button communicates the current status of something (like a meeting or a work package) using a label and a colour. Optionally, it allows the user to change the status to something else. The button triggers an action menu with alternate statuses. In read-only mode, the status button does not offer any interaction.
|
|
|
|
The colours adapt automatically to the currently active mode (light/dark/light high contrast).
|
|
|
|
## Overview
|
|
|
|
<%= embed OpPrimer::StatusButtonComponentPreview, :playground %>
|
|
|
|
## Anatomy
|
|
|
|
The component provides two variants:
|
|
|
|
**1. With colour markers**
|
|
|
|
For any selectable status item, a small colour marker will be displayed. The colour of this marker is determined by our internal colour helpers.
|
|
|
|
<%= embed OpPrimer::StatusButtonComponentPreview, :playground %>
|
|
|
|
**2. With icons and colours**
|
|
|
|
The button will be coloured, along with a leading icon in the foreground colour (the same as the text). The action dropdown menu will also show icons; the dropdown will not, however, show colours.
|
|
|
|
<%= embed OpPrimer::StatusButtonComponentPreview, :with_icon %>
|
|
|
|
## Best practices
|
|
|
|
**Do**
|
|
|
|
- Use the component when each status needs a colour. (Eg. meeting or work package status)
|
|
- Specify the colour for each status; these colours are not automatically set via Primer and must be manually entered. However, using named Primer colour variables is encouraged (although a hex code will also work, thanks to the internal colour helpers who will translate it to other colour modes).
|
|
|
|
**Don't**
|
|
|
|
- Don't use the component if the status is not coloured. You can simply use an ActionMenu for this case.
|
|
|
|
## Used in
|
|
|
|
The component is used in:
|
|
|
|
* Meetings to signal the status of the meeting, as well as providing options to change it.
|
|
* It will be used in the future for the work package status.
|
|
|
|
## Examples
|
|
|
|
For detailed examples have a look at the other [preview examples](/lookbook/inspect/OpenProject/Primer/status_button/playground) of the component.
|
|
|
|
This is an example playground of the `OpPrimer::StatusButtonComponent`.
|
|
|
|
<%= embed OpPrimer::StatusButtonComponentPreview, :playground, panels: %i[params source] %>
|
|
|
|
## Technical notes
|
|
|
|
The StatusButton component is a composition of a Primer Button and Primer ActionMenu. You provide options of statuses using the `OpPrimer::StatusButtonOption`. In there, you can pass:
|
|
|
|
* `name`: (required) the name of the option
|
|
* `icon`: (optional) the leading icon
|
|
* `color_ref`: (optional) The reference of the object to be coloured (for persisted items (like WorkPackage status or type), this is the ID, otherwise some other unique identifier)
|
|
* `color_namespace`: (optional, although it is required when setting `color_ref`) The namespace is usually the name of the coloured objects (e.g "status", "type", "meeting_status".
|
|
|
|
The `color_ref` and `color_namespace` are used together to build internally the highlighting classes for the options (e.g `__hl_inline_status_1`)
|
|
|
|
**Note** For this to work, your `color_namespace` has to be registered so that the classes are created beforehand. Have a look [here](https://github.com/opf/openproject/blob/dev/app/views/highlighting/styles.css.erb) on how this is done for the already existing namespaces.
|
|
|
|
```css
|
|
<%# For persisted objects %>
|
|
<%= resources_scope_color_css("status", ::Status) %>
|
|
<%= resources_scope_color_css("priority", ::IssuePriority) %>
|
|
<%= resources_scope_color_css("type", ::Type, inline_foreground: true) %>
|
|
|
|
<%# For non-persisted objects %>
|
|
<% Meetings::Statuses::AVAILABLE.each do |meeting_status| %>
|
|
<%= resource_color_css("meeting_status", meeting_status) %>
|
|
<% end %>
|
|
```
|
|
|
|
### Code structure
|
|
|
|
The status button can be called directly
|
|
|
|
```html
|
|
<%=
|
|
items = [
|
|
OpPrimer::StatusButtonOption.new(name: "Closed",
|
|
icon: :lock,
|
|
color_ref: 1,
|
|
color_namespace: "status",
|
|
tag: :a,
|
|
href: "/bar")
|
|
]
|
|
component = OpPrimer::StatusButtonComponent.new(current_status: items.first,
|
|
items: items,
|
|
readonly: false,
|
|
button_arguments: { size: :medium, title: "foo" })
|
|
end
|
|
%>
|
|
```
|
|
|
|
Further, you can pass all options you'd want to pass to the `ActionMenu` item, e.g the description:
|
|
|
|
<%= embed OpPrimer::StatusButtonComponentPreview, :with_description %>
|