glamrock-agenda
Version:
Glamrock agenda
230 lines (182 loc) • 11.6 kB
Markdown
# The Eagerly agenda, built for Glamrock
## For local testing
cd your-lib-folder/
```
npm link
```
cd your-app/
```
npm link name-of-your-lib
```
### Want to also minify bundle output?
You can install rollup-plugin-terser (still works with rollup v3, but since it has no updates, we need to install it with legacy peer options)
```
npm i rollup-plugin-terser --save-dev --legacy-peer-deps
```
The `Agenda` component allows for flexible rendering of the following components:
- `Tile`
- `Image`
- `Link`
- `NotFound`
- `LoadMoreButton`
This is useful when you want to overwrite a default component with different markup or styling.
## Props
The Agenda component accepts the following props:
| **Prop Name** | **Type** | **Required** | **Description** |
| ------------------------ | ------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`data`** | `Array` | Yes | An array of events and promo texts to render in the agenda. Each item should follow the structure expected by the agenda. |
| **`helperText`** | `ReactNode` or `string` | No | Optional text strings to overwrite default strings that can be found in strings.ts. |
| **`searchParams`** | `Record<string, unknown>` | No | An object containing key-value pairs for filtering, pagination, and other query parameters. Useful for server-side filtering or client-side control. |
| **`handleParamsChange`** | `(params: Record<string, unknown>) => void` | No | A callback function triggered when the `searchParams` are updated by user actions or internal state changes. |
| **`filters`** | `Array` or `Record<string, unknown>` | No | Configures the filter options available for users to refine the displayed data. |
| **`options`** | `Object` | No | A collection of configuration options for customizing agenda behavior. See [Options Table](#options-table) for details. |
| **`components`** | `Object` | No | Custom React components to override default UI elements. See [Components Table](#components-table) for details. |
### Example helperText
```js
...
helperText={{
loadMore: 'Show me more please!',
}}
...
```
### Options
| **Prop** | **Type** | **Default** | **Description** |
| ----------------------- | ---------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------- |
| `locale` | `string` | `'nl-NL'` | Sets the locale for date formatting. |
| `postsPerPage` | `number` | `5` | Number of posts to display per page. |
| `showViewSwitcher` | `boolean` | `false` | Enables the view switcher functionality. |
| `showTotal` | `boolean` | `true` | Optionally show a total count above results |
| `useOverlay` | `boolean` | `true` | Whether to show the filters in an overlay or not |
| `promoFrequency` | `number` | `4` | Frequency at which promo strips are shown. |
| `promoStrips` | `ReactNode[]` | `[]` | Array of custom promo strips to display. |
| `date.formatSingle` | `string` | `'EEE d MMM yyyy'` | Date format for single dates. |
| `date.formatRange` | `{start: string, end: string}` | `{start: 'EEE d MMM yyyy', end: 'EEE d MMM yyyy'}` | Date format for range of dates. |
| `date.dateRangeDivider` | `string` | `'->'` | Divider used in date ranges. |
| `date.useMostRecent` | `boolean` | `false` | Uses the most recent date if multiple are available. |
| `groupEventsByMonth` | `boolean` | `true` | Groups events by month in the agenda view. |
| `loadMore` | `function` | `undefined` | Callback function triggered when loading more events. |
| `icons` | `{ prevPage: ReactNode, nextPage: ReactNode }` | `{}` | Object containing custom icon components for navigation buttons. |
| `filters` | `any[]` | `[]` | Array of filter options for the agenda. |
| `searchParams` | `object` | `{}` | Search parameters for filtering agenda items. |
| `handleParamsChange` | `function` | `undefined` | Callback function triggered when search parameters change. |
### Example custom options
```js
const promoStrips = [
<div key={1} style={{ background: 'green' }}>
Promo 1
</div>,
<div key={2} style={{ background: 'blue' }}>
Promo 2
</div>
];
```
### Components
| **Prop** | **Type** | **Default** | **Description** |
| --------------------------- | ---------------------------------------------- | ----------- | ---------------------------------------------------------------- |
| `components.Image` | `React.Component` | Next Image | Custom image component for rendering images. |
| `components.Link` | `React.Component` | Next Link | Custom link component for handling navigation. |
| `components.Tile` | `function` | `undefined` | Custom tile renderer for agenda items. |
| `components.NotFound` | `ReactNode` | `undefined` | Custom component to display when no items are found. |
| `components.LoadMoreButton` | `ReactNode` | `undefined` | Custom button for loading more items. |
| `icons` | `{ prevPage: ReactNode, nextPage: ReactNode }` | `{}` | Object containing custom icon components for navigation buttons. |
| `filters` | `any[]` | `[]` | Array of filter options for the agenda. |
| `searchParams` | `object` | `{}` | Search parameters for filtering agenda items. |
| `handleParamsChange` | `function` | `undefined` | Callback function triggered when search parameters change. |
### Example custom components
The following components do not have a custom value in settings.js file of your Glamrock project. Here's how you can overwrite them:
```js
Tile: ({ item }) => (
<div key={item.title} className="custom-tile">
<h3>{item.title}</h3>
</div>
);
```
```js
NotFound: <div>No items found</div>,
```
```js
icons: {
prevPage: <Icon icon="ARROW_RIGHT" fill="secondary" width="15px" height="15px" />,
nextPage: <Icon icon="ARROW_RIGHT" fill="secondary" width="15px" height="15px" />
}
```
```js
LoadMoreButton: <button>Load more</button>;
```
## Full example
Here’s an example demonstrating how to implement a custom tile and custom promo strips.
To use a custom tile rendering function, follow these steps:
1. **Define a custom rendering function** that accepts a `DataItem` and returns the desired JSX markup.
2. **Overwrite the default Tile by passing this function to the `Agenda` component** via the `Tile` prop:
```js
'use client';
import Agenda from 'glamrock-agenda';
import AgendaStyled from './style'; // wrapper that contains all the styling
import useEvents from './useEvents'; // hook to prepare data
import { defaultOptions, defaultComponents } from './settings'; // default settings
const EagerlyAgenda = () => {
const postsPerPage = defaultOptions.postsPerPage;
const useLoadMore = defaultOptions.useLoadMore;
const { currentParams, data, filters, handleParamsChange, loadMore } = useEvents({
postsPerPage,
useLoadMore,
});
// extend default options
const customOptions = {
...defaultOptions,
loadMore,
// overwrite default value
promoFrequency: 2,
// overwrite default promo strips
promoStrips: [
<div key={1} style={{ background: 'green' }}>
Promo 1
</div>,
<div key={2} style={{ background: 'blue' }}>
Promo 2
</div>,
],
};
// extend default components
const customComponents = {
...defaultComponents,
// add custom Tile
Tile: (item) => (
<div key={item.title} className="custom-tile">
<h4 style={{ color: 'blue' }}>{item.title}</h4>
<a href={item.link}>Read more</a>
</div>
),
};
return (
<AgendaStyled>
<Agenda
data={data}
helperText={}
searchParams={currentParams}
handleParamsChange={handleParamsChange}
filters={filters}
options={customOptions}
components={customComponents}
/>
</AgendaStyled>
);
};
export default EagerlyAgenda;
```
## Build & Publish
You can use this template and
change the name under package.json.
Build
```
npm run build
```
Build & Watch
```
npm run build:watch
```
Publish (public library)
Be sure you are either logged in under `npm login` or you have a token (check https://docs.npmjs.com/creating-and-viewing-access-tokens).
```
npm run publish --access=public
```