[#64474] Begin documenting Attribute help texts #20910
Conversation
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation for the Attribute Help Texts feature in OpenProject. The documentation explains how administrators can provide additional contextual information for work package and project attributes, and how these help texts are automatically rendered in Primer forms.
Key Changes:
- Documents the automatic rendering of attribute help texts in Primer forms
- Lists all supported input field types
- Provides examples for standard forms, custom fields, and customization options
myabc
force-pushed
the
code-maintenance/64474-attribute-help-texts
branch
from
52162e7 to
ae3daef
Compare
|
@HDinger I think this is OK as a start. I've implemented this as a page (under Patterns) rather than component docs. Things that could be added:
|
|
Caution The provided work package version does not match the core version Details:
Please make sure that:
|
| - `action_menu(**, &)` | ||
| - `auto_complete(**, &)` | ||
| - `autocompleter(**, &)` | ||
| - `block_note_editor(**, &)` | ||
| - `button(**, &)` | ||
| - `check_box_group(**, &)` | ||
| - `check_box(**, &)` | ||
| - `color_select_list(**, &)` | ||
| - `multi(**, &)` | ||
| - `pattern_input(**, &)` | ||
| - `project_autocompleter(**, &)` | ||
| - `radio_button_group(**, &)` | ||
| - `range_date_picker(**)` | ||
| - `rich_text_area(**)` | ||
| - `select_list(**, &)` | ||
| - `single_date_picker(**)` | ||
| - `storage_manual_project_folder_selection(**)` | ||
| - `submit(**, &)` | ||
| - `text_area(**, &)` | ||
| - `text_field(**, &)` | ||
| - `work_package_autocompleter(**, &)` |
There was a problem hiding this comment.
Is it worth including this list - or will it just be an issue keeping it up-to-date. Can we include this list from elsewhere?
| ### For Component authors | ||
|
|
||
| If you create a new input method (by extending | ||
| `Primer::Forms::Dsl::Input` and adding an accompanying method to |
There was a problem hiding this comment.
We should publish API docs somewhere and link.
myabc
force-pushed
the
code-maintenance/64474-attribute-help-texts
branch
from
e37150b to
52d3f80
Compare
myabc
force-pushed
the
code-maintenance/64474-attribute-help-texts
branch
from
52d3f80 to
c72d1a9
Compare
|
|
||
| You may also wish to show help texts when displaying attributes to the user. You | ||
| can use `AttributeLabelComponent` as shown above, passing the model and | ||
| applicable attribute. This takes care of finding an instantiating the Attribute |
There was a problem hiding this comment.
This takes care of finding and instantiating the Attribute
There was a problem hiding this comment.
I understand that this is a first draft, but imho, the previews are crutial to understand all of it. You and I know what it is about, how it was implemented and how the result looks like, however I fear that outstanders will not get it without some visual help.
Further, I am missing somehow the explanation how the attribute help texts are automatically added. You mentioned it shortly with decorate_options for component authors, but I think it worth explaining it a little bit more in detail
| additional information for attributes of certain entities in OpenProject. | ||
| Currently, work packages and projects are supported. | ||
|
|
||
| Our [System admin guide][system_admin_guide] provides guidance for |
There was a problem hiding this comment.
This is not a valid link
| Our [System admin guide][system_admin_guide] provides guidance for | |
| Our [System admin guide](https://www.openproject.org/docs/system-admin-guide/attribute-help-texts/) provides guidance for |
| `additional_label` slot). It renders without a wrapper and the caller is | ||
| responsible for finding and passing an instance of `AttributeHelpText`. | ||
|
|
||
| ```erb |
There was a problem hiding this comment.
Here at the latest a preview should be shown instead of a normal code block
| } | ||
| ) | ||
| end | ||
| end |
There was a problem hiding this comment.
Ideally, this would also be a preview, so that you see the code as well as the result. Otherwise nobody will get where the attributehelpText is rendered
| There is also an Angular `attribute-help-text` component available. It renders | ||
| identically to its Rails `AttributeHelpTextComponent` counterpart. Set the | ||
| attribute name using the `attribute` property and model name using | ||
| `attributeScope` (in `PascalCase`). |
There was a problem hiding this comment.
I think, we should mark that part somehow as deprected otherwise people will use again..
Ticket
https://community.openproject.org/wp/64474
What are you trying to accomplish?
Screenshots
What approach did you choose and why?
Merge checklist