Add a mention of the /@@test-rendering views to the developer documentation for Classic UI

[acsr]

Hidden Design Elements Previews in Plone

In the ClassicUI we have a @@test_rendering view
This renders examples of most UI elements using the active CSS styling.

This useful hidden feature is not mentioned or searchable in the docs or trainings.

How to enter these pages

• in a Plone ClassicUI site append /@@test-rendering to any url
• from there you can enter three tabs:
  - [Test Rendering] ./@@test-rendering
  - [Bootstrap Cheatsheet]./@@test-rendering-cheatsheet
  - [Icons] ./@@test-rendering-icons

ToDo

Add a chapter or notes to the docs and trainings for people in need to look up styling and available elements in Plone

Related Questions

1. Is this feature deprecated and or unsupported? It was present since at least Plone 3 (in Plone 2.5 we had /test_rendering)
2. Is there any related view for Volto?
3. How are the Storybook attempts in e.g. Mockup related to this?

[acsr]

the source is in https://github.com/plone/Products.CMFPlone/tree/master/Products/CMFPlone/browser/templates

• Products/CMFPlone/browser/templates/test_rendering.pt
• Products/CMFPlone/browser/templates/test_rendering_cheatsheet.pt
• Products/CMFPlone/browser/templates/test_rendering_icons.pt

[Manas-Kenge]

Hey @acsr, I reproduced the view as you mentioned and saw the three tabs. Should I start working on the documentation, or is there any ongoing discussion with other maintainers?

[acsr]

Hey @Manas-Kenge I reformatted my questions as ordered list and answer myself. I do not know of a discussion elsewhere.

1. I think you can ignore the deprecation question until someone points us to a state. The templates were updated for Plone 5 in 2019 and are maintained as necessary until 2 years ago.

• They are still availabe and useful but undocumented.
• The feature should be documented and this can be helpful.
• These templates can help during migrations.
• A deprecation note can be added in a second step or during review of the docs.

Note: I would include at least a note on the presence in older versions because it is not documented there:

The view @@test-rendering was available since at least Plone 3 (in Plone 2.5 we had /test_rendering)

For the other stuff I will ask in the forum:
2. Since this ticket is explicitly targeting the ClassicUI you can ignore my question related to VoltoUI
3. Off Topic here, just asking if someone knows a relation to connect this. Storybook is an approach to document UI elements (e.g. in plone.mockup) with live code examples.

[acsr]

Addendum: The answer to my points 2. + 3. related to the equivalent to test_rendering in Volto and Storybook were answered in the Forum: pointing to Plone Documentation v6/VoltoUI/Contributing to Volto and there Style Guide and Documentation mentioning the Storybook build and a bit hidden:

in Storybook entry

… When you develop a component, we encourage you to create or update its Volto Storybook entry.…

This is actually not either Reference Documentation or HowTo.

Ideas & questions how to crosslink both topics can be found in my comment to the forum post.

This can be part of the next iteration.

[Manas-Kenge]

@acsr I read the discussion about adding a crosslink between the /@@test-rendering documentation and the Volto Storybook. Would you like me to include this crosslink as part of the documentation update, or is this still an idea that needs confirmation?

[acsr]

@Manas-Kenge I am sorry to only offer a discussion with myself (and you). I hope it is helpful to share the considerations.

1. Since we are motivating to a move to Volto I would definitely add a "see also:" to the /@@test-rendering documentation.
   The see also could also be pointing at migration hints if we decide to choose that approach (see below).

2. I had currently no final opinion for the Volto counterpart, because the docs for the Storyboard are buried in the Contributing to Volto section. The crosslink / tags should go in a unwritten reference in the VoltoUI/Theming story paragraph but this is currently outdated and pointing to Semantic UI styling. Until then it only makes sense in VoltoUI/Contributing to Volto/Style Guide.

While writing this down (rubberducking) I am thinking about an additional approach putting a mention of @@test-rendering test_rendering and Storyboard docs into a section on theming in the migration docs under Migrating from Plone Classic UI to Volto.

This allows to find the terms in context when searching without bloating the docs in detail an avoid being prone to be outdated.

Example for possible /@@test_rendering documentation only to save you some time

If you are looking for an overview of UI components in the VoltoUI you can find informations on [Storybook](https://storybook.js.org/) currently under [VoltoUI/Contributing to Volto/Style Guide](https://6.docs.plone.org/volto/contributing/style-guide.html) and in the [documentation of the related make commands ](https://6.docs.plone.org/volto/contributing/documentation.html#storybook-entry)

[acsr]

Update: Listening to the ClassicUI team meeting now, @stevepiercy confirmed there the relevance of Storyboard for ClassicUI there and I agree and am seconding.

[acsr]

I accidentially mangled up my correction of spelling of the ids, and reverted all occurrences to the correct wording (hope I did not miss one.

• In Plone 2.5 the url appended was: /test_rendering with underscore
• In Plone 3+ the url is /@@test-rendering` with hyphen, the page templates filenames still use underscores