Add description for different types of blocks #4166

MAX-786 · 2022-12-21T23:28:45Z

Added description of Volto Blocks and for every different type of block. Also added relevant screenshots.

netlify · 2022-12-21T23:28:50Z

✅ Deploy Preview for volto ready!

Name	Link
🔨 Latest commit	`f2a312e`
🔍 Latest deploy log	https://app.netlify.com/sites/volto/deploys/63a5d627c5a965000735a7ff
😎 Deploy Preview	https://deploy-preview-4166--volto.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

cypress · 2022-12-21T23:32:01Z

Test summary

14 • 0 • 0 • 0

Run details


Project	Volto
Status	Passed
Commit	`f2a312e`
Started	Dec 23, 2022 11:45 PM
Ended	Dec 23, 2022 11:48 PM
Duration	03:07 💡
OS	Linux Ubuntu -
Browser	Chrome 108

View run in Cypress Dashboard ➡️

This comment has been generated by cypress-bot as a result of this project's GitHub integration settings. You can manage this integration in this project's settings in the Cypress Dashboard

ksuess

This is definitely an enhancement.
Would you mind adding also a section for the search block?

docs/source/user-manual/blocks.md

Co-authored-by: Katja Süss <[email protected]>

Co-authored-by: Steve Piercy <[email protected]>

stevepiercy

Thank you for starting this page. Animated gifs are awesome! I started a review, but it got too long and complicated with lots of nitpicky details. Yet you inspired me to take your work further by making many enhancements. Perhaps too many 😁.

Here's a summary of the nitpicks, and general guidance to writing documentation—some of which I realized only while working on this page (and which I should add to our Docs Contributing Guide):

Use dashes - in filenames and avoid underscores.
Images should be no wider than 740 pixels to fit within the documentation's main view port. This avoids scaling and reducing legibility. To make that work in Volto, set your browser width to 1180 pixels. You will notice that the drag and trash icons for each block move inside the block from outside. This is a TIL (thing I learned).
Screenshots of each step are helpful. It is painstaking, but totally worth it.
Provide sufficient detail of what each option is and does.
Avoid repetitive statements.
Avoid marketing speak. Words such as "powerful", "easy", "simple" come off as hyping a feature, instead of plainly describing what it is and does.
Avoid empty phrases and clauses. Short, terse sentences are preferred. For example:
- "An images grid block is a type of block in Volto that allows users to display a grid of images on a page."
- "An images grid block displays a row of images on a page."
Headings should be Sentence cased, not Title Cased.

sneridagh

@MAX-786 the grid and the system ones are not official Plone/Volto blocks, although they are present in the demo.

I'd leave the grid one for now (it's planned for Plone 6.1) and remove the system one, since it's a demo site block only.

For the rest, great addition!

MAX-786 · 2022-12-23T11:34:27Z

Thank you so much for your thorough review and for taking the time to provide such thoughtful feedback. Your insights and suggestions are greatly appreciated and will be very valuable to me.

Provide sufficient detail of what each option is and does.

I thought of doing it but it made me nervous as it got too long 😖, I'll make sure nxt time.

Avoid repetitive statements.

Avoid marketing speak. Words such as "powerful", "easy", "simple" come off as hyping a feature, instead of plainly describing what it is and does.

Sure I'll remember next time. btw That is something I got from my college (pitching vibes)😂, I need to suppress those feelings😖.
Thanks, everyone for your help.

MAX-786 · 2022-12-23T14:27:39Z

@MAX-786 the grid and the system ones are not official Plone/Volto blocks, although they are present in the demo.

I'd leave the grid one for now (it's planned for Plone 6.1) and remove the system one, since it's a demo site block only.

For the rest, great addition!

Thanks for the review, Can you please tell me if these changes should be done by me or if you have already done them, as I can still see the System Block in the last commit?

stevepiercy · 2022-12-23T15:30:45Z

@MAX-786 please make the requested changes from @sneridagh. Thank you!

MAX-786 · 2022-12-23T16:24:47Z

It's Done! Thanks.

tiberiuichim · 2022-12-23T16:35:24Z

OMG you're actually doing this! Writing a user manual for Volto. You two are awesome!

MAX-786 · 2022-12-23T20:51:54Z

And as I have limited knowledge of cypress..... this 1 failing test is giving me horror, something's wrong in listingblock.js
Below is the error, I'll try googling if i can find what's the problem ..... and.....please help (>_<)

Timed out retrying after 4050ms: cy.click() failed because this element is detached from the DOM.

<button class="ui basic icon button listing">...</button>

Cypress requires elements be attached in the DOM to interact with them.

The previous command that ran was:

cy.contains()

This DOM element likely became detached somewhere between the previous and current command.

Common situations why this happens:

Your JS framework re-rendered asynchronously

Your app code reacted to an event firing and removed the element

You typically need to re-query for the element or add 'guards' which delay Cypress from running new commands.

stevepiercy · 2022-12-23T23:41:13Z

I think you can ignore the failing test as this PR involves documentation only, and nothing to do with core.

Nonetheless, how does one rerun a failed test in Cypress?

OMG you're actually doing this! Writing a user manual for Volto. You two are awesome!

It ain't gonna write itself. 😝

stevepiercy · 2022-12-23T23:42:36Z

nm, I got lost in Cypress. I found it in GHA. Rerunning it now.

stevepiercy · 2022-12-24T00:46:01Z

The failing test was a glitch, and we're all green. Merging! 🥳

* master: (78 commits) Update makefile with Vale and fix linkcheckbroken (#4181) Add todo regarding management of Plone's backend. Update versions. (#4198) Pin Sphinx<5,>=3 due to sphinx-book-theme 0.3.3 requirement. (#4199) Improve matching in keyboard slash menu (#4187) Add description for different types of blocks (#4166) Remove dangling news item Release 16.6.0 (#4186) Fix for externalRoutes short version not working anymore (#4182) Release generate-volto 6.2.2 Changelog for generator fix Update docker image used in Makefile for app (#4184) Update README with a new Volto site (#4170) Add HI-ERN website to volto in production section in README (#4172) Fix provide a method to disable the searching capabilities of SortOn … (#4163) More ignores Release @plone/scripts 2.2.2 Adjust npmignores, reissue package Release generate-volto 6.2.1 Update makefile for addons (#4175) Fix team name in PLIP.md ...

Co-authored-by: Katja Süss <[email protected]> Co-authored-by: Steve Piercy <[email protected]>

Co-authored-by: Mohammad Hussain <[email protected]> Co-authored-by: Katja Süss <[email protected]> Co-authored-by: Steve Piercy <[email protected]>

MAX-786 added 4 commits December 22, 2022 04:29

add description for block's types

c5a1dbd

correct spellings

5b2510c

add changelog

021298b

fix image of hero block

8c35ac2

MAX-786 requested a review from stevepiercy December 21, 2022 23:38

tiberiuichim approved these changes Dec 22, 2022

View reviewed changes

ksuess requested changes Dec 22, 2022

View reviewed changes

docs/source/user-manual/blocks.md Outdated Show resolved Hide resolved

docs/source/user-manual/blocks.md Outdated Show resolved Hide resolved

MAX-786 and others added 3 commits December 22, 2022 19:07

Update docs/source/user-manual/blocks.md

b195dfc

Co-authored-by: Katja Süss <[email protected]>

add description for search block

3fde49e

Update docs/source/user-manual/blocks.md

166face

Co-authored-by: Steve Piercy <[email protected]>

ksuess approved these changes Dec 22, 2022

View reviewed changes

Overhaul User Manual > Blocks

da9e2bd

stevepiercy approved these changes Dec 23, 2022

View reviewed changes

stevepiercy added this to the Plone 6.0 milestone Dec 23, 2022

Merge branch 'master' into user_manual_docs

d53cc7d

sneridagh requested changes Dec 23, 2022

View reviewed changes

MAX-786 requested a review from sneridagh December 23, 2022 14:17

MAX-786 and others added 2 commits December 23, 2022 21:53

remove the system block

7d8ce6e

Merge branch 'master' into user_manual_docs

f2a312e

stevepiercy merged commit bb35f53 into master Dec 24, 2022

stevepiercy deleted the user_manual_docs branch December 24, 2022 00:46

sneridagh pushed a commit that referenced this pull request Jan 4, 2023

Add description for different types of blocks (#4166)

22cc3a7

Co-authored-by: Katja Süss <[email protected]> Co-authored-by: Steve Piercy <[email protected]>

sneridagh added a commit that referenced this pull request Jan 4, 2023

Add description for different types of blocks (#4166) (#4215)

d36bd75

Co-authored-by: Mohammad Hussain <[email protected]> Co-authored-by: Katja Süss <[email protected]> Co-authored-by: Steve Piercy <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add description for different types of blocks #4166

Add description for different types of blocks #4166

MAX-786 commented Dec 21, 2022

netlify bot commented Dec 21, 2022 •

edited

Loading

cypress bot commented Dec 21, 2022 •

edited

Loading

ksuess left a comment

stevepiercy left a comment

sneridagh left a comment

MAX-786 commented Dec 23, 2022 •

edited

Loading

MAX-786 commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

MAX-786 commented Dec 23, 2022

tiberiuichim commented Dec 23, 2022

MAX-786 commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

stevepiercy commented Dec 24, 2022

Add description for different types of blocks #4166

Add description for different types of blocks #4166

Conversation

MAX-786 commented Dec 21, 2022

netlify bot commented Dec 21, 2022 • edited Loading

✅ Deploy Preview for volto ready!

cypress bot commented Dec 21, 2022 • edited Loading

Test summary

Run details

ksuess left a comment

Choose a reason for hiding this comment

stevepiercy left a comment

Choose a reason for hiding this comment

sneridagh left a comment

Choose a reason for hiding this comment

MAX-786 commented Dec 23, 2022 • edited Loading

MAX-786 commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

MAX-786 commented Dec 23, 2022

tiberiuichim commented Dec 23, 2022

MAX-786 commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

stevepiercy commented Dec 23, 2022

stevepiercy commented Dec 24, 2022

netlify bot commented Dec 21, 2022 •

edited

Loading

cypress bot commented Dec 21, 2022 •

edited

Loading

MAX-786 commented Dec 23, 2022 •

edited

Loading