PRO-2355 document component admin UI extension patterns #153
Conversation
PRO-2355 Document how to override admin UI components
This is not a deep dive into everything you can learn by reading the source of the component you're overriding. It's a guide to the two patterns for overriding itself (same name, and configuration). |
|
@boutell Are you looking for an initial review? |
boutell
changed the title
|
This is now ready for proper review. In the end I was able to cover the three major cases right now — override by name, override by configuration (for situations where subclassing makes override by name a bad idea), and custom schema fields, which includes a full example. You can find a working example of the custom schema field shown here in the |
…d in a better pedagogical order that emphasizes adding things (custom schema field types, custom columns) over overriding things
|
Implemented Bea's notes, added custom column coverage, and reorganized in a better pedagogical order that emphasizes adding things (custom schema field types, custom columns) over overriding things |
|
@boutell The big thing I'm seeing as I start review is that the custom field types section is still part of the same UI page. That should be a separate code recipe page (how to). |
docs/guide/custom-ui.md
Outdated
|
|
||
| ## Overriding standard Vue.js components through configuration | ||
|
|
||
| There can be only one `AposDocsManager` Vue.js component definition in a project, but sometimes we need different behavior for a specific piece type only. We could work around this by overriding a core component and adding conditional logic, but this results in code that is hard to maintain, and also means we are stuck maintaining a copy of a complex component and missing out on bug fixes and improvements. It would be better if we could **specify a different, custom component name to be used** to manage a particular piece type. |
There was a problem hiding this comment.
There are a few previous comments that you don't seem to have addressed here.
Remove "Vue.js" from "only one AposDocsManager Vue.js component in a project". Not critical, but repetitive.
Remove "only" at the end of the second sentence as it's redundant.
We could work around this by overriding" to "We could override" (then, "and add"). Period after "hard to maintain," then new sentence.
It would be better if we could...
"Could" isn't necessary since the purpose here is to show they can. Simply "It would be better to specify...".
| The `AposWidget` component has **nothing to do with a typical site visitor experience.** It is used only when displaying our widget while the page is in edit mode. While overriding this component is rare, but the `@apostrophecms/rich-text-widget` module does so to provide a "click the text to edit" experience for rich text widgets. If you're just trying to enhance your widget with frontend JavaScript, you should write a [widget player](custom-widgets.md#client-side-javascript-for-widgets) instead. | ||
| ::: | ||
|
|
||
| ## Registering custom field types |
There was a problem hiding this comment.
This should be a code recipe page instead. It's a separate section in the navigation. If you break this out to a new page I can help with the nav.
I see the value for this topic in terms of expanding UI options. It would make sense to have a paragraph that introduces this idea and links over to the code recipe. There's simply more to custom field types than customizing UI.
|
I've refactored as requested. It makes sense for it to be a separate article. However I wanted to run a concern by you: I'm not convinced this new article belongs in "cookbook" and not "guide." Compare it to "custom batch operations" or "custom widgets." It's similar in structure and its role is similarly to document a clearly defined core feature with examples. "Cookbook" so far seems to be the domain of things that aren't Apostrophe features per se but Apostrophe devs want to know more about, like navigation or specific hosting situations. Custom schema field types aren't a special case or a particular application, they are a primary feature with a well-defined boundary. As a user I would expect to be able to find them in the side nav of the guide with similar topics, but instead they are in the cookbook which is not part of that. "Advanced topics" within the guide seems like the more natural place. |
|
That's a good point. It makes sense to me to put it in a nav section such as "Other customizations" parallel to "Other module config." |
|
Would you mind doing that part after this PR lands since you have the
clearest sense of how to handle the nav?
…On Wed, Jan 5, 2022 at 10:39 AM Alex Bea ***@***.***> wrote:
That's a good point. It makes sense to me to put it in a nav section such
as "Other customizations" parallel to "Other module config."
—
Reply to this email directly, view it on GitHub
<#153 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAH27P4U6HVGCFKNT6M6H3UURQ2XANCNFSM5IW4IABA>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.
You are receiving this because you were mentioned.Message ID:
***@***.***>
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
|
|
sure |
No description provided.