Skip to main content

Creating a new section and linking it with Contentful

This guide will walk you through the process of creating a new section and linking it with Contentful.

Before you start​

  • Checkout the component development guidelines.
  • Ensure a section doesn't already exist which is similar to your new section. Speak to the project lead developer before creating a new section if you are unsure.

Creating a new section​

1. Run the section code generation script​

From the pwa repo root directory run the command:

pnpm codegen:section --filter=@overdose/carrots-frontend

You will be asked to give your section a name. Enter a section name, eg. RichText

Console output of section generation tool asking for a section name

This will generate all necessary files to add a new section to the graphql schema. It will also create a new section graphql resolver and a section component.

The full list of files added or changed is output in your console:

Section tool output

2. That’s it!​

Your section is now ready for use on the front end! Your new section has been added to the graphql schema, a resolver has been created, and TypeScript types have been created for your section component props.

You will probably want to customise your section too - if so, read on 👇

Customising a section & connecting to Contentful​

1. Add required fields to section graphql schema​

Open the generated section graphql scheme file. (eg apps/carrots-frontend/src/graphql/schema/sections/RichText.ts). By default your section will contain the fields id and title - both fields are required. Add any additional fields you require here.

RichText.ts

2. Add new fields to PageByUrl query​

To make your new fields available on the frontend you need to add them to the PageByUrl query. See Anatomy of a page load for more information about this query.

apps/carrots-frontend/src/graphql/queries/pageByUrl.ts

pageByUrl.ts

3. Run the Typescript codegen command​

From the pwa repo root directory run the command:

pnpm codegen:graphql --filter=@overdose/carrots-frontend

This will generate TypeScript types based on the provided graphql schema. A new section props type is automatically passed to your new section component.

pageByUrl.ts

4. Modify the section resolver to modify or format data server-side​

Apply server-side modifications our your section by modifying the new section resolver. This is also where you can call additional APIs. See: Retrieving data from a datasource in a section

RichText.ts

5. Create your new section in Contentful​

Login to the carrots-frontend Contentful app. Find an existing section which most resembles your desired section and duplicate it.

Section: SEO Block

Create a new section using the existing name convention:

  • Name: Section: [Section Name] (eg Section: Rich Text) - this field should be in a human-readable format (not camelCase)
  • Api Identifier: Section[SectionName] (eg. SectionRichText)
  • Description: Give the section a short, useful description

Duplicate content type

Delete any fields you don’t need and add any new fields to your section as desired. Ensure Titles are human-readable, and field names are camelCase. Do not delete the Admin title or Title fields.

Press "Add field". Enter a Name and Field ID, then "Create and configure".

New Rich Text Field

Select “Enable localization of this field” for all fields.

Once you have finished adding fields to your new section head to the Page Template content type. Edit the Sections field and under “Validation” toggle on your new section.

Page template

Page Template sections

Your section is now ready to be added to any existing or new Template.

6. Hook up the Contentful data source to your new section​

Add your new Contentful section to the Contentful data source query. Ensure the type exactly matches the Field ID you set up in the previous step.

apps/carrots-frontend/src/server/data-sources/contentful/fragments.ts

fragments.ts

7. Map the Contentful section typename to your carrots-frontend section typename​

Map the Field ID of the section you made in Contentful to the name of your new section in the project.

apps/carrots-frontend/src/server/data-sources/contentful/utils/getSectionType.ts

getSectionType.ts

Further reading​