Create guidance for building flexible blocks #4330
Conversation
leenagupte
force-pushed
the
documenting-blocks
branch
from
1518d44
to
c776cf6
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
c776cf6
to
2d467e5
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
2d467e5
to
0a82d5d
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
0a82d5d
to
15410e9
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
15410e9
to
8625c99
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
8625c99
to
a1f2735
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
caa08dc
to
ad5f8df
Compare
leenagupte
force-pushed
the
documenting-blocks
branch
from
ad5f8df
to
60c5f5e
Compare
Documents what each of the blocks is, when they should be used and how they are configured. Co-authored-by: Keith Lawrence <[email protected]>
leenagupte
force-pushed
the
documenting-blocks
branch
from
60c5f5e
to
a136674
Compare
leenagupte
changed the title
|
|
||
| Blocks are rendered in the order that they appear in the content item. | ||
|
|
||
| Blocks are added to the content item in the details hash. The landing page editor is currently a work in progress. At time of writing, the config for blocks need to be added in YAML format in Whitehall. This YAML config is then merged into `details` hash when the landing page is saved and published. |
There was a problem hiding this comment.
grammar nitpick: either "the details hash" or just "details" without "hash"
|
|
||
| ## Types of Block | ||
|
|
||
| Each block rendered using its own partial template. The full list of available types of block available can be found by looking at the contents of: `app/views/landing_page/blocks` |
There was a problem hiding this comment.
Grammar nitpick:
Each block is rendered
OR
Each block renders
|
|
||
| ### Simple blocks | ||
|
|
||
| Simple blocks general render one component or "thing". They can either be rendered directly or as the children of compound blocks. |
There was a problem hiding this comment.
Nitpick:
generally, not general
| #### Govspeak | ||
|
|
||
| A wrapper around the [Govspeak content component](https://components.publishing.service.gov.uk/component-guide/govspeak). Note that the content item data for the component is not Govspeak, but HTML that has been converted from Govspeak. If you're editing the block data in Whitehall, though, you can use Govspeak directly by taking advantage of the publishing-api automatic conversion (see second example) | ||
|
|
There was a problem hiding this comment.
This reads as a bit confusing. This makes it sound like I need to go and find a tool to produce some HTML by converting it whereas in fact I can just supply any supported HTML. I don't think there's any need to mention publishing-api, just that there are two options for input: Any HTML which only uses the govspeak approved subset of tags, or govspeak. Then call out the syntax difference needed for each option as illustrated.
|
|
||
| #### Heading | ||
|
|
||
| A wrapper around the [Heading component](https://components.publishing.service.gov.uk/component-guide/heading). Note, though, that the block uses `content` where the component uses `text` for the title text key. This is so that headings can be indexed (only values inside a `content` key will be indexed when being published from Whitehall - see [Indexing block content in search](#indexing-block-content-in-search)) |
There was a problem hiding this comment.
This contextless reference to indexing threw me. The link to indexing helped, but I could have made more sense of this if you specified search here - I was thinking we were numbering headings for some reason as per an array index. Suggestion:
"This is so that headings can appear in search (only values..." etc
| #### Blocks container | ||
|
|
||
| A blocks container is used as an empty unstyled parent container to | ||
| hold other elements. It is used when we don't want to want to create |
There was a problem hiding this comment.
Why/when would we not want to create a row/grid layout?
There was a problem hiding this comment.
I pilfered that explanation from the commit message. Does that explanation make sense? If so I can replicate it wholesale.
| ``` | ||
|
|
||
| The left column is always populated if only one column is defined. | ||
| A blocks container applied to a column so that everying in the column can be styled relative to one and other. |
There was a problem hiding this comment.
I think this sentence is missing some words, I don't quite follow. Also typo in "everying".
|
|
||
| ## Indexing block content in search | ||
|
|
||
| Only content in blocks that has a label of `content` will be indexed in site search. |
There was a problem hiding this comment.
grammar: "have a label" not has
|
|
||
| ## Extending a page (Whitehall Only) | ||
|
|
||
| When editing a page in Whitehall, you may wish to use data from another page. Adding the top-level key `extends`, and the path of another landing page, will cause the data from the current block to be merged over the data from the extended block before publishing. This is a shallow merge (ie only top-level values are checked), and is currently used so that navigation groups can be specified in one page and used by sub-pages. |
There was a problem hiding this comment.
Suggestion: For clarity change "you may wish to use data from another page" to "you may wish to use data from another flexible content page" as there are many things on GOV.UK called pages.
|
|
||
| ...the navigation_groups element will be copied into the child page when it is saved (allowing you to specify a shared menu in one page and simply republish all the child pages with a standard Whitehall rake task). | ||
|
|
||
| If the child page didn't specify any blocks, those too would be merged over from the parent. That's because `extends` does a shallow merge of everything in the `details` element of the parent. This means that it is possible to add more top-level elements that can be shared across child pages. |
There was a problem hiding this comment.
I'm a bit confused by this bit about copying blocks over and why they are copied if empty and not copied otherwise.
I also don't really understand what I'll see in Whitehall - if I create a child page as above and save it, when I load it again will I see what I originally wrote or will it have expanded out all the links? If a navigation item changes do I need to hand edit every child or run a rake task to do so?`
Links out to running relevant rake tasks would be helpful if that's necessary - details on how to specify the right content items for the rake task etc
What
Documents what each of the blocks is, when they should be used and how they are configured.
Why
Trello card
Rendered version