Block examples documentation

[erral]

• I signed and returned the Plone Contributor Agreement, and received and accepted an invitation to join a team in the Plone GitHub organization.
• I verified there aren't other open pull requests for the same change.
• I followed the guidelines in Contributing to Volto.
• I succesfully ran code linting checks on my changes locally.
• I succesfully ran unit tests on my changes locally.
• I succesfully ran acceptance tests on my changes locally.
• If needed, I added new tests for my changes.
• If needed, I added documentation for my changes, either in the Storybook or narrative documentation.
• I included a change log entry in my commits.

---

I have reviewed the block documentation, converted some code blocks from class components to functional components, and provide an example of a simple block.

---

📚 Documentation preview 📚: https://volto--6560.org.readthedocs.build/

[netlify]

✅ Deploy Preview for plone-components canceled.

Name	Link
🔨 Latest commit	058b4b0
🔍 Latest deploy log	https://app.netlify.com/sites/plone-components/deploys/677bbb4d721c750008c4626d

[ichim-david]

Thank you for writing this @erral . It's awesome when an experienced Volto developer takes some time to pass on some of this hard-earned experience and writes some documentation. You are awesome for doing this.

I plan on giving it a read sometime this week to see if there is anything that I can help with in potential suggestions. But again, thank you for doing this.

[stevepiercy]

This is great stuff. Thank you!

I created a related PR to define Glossary terms at plone/documentation#1829, which needs to be merged before this PR to pull them into this PR's docs preview.

[ichim-david]

@erral once you apply @stevepiercy suggestions and you feel that the work is ready for review you can add me as a reviewer if you would like, I volunteer to read the docs and give any potential suggestions if needed.

[stevepiercy]

Just a bunch of nitpicky stuff, except for changing webmaster or developer to editor. I'll merge these. Over to @ichim-david!

[stevepiercy]

Glossary terms link now.

https://volto--6560.org.readthedocs.build/blocks/examples/custom-view-and-variations.html#view-component

According to the React docs, HOC is no longer used in modern React, so should we use them anymore?

[ichim-david]

@erral thank you again for taking the time to write these examples.

I think we are missing an example where you also define a custom edit view since we have created the view component, the schema and the schema enhancer.

What we haven't shown yet to the user is how they can also create a custom edit component.
It can also come in another pull request or added by Steve or anyone else I'm not saying it's mandatory for that example to also be created in this pull request but I think it would have been useful to have that example as well.

Again thank you for your work.

[ichim-david]

@erral this is the first document that you have created why do we have example block 02? it makes more sense for me to start with ExampleBlock01 or simply have block1

[erral]

wrll, this comes from examples I have written for my team. There are 6 examples, but I have brought here only 3, the most relevant ones. I have copy-pasted the code, so that's why we have 2, 5 and 6.

I haven't copied the following ones:

• Block just with schema (automatic view and edit)
• Custom edit component (I will add this following your suggestion)
• Block with 'manual' variations: adding the variation field manually in the schema

[ichim-david]

@erral I would flip this info to be added before the info from here
https://github.com/plone/volto/pull/6560/files#diff-0cac75d5c1904800eea8a8aabac27f32423c1cdffa5d10c0b1bb56456a83aa9aR137

[ichim-david]

@erral I don't think this info should be here. It has nothing to do with the example given here. I would show the contents of the index file that is created whenever you create a new add-on.
From there, I would show that we can add our configuration for the block.

[erral]

I will rewrite this, saying to add the block configuration form before the return config, that will be easier to understand.

[erral]

Thanks @ichim-david and @stevepiercy for your comments.

I have made some modifications in the docs:

• I have included the example with a custom edit component
• I have renamed the examples 1,2,3,4 instead of the previous 2, 5 and 6 😅
• I have changed the block configuration settings part. I have reworded where the configuration should be included to be clearer for the reader.

[stevepiercy]

More nitpicky stuff. I'll merge these.

[stevepiercy]

I'm waiting for the RTD PR preview to complete building before committing these suggestions.

[stevepiercy]

This looks great. Thank you @erral for sharing your work, and @ichim-david for the suggesstions for improvement. ✋

@ichim-david one more review from you, and if you approve, please go ahead and merge.

[ichim-david]

@erral and @stevepiercy. I built locally and the code examples look good now without any extra
overflow scrollbars and the build is passing.
Again thank you erral for this work.

[davisagli]

@erral @ichim-david @stevepiercy Nice work!