FE: Document the process to expose Q&A on new content type, once added in CMS

[jilladams]

Description

User Story

AS A PW engineer I WANT to document the steps for adding reusable Q&As to FE templates SO THAT we can repeat the process efficiently and reliably for multiple content types / pages.

Eng notes

We've done this before for Resources & Support Detail pages, we can use that as a reference. Epic: https://github.com/department-of-veterans-affairs/va.gov-cms/issues/8630

Acceptance Criteria

• [x] A runbook (document of steps) has been written and added to Github docs in Team repo
  • [x] @wesrowe / @jilladams to clarify with @davidconlon where/how we want Q&A / COPE content to be documented as a Product in the directory. AKA where should https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/tier-2-content-IA-and-design/cope-cms-faq-library/product-outline.md be moved to?
• [x] An example to follow: Facilities runbook example. Also check out the BE runbook for this same effort.
• [x] Include any generic instructions for leveraging GQL query provided by BE eng
• [x] The runbook addresses FE steps only. BE steps were covered via #10936.

[jilladams]

FE spike / docs/ templating note from talking to @jtmst today, and from BE refinement (@dsasser and @chri5tia ):

• in CMS, this will need to be added per content type. Cannot be done once and for all across content types. More notes now on #10936, the Drupal ticket to document the process to add Q&As to a content type.
• Each content type will generate its own GraphQL in order to harness the fields in FE templates. This likely means we cannot easily template once and for all in the front end, due to the nature of the data coming out of Drupal.
• For FE: Josh mentioned it might be possible to work within the template structure to make it possible to show QA at the most rudimentary template level (page?). But: that will depend on the nature of the GraphQL and how specific the field data is per content type.

FYI @wesrowe .

[jilladams]

Since this won't be a repetitive task forever, just until we get through all content types, can be a Github doc rather than an issue template.

We know that DaveC wants products to live at /products long-term, so we know that this doc: https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/tier-2-content-IA-and-design/cope-cms-faq-library/product-outline.md needs to move. Let's figure out with him where it should go, move it, and add this runbook in that new location. (@wesrowe ). Added that to ACs.

[randimays]

Since this won't be a repetitive task forever, just until we get through all content types, can be a Github doc rather than an issue template.

We know that DaveC wants products to live at /products long-term, so we know that this doc: https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/tier-2-content-IA-and-design/cope-cms-faq-library/product-outline.md needs to move. Let's figure out with him where it should go, move it, and add this runbook in that new location. (@wesrowe ). Added that to ACs.

@jilladams @wesrowe did we get any clarification for this?

[jilladams]

not a final answer, but a next step: https://dsva.slack.com/archives/C52CL1PKQ/p1686831918450099?thread_ts=1686787816.585489&cid=C52CL1PKQ

This problem isn't just for Q&A's but for the whole public websites product portfolio. Jen Lee organized it by team, which it should never have been. Fundamentally, I think I want to consolidate all of this into "Resources and Support/Learning Center" but even that, as a name, doesn't work - I'd like to talk this through with the content team about what we should actually call it. the concept of "tier 2" was a Jen Lee thing that confused things. There's really no such thing as a "CMS product" other than the CMS itself. There are, however, products that currently use Drupal for content.

So: waiting on DaveC for final destination.

[randimays]

Not sure where to put this yet, so sticking the documentation here for now. A couple of caveats:

• I went over the code implementation with @jtmst. We're not sure whether q_a_group.drupal.liquid and qaGroup.paragraph.graphql.js are completely reusable for the next implementation. In theory, when the same Q&A field is added on a new content type, the query and data structure should remain the same. But it'll be difficult for us to know until we implement this solution on a new content type.
• @jtmst mentioned that there might be a DRYer way to implement this rather than adding all of the logic in this pull request (same as above) to the individual content type (as seen in support_resources_detail_page.drupal.liquid. We may refactor later and update this documentation at that point.

Exposing Q&A on New Content Types

Pre-Existing Setup

1. src/site/paragraphs/q_a_group.drupal.liquid This template consumes the Drupal entity data for a single Q&A on the content type and uses the src/site/paragraphs/rich_text_char_limit_1000.drupal.liquid template to display the contents of the Q&A answer.

2. src/site/stages/build/drupal/graphql/paragraph-fragments/qaGroup.paragraph.graphql.js: This GraphQL query has been modified to consume the new data structure for a Q&A answer coming from Drupal. We received the query snippet (contained within fieldAnswer, ending before targetId, lines 16-24) from a Drupal developer to facilitate connecting the data from Drupal.

Implementing a New Content Type

The two files referenced under Pre-Existing Setup are used to fetch the Drupal data for Q&As of the type q_a_group and render the Q&A answers. The steps below demonstrate how to optionally render a fieldSectionHeader if it exists, then loop through the Q&As, display the question, then create the template name for displaying the Q&A answer.

For reference, see src/site/layouts/support_resources_detail_page.drupal.liquid. You will need to add the steps below into the appropriate template for your content type / page.

Under the <!-- QAs --> comment, there is logic that loops through the content blocks coming from Drupal.

1. Determine if the entityBundle on that content block is q_a_group.

{% if contentBlock.entity.entityBundle === "q_a_group"  %}

2. If so, assign a variable to represent the Q&A entities:

{% assign fieldQAs = contentBlock.entity.queryFieldQAs.entities %}

3. Conditionally render the fieldSectionHeader as an <h2> if it exists.

<!-- Optional section header -->
    {% if contentBlock.entity.fieldSectionHeader %}
        <h2>{{ contentBlock.entity.fieldSectionHeader }}</h2>
    {% endif %}

4. a. If the fieldSectionHeader does exist, render the Q&A question as an <h3> b. If the fieldSectionHeader does not exist, render the Q&A question as an <h2>.

   {% assign fieldSectionHeaderTag = 'h2' %}
   {% if contentBlock.entity.fieldSectionHeader %}
   {% assign fieldSectionHeaderTag = 'h3' %}
   {% endif %}

5. Loop through the Q&As a. Use the fieldAnswer.entity.entityBundle to create the name for the template that will be used to render Q&A answers. i.e. src/site/paragraphs/q_a_group.drupal.liquid. b. Add in the template via include, passing in the fieldAnswer.entity.

{% for fieldQA in fieldQAs %}
    <{{ fieldSectionHeaderTag }}>{{ fieldQA.entityLabel }}</{{ fieldSectionHeaderTag }}>
    {% if fieldQA.fieldAnswer %}
        {% assign fieldAnswer = fieldQA.fieldAnswer %}
        {% assign bundleComponent = "src/site/paragraphs/" | append: fieldAnswer.entity.entityBundle %}
        {% assign bundleComponentWithExtension = bundleComponent | append: ".drupal.liquid" %}
         {% include {{ bundleComponentWithExtension }} with entity = fieldAnswer.entity %}
    {% endif %}
    </ul>
{% endfor %}

[jilladams]

Dave decision for now out of Product Sync:

• @davidconlon to talk to the Content team re: proposal to move the COPE QA github doc to a new path:/product/content/faq-library as proposed new home for the top level document. (FYI @bethpottsVADEPO & @DanielleThierryUSDSVA )
  • Underlying question: is COPE Q&A content actually a child / feature of "Resources & Support" (formerly Learning Library, potentially to be rebranded again near term)
• This documentation itself should live underneath the parent doc at an /engineering path. If / when the parent doc moves, we'll need to move engineering docs as well.

SO: @randimays for the purposes of this ticket today, let's let it ride through this sprint to see if we get an answer re: those questions. And if we don't get that resolved by this time next week, go ahead and create a new README at https://github.com/department-of-veterans-affairs/va.gov-team/blob/master/products/content/tier-2-content-IA-and-design/cope-cms-faq-library/engineering/readme.md, and we'll move that when we move the product brief.

[randimays]

@jilladams Thank you! I'll standby.

[wesrowe]

@randimays, Dave confirmed in mid-sprint checkin: post the docs in the current location and we'll move it later when the right place emerges.

[randimays]

Final docs live here: https://github.com/department-of-veterans-affairs/va.gov-team/tree/master/products/content/tier-2-content-IA-and-design/cope-cms-faq-library/engineering As I understand, @chri5tia will be contributing to these when the BE portion is done.