Custom pages

Contents

So far, rendering has been based on hardcoded mappings made by the developer. In this chapter you will enable editors to compose their own pages.

Task: Disable the debug view

For every page you select, the debug view keeps appearing - even in Content Studio. Disable this by following the steps below.

  1. Comment out the CATCH_ALL debug view at the bottom of your mappings file, like this:

    src/components/_mappings.ts
    ...
    
    /*
    // Debug
    ComponentRegistry.addContentType(CATCH_ALL, {
        view: PropsView
    });
    */
  2. Verify that pages no longer render the JSON body by visiting your site on http://localhost:3000.

    The same now applies to Content Studio.

Task: Set up page rendering

Content types need to exist in Enonic before an editor can create content. Similarly, page components must be defined before Content Studio can enable editors to create pages.

  1. Check the page component descriptor - Verify that the Enonic app (not the Next.js front-end) has a page component descriptor at:

    src/main/resources/cms/pages/main/main.yaml
    kind: "Page"
    title: "Main"
    description: "Contains a single main region"
    form: [ ]
    regions:
      - "main"
    The definition of the region main allows Content Studio editors to add components to the page, as you will see later.
  2. Redeploy the Enonic app - This is only needed if you had to add the descriptor, and happens automatically if you started enonic dev.

  3. Configure page rendering in Next.js - Rendering a page is similar to rendering a content type. Go to the folder ./src/components, create a new folder here called pages, and inside it a new file called Main.tsx containing the following code.

    Make sure to use src/components/pages, not src/pages!
    src/components/pages/Main.tsx
    import type {PageProps} from '@enonic/nextjs-adapter';
    import React from 'react'
    import RegionsView from '@enonic/nextjs-adapter/views/Region';
    
    const MainPage = (props: PageProps) => {
        const page = props.page;
        const regions = (!page.regions || !Object.keys(page.regions).length) ? {
            main: {
                name: 'main',
                components: [],
            }
        } : page.regions;
        
        return (
            <>
                <RegionsView {...props} page={{...page, regions}} name="main"/>
            </>
        );
    };
    
    export default MainPage;
    The <RegionsView> element refers to the main region defined in the page component descriptor.
  4. Register the page - Add the following lines to _mappings.ts:

    src/components/_mappings.ts
    import MainPage from './pages/Main';
    
    // Page mappings
    ComponentRegistry.addPage(`${APP_NAME}:main`, {
        view: MainPage
    });

Both Enonic and Next.js are now able to handle custom pages.

Task: Create your first page

It’s time to build a custom page, by turning the site into one.

  1. Open the page view - From Content Studio, select and edit the /hmdb content item. From the edit view, open the Context Panel by clicking the Show Context Panel icon in the top right corner, and select Page in the widget dropdown at the top of the panel.

    You should now see the following:

    Selecting the page component in the page view
  2. Select the page component - In the Inspect tab of the panel, select the Main component you created earlier from the Template dropdown (it shows Automatic until then).

  3. Verify the result - The page now shows a single "dropzone": the region you specified earlier.

    Active page controller rendering an empty region visualized by a placeholder

Task: Add a paragraph part

To put something on the page, you need a component editors can drop into the region. Create a Paragraph part that holds rich text.

The next chapter takes a deeper dive into parts and components.
  1. Check the part descriptor - Verify that the Enonic app (not the Next.js front-end) has the paragraph part:

    src/main/resources/cms/parts/paragraph/paragraph.yaml
    kind: "Part"
    title: "Paragraph"
    description: "A rich text component"
    form:
      - name: "text"
        type: "HtmlArea"
        label: "Text"
        occurrences:
          min: 1
          max: 1
        allowHeadings: "h1 h2 h3"
    The HtmlArea form item gives editors a rich text editor with formatting, links, images and macros.
  2. Redeploy the Enonic app - This is only needed if you had to add the part, and happens automatically if you started enonic dev.

  3. Add the part implementation to the Next.js app:

    src/components/parts/Paragraph.tsx
    import React from 'react'
    import {PartProps} from '@enonic/nextjs-adapter';
    import RichTextView from '@enonic/nextjs-adapter/views/RichTextView';
    
    const Paragraph = (props: PartProps) => {
        return props.part.config.text ? (
            <RichTextView data={props.part.config.text} meta={props.meta}/>
        ) : null;
    };
    
    export default Paragraph;

    The RichTextView component (from the Enonic adapter) takes care of resolving links, sizing images and rendering macros.

  4. Register the part - Add the following lines to _mappings.ts:

    src/components/_mappings.ts
    import {richTextQuery} from '@enonic/nextjs-adapter';
    import Paragraph from './parts/Paragraph';
    
    // Part mappings
    ComponentRegistry.addPart(`${APP_NAME}:paragraph`, {
        view: Paragraph,
        configQuery: `{${richTextQuery('text')}}`
    });
    richTextQuery generates the query fragment needed for the adapter to resolve link, image and macro metadata within the rich text field of the part config form.
  5. Add the part to your page - Back in Content Studio, drag Part from the Insert tab on the right hand side into the region, then select Paragraph in the part dropdown of the Inspect tab. Use the rich text editor to write and format text, as well as insert images or macros, and click Apply.

    Next.js-rendered paragraph part with an image
  6. Verify the result - Click the Preview button in Content Studio to see a full-screen version of the page.

Task: Publish the page

Your new page is looking good. However, if you visit http://localhost:3000 in an incognito window or a different browser, you’ll get a "404 page not found" error. This is because preview mode is off in an incognito window, and only published changes are visible from the front-end.

Content Studio activates Next.js' preview mode, which in turn uses the drafts API. When accessing the front-end directly, Next.js fetches published content from the master branch.

  1. Publish the page - Click Mark as ready, and then Publish now in the Publishing Wizard.

    Publishing wizard
  2. Verify that your page is live - Visit http://localhost:3000 in an incognito window once again.

Summary

You’ve disabled the debug view, registered a Main page component with a region, added a Paragraph part, and published a page composed in Content Studio.

Next, you’ll add more configurable parts to play with.


Contents

Contents