[WHIT-2788] Configurable document form objects

[ChrisBAshton]

What

This PR refactors the schema design for config-driven document types by separating concerns that were previously conflated under edit_screens. We now:

• removed settings.edit_screens, in favour of a new top-level forms hash. It describes things at the UI level: which fields appear on which forms.
• adds new top-level presenters field, describing which field values get sent to Publishing API (and how to map them)
• removes schema.properties in favour of schema.attributes: effectively a slimmed down version of the former.
• schema.validations remains unchanged, but we no longer have 'nested' validation (e.g. schema.properties.duration.validations) - the 'nested' validation has moved up into the schema.validations (in this example, schema.validations.duration). This isn't represented in the overview below as we only had one example and it's more of a side-effect than a deliberate change.

Overview of schema changes:

"schema": {
-  "properties": {
-    "body": {
-      "title": "Body",
-      "type": "string",
-      "format": "govspeak"
-    }
+  "attributes": {
+    "body": {
+      "type": "string",
+    }
+  }
}
+ "forms": {
+  "documents": {
+    "fields": {
+      "body": {
+        "title": "Body",
+        "description": "The main content of the page",
+        "block": "govspeak"
+      }
+    }
+  }
+ },
+ "presenters": {
+   "publishing_api": {
+    "body": "govspeak"
+  }
+}
"settings": {
-  "edit_screens": {
-   "document": ["body"]
- }

Why

Bunching up properties into 'edit screens' was a good first step in #10786, allowing us to update different block content fields in isolation on separate tabs. But it was too restrictive: we had no way of denoting which fields should be 'grouped' (e.g. start & end date fields for an overall 'duration') and also we were having to wrestle with wanting to present the fields in one way but present them differently when presenting to Publishing API. The previous properties and edit_screens concepts were conflating too much.

The refactoring of the schemas we've done here should make it quicker and easier to iterate document types in future.

Manual Testing

We have checked on integration to be sure nothing is broken so far, in terms of usability and integrity of the block content data. Details of how we carried out the test can be found in here.

Jira: https://gov-uk.atlassian.net/browse/WHIT-2788

---

⚠️ This repo is Continuously Deployed: make sure you follow the guidance ⚠️

This application is owned by the Whitehall Experience team. Please let us know in #govuk-whitehall-experience-tech when you raise any PRs.

Follow these steps if you are doing a Rails upgrade.

[ChrisBAshton]

I was thinking about this yesterday - even though we only have flattened top level properties now, we need to make sure that the values are retained, even if the values are nested structures. So make sure we have a test for something like

"foo" => { "bar" => { "baz" => 123 } }

[eYinka]

I believe this has been sorted in:

whitehall/test/unit/app/models/standard_edition_block_content_merge_test.rb

Lines 172 to 176 in f4b7d53

	assert_equal({
	"info" => "updated info",
	"details" => "updated details",
	"bool" => false,
	}, bc["meta"].to_h)

[ChrisBAshton]

LGTM but can we remove or update the comment above the test?

[eYinka]

That's done. Thanks!

[lauraghiorghisor-tw]

I do wonder about this, sorry - the types we can now store in our blocks are https://github.com/alphagov/whitehall/pull/10972/changes#diff-ae39aa868855f099aa58be0acefa4cd2ab924fb72aafba6e9201d87a9b6dd9c9 - so they can never be an object. Do I misunderstand?

Your merge test doesn't have a problem with that structure but I think it's misleading to have it here as it's no longer relevant.

[lauraghiorghisor-tw]

If we must still support arrays and the like, then I think we need to re-introduce the object type and revisit that deleted code from block_content and add relevant tests there rather than in the merge test.

[ChrisBAshton]

I think @GDSNewt and I can reintroduce that code if necessary (while working on social media links for topical events)? Given the nesting isn't needed for our currently supported formats and we've already tested this simplified schema on Integration.

We're going to have to solve how to do 'arrays' in config-driven world anyway, and will tackle questions around validating the structure of each array element as part of that work.

[lauraghiorghisor-tw]

I am in agreement. SHIP IT (well, after I've had a look at the last commit).

[lauraghiorghisor-tw]

I've had a look, final LGTM ⛴️

[lauraghiorghisor-tw]

Had a read-through, LGTM and seems all that's needed was carried over nicely 😎 I did check tests in detail 👍

[lauraghiorghisor-tw]

I just approved but realised one little omission: the publishing_api_payload methods of all the content blocks can now be removed. Can that please be committed? Can be a separate commit.

[eYinka]

I just approved but realised one little omission: the publishing_api_payload methods of all the content blocks can now be removed. Can that please be committed? Can be a separate commit.

Good spot @lauraghiorghisor-tw. I've just added d5e7f9a to clean that up.