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.
-
Comment out the
CATCH_ALLdebug view at the bottom of your mappings file, like this:src/components/_mappings.ts... /* // Debug ComponentRegistry.addContentType(CATCH_ALL, { view: PropsView }); */ -
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.
-
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.yamlkind: "Page" title: "Main" description: "Contains a single main region" form: [ ] regions: - "main"The definition of the region mainallows Content Studio editors to add components to the page, as you will see later. -
Redeploy the Enonic app - This is only needed if you had to add the descriptor, and happens automatically if you started
enonic dev. -
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 calledpages, and inside it a new file calledMain.tsxcontaining the following code.Make sure to use src/components/pages, notsrc/pages!src/components/pages/Main.tsximport 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 themainregion defined in the page component descriptor. -
Register the page - Add the following lines to
_mappings.ts:src/components/_mappings.tsimport 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.
-
Open the page view - From Content Studio, select and edit the
/hmdbcontent item. From the edit view, open the Context Panel by clicking theShow Context Panelicon in the top right corner, and selectPagein the widget dropdown at the top of the panel.You should now see the following:
-
Select the page component - In the
Inspecttab of the panel, select theMaincomponent you created earlier from theTemplatedropdown (it showsAutomaticuntil then). -
Verify the result - The page now shows a single "dropzone": the region you specified earlier.
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. |
-
Check the part descriptor - Verify that the Enonic app (not the Next.js front-end) has the
paragraphpart:src/main/resources/cms/parts/paragraph/paragraph.yamlkind: "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. -
Redeploy the Enonic app - This is only needed if you had to add the part, and happens automatically if you started
enonic dev. -
Add the part implementation to the Next.js app:
src/components/parts/Paragraph.tsximport 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
RichTextViewcomponent (from the Enonic adapter) takes care of resolving links, sizing images and rendering macros. -
Register the part - Add the following lines to
_mappings.ts:src/components/_mappings.tsimport {richTextQuery} from '@enonic/nextjs-adapter'; import Paragraph from './parts/Paragraph'; // Part mappings ComponentRegistry.addPart(`${APP_NAME}:paragraph`, { view: Paragraph, configQuery: `{${richTextQuery('text')}}` });richTextQuerygenerates the query fragment needed for the adapter to resolve link, image and macro metadata within the rich text field of the part config form. -
Add the part to your page - Back in Content Studio, drag
Partfrom theInserttab on the right hand side into the region, then selectParagraphin the part dropdown of theInspecttab. Use the rich text editor to write and format text, as well as insert images or macros, and clickApply.
-
Verify the result - Click the
Previewbutton 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.
-
Publish the page - Click
Mark as ready, and thenPublish nowin the Publishing Wizard.
-
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.