Add Related Items slot (#64)

docs/how-to-guides/customize-related-items.md

@@ -0,0 +1,50 @@
+---
+myst:
+  html_meta:
+    "description": "How to hide or replace the related items list shown below content in Plone Aurora"
+    "property=og:description": "How to hide or replace the related items list shown below content in Plone Aurora"
+    "property=og:title": "Customize the related items"
+    "keywords": "Plone Aurora, related items, slot, belowContent"
+---
+
+# Customize the related items
+
+Plone Aurora renders a content item's related items below the content as links.
+The list comes from a slot component registered for the `belowContent` slot.
+This guide shows you how to hide or replace it.
+
+## Hide the related items
+
+Set `showRelatedItems` to `false` in your add-on configuration to hide the list on every page.
+
+```ts
+import type { ConfigType } from '@plone/registry';
+
+export default function install(config: ConfigType) {
+  config.settings.showRelatedItems = false;
+  return config;
+}
+```
+
+The slot renders the list whenever an item has `relatedItems`, unless `showRelatedItems` is `false`.
+
+## Replace the related items component
+
+Register your own component for the `belowContent` slot under the same name to override the default.
+
+```ts
+import type { ConfigType } from '@plone/registry';
+import MyRelatedItems from './MyRelatedItems';
+
+export default function install(config: ConfigType) {
+  config.registerSlotComponent({
+    name: 'RelatedItems',
+    slot: 'belowContent',
+    component: MyRelatedItems,
+  });
+  return config;
+}
+```
+
+Your component receives the slot props, including `content`, from which you can read `content.relatedItems`.
+To learn how slots work in general, refer to {doc}`register-slots`.

docs/how-to-guides/index.md

@@ -30,4 +30,5 @@ icons
 configure-plate-code-block-languages
 bind-metadata-fields-to-plate-text-blocks
 custom-content-types
+customize-related-items
 ```

packages/layout/config/slots.ts

@@ -9,6 +9,7 @@ import HeaderTools from '../slots/Tools';
 import ContentArea from '../slots/ContentArea';
 import MainFooter from '../slots/MainFooter/MainFooter';
 import Breadcrumbs from '../slots/Breadcrumbs';
+import RelatedItems from '../slots/RelatedItems/RelatedItems';
 import { NotContentTypeCondition } from '../helpers';
 
 export default function install(config: ConfigType) {
@@ -83,5 +84,12 @@ export default function install(config: ConfigType) {
     component: MainFooter,
   });
 
+  // Related Items
+  config.registerSlotComponent({
+    name: 'RelatedItems',
+    slot: 'belowContent',
+    component: RelatedItems,
+  });
+
   return config;
 }

packages/layout/locales/de/common.json

@@ -17,6 +17,9 @@
     "toolbar": {
       "label": "Werkzeugleiste"
     },
+    "relatedItems": {
+      "label": "Verwandte Inhalte"
+    },
     "views": {
       "link": {
         "linkLabel": "Die Linkadresse lautet:",

packages/layout/locales/en/common.json

@@ -17,6 +17,9 @@
     "toolbar": {
       "label": "Toolbar"
     },
+    "relatedItems": {
+      "label": "Related items"
+    },
     "views": {
       "link": {
         "linkLabel": "The link address is:",

packages/layout/locales/it/common.json

@@ -17,6 +17,9 @@
     "toolbar": {
       "label": "Barra degli strumenti"
     },
+    "relatedItems": {
+      "label": "Contenuti correlati"
+    },
     "views": {
       "link": {
         "linkLabel": "L'indirizzo del link è:",

packages/layout/news/64.feature

@@ -0,0 +1 @@
+Added a Related Items slot that renders a content item's related items as links below the content. @Cabonie

packages/layout/slots/RelatedItems/RelatedItems.module.css

@@ -0,0 +1,15 @@
+@layer custom {
+  .relatedItems {
+    padding: 0;
+    margin-top: 1.5rem;
+    list-style: none;
+  }
+
+  .relatedItems li {
+    margin-bottom: 0.5rem;
+  }
+
+  .relatedItems li:last-child {
+    margin-bottom: 0;
+  }
+}

packages/layout/slots/RelatedItems/RelatedItems.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import { RouterProvider } from 'react-aria-components';
+import RelatedItems from './RelatedItems';
+
+type Item = { '@id': string; title: string };
+
+const renderRelatedItems = (relatedItems: Item[]) =>
+  render(
+    <MemoryRouter>
+      <RouterProvider navigate={() => undefined}>
+        <RelatedItems
+          content={{ relatedItems } as never}
+          location={{ pathname: '/' } as never}
+        />
+      </RouterProvider>
+    </MemoryRouter>,
+  );
+
+describe('RelatedItems slot', () => {
+  it('renders nothing when there are no related items', () => {
+    const { container } = renderRelatedItems([]);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('renders a link for each related item', () => {
+    renderRelatedItems([
+      { '@id': '/news/one', title: 'News One' },
+      { '@id': '/events/two', title: 'Event Two' },
+    ]);
+    expect(screen.getByRole('link', { name: 'News One' })).toHaveAttribute(
+      'href',
+      '/news/one',
+    );
+    expect(screen.getByRole('link', { name: 'Event Two' })).toHaveAttribute(
+      'href',
+      '/events/two',
+    );
+  });
+});

packages/layout/slots/RelatedItems/RelatedItems.tsx

@@ -0,0 +1,34 @@
+import { useTranslation } from 'react-i18next';
+import { Link } from '@plone/components';
+import config from '@plone/registry';
+import type { SlotComponentProps } from '../SlotRenderer';
+import SectionWrapper from '../../components/SectionWrapper/SectionWrapper';
+import styles from './RelatedItems.module.css';
+
+const RelatedItems = (props: SlotComponentProps) => {
+  const { t } = useTranslation();
+  const items = props.content.relatedItems ?? [];
+
+  const showRelatedItems = config.settings.showRelatedItems !== false;
+  if (!showRelatedItems || items.length === 0) {
+    return null;
+  }
+
+  return (
+    <SectionWrapper
+      as="nav"
+      width="layout"
+      aria-label={t('layout.relatedItems.label')}
+    >
+      <ul className={styles.relatedItems}>
+        {items.map((item) => (
+          <li key={item['@id']}>
+            <Link href={item['@id']}>{item.title}</Link>
+          </li>
+        ))}
+      </ul>
+    </SectionWrapper>
+  );
+};
+
+export default RelatedItems;