diff --git a/workspaces/announcements/README.md b/workspaces/announcements/README.md index 94044a3fa6..d501f148bc 100644 --- a/workspaces/announcements/README.md +++ b/workspaces/announcements/README.md @@ -1,16 +1,45 @@ -# [Backstage](https://backstage.io) +# Announcements plugin for Backstage -This is your newly scaffolded Backstage App, Good Luck! +The Announcements plugin manages and displays announcements within Backstage. -To start the app, run: +## Features -```sh -yarn install -yarn dev -``` +This plugin provides: -To generate knip reports for this app, run: +- a component to display the latest announcement as a banner, if there is one +- a component to display the latest announcements, for example on a homepage +- pages to list, view, create, edit and delete announcements +- an admin portal to manage announcements +- integration with the [`@backstage/plugin-search`](https://github.com/backstage/backstage/tree/master/plugins/search) plugin +- integration with the [`@backstage/plugin-permission-backend`](https://github.com/backstage/backstage/tree/master/plugins/permission-backend) plugin +- integration with the [`@backstage/plugin-events-backend`](https://github.com/backstage/backstage/tree/master/plugins/events-backend) plugin +- integration with the [`@backstage/plugin-signals-backend`](https://github.com/backstage/backstage/tree/master/plugins/signals-backend) plugin -```sh -yarn backstage-repo-tools knip-reports -``` +You will find installation instructions in each plugin's readme file. + +## How does it look? + +### Latest announcement banner + +![Latest announcement banner](./images/announcement_banner.png) + +### Announcements card + +![Announcements card](./images/announcements_card.png) + +### Announcements page + +![Announcements page](./images/announcements_page.png) + +### Announcements search + +![Announcements search results](./images/announcements_search.png) + +### Admin Portal + +![Announcements admin portal](./images/announcements_admin_portal.png) + +## Previously maintained by + +- [procore-oss](https://github.com/procore-oss/backstage-plugin-announcements) +- [K-Phoen](https://github.com/K-Phoen/backstage-plugin-announcements) diff --git a/workspaces/announcements/docker-compose.yml b/workspaces/announcements/docker-compose.yml new file mode 100644 index 0000000000..57feeca3eb --- /dev/null +++ b/workspaces/announcements/docker-compose.yml @@ -0,0 +1,8 @@ +services: + psql: + image: postgres + environment: + POSTGRES_USER: ${POSTGRES_USER} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + ports: + - ${POSTGRES_PORT}:5432 diff --git a/workspaces/announcements/env.sample b/workspaces/announcements/env.sample new file mode 100644 index 0000000000..de4c746e52 --- /dev/null +++ b/workspaces/announcements/env.sample @@ -0,0 +1,4 @@ +POSTGRES_HOST=localhost +POSTGRES_PORT=5432 +POSTGRES_USER=postgres +POSTGRES_PASSWORD=postgres diff --git a/workspaces/announcements/images/announcement_banner.png b/workspaces/announcements/images/announcement_banner.png new file mode 100644 index 0000000000..4188e28dde Binary files /dev/null and b/workspaces/announcements/images/announcement_banner.png differ diff --git a/workspaces/announcements/images/announcements_admin_portal.png b/workspaces/announcements/images/announcements_admin_portal.png new file mode 100644 index 0000000000..da36b6d62a Binary files /dev/null and b/workspaces/announcements/images/announcements_admin_portal.png differ diff --git a/workspaces/announcements/images/announcements_card.png b/workspaces/announcements/images/announcements_card.png new file mode 100644 index 0000000000..abc435463a Binary files /dev/null and b/workspaces/announcements/images/announcements_card.png differ diff --git a/workspaces/announcements/images/announcements_context_menu.png b/workspaces/announcements/images/announcements_context_menu.png new file mode 100644 index 0000000000..f681bfee8c Binary files /dev/null and b/workspaces/announcements/images/announcements_context_menu.png differ diff --git a/workspaces/announcements/images/announcements_page.png b/workspaces/announcements/images/announcements_page.png new file mode 100644 index 0000000000..9f31c37ee8 Binary files /dev/null and b/workspaces/announcements/images/announcements_page.png differ diff --git a/workspaces/announcements/images/announcements_search.png b/workspaces/announcements/images/announcements_search.png new file mode 100644 index 0000000000..8e778a356a Binary files /dev/null and b/workspaces/announcements/images/announcements_search.png differ diff --git a/workspaces/announcements/plugins/announcements-backend/README.md b/workspaces/announcements/plugins/announcements-backend/README.md index 3f88f773f9..0d4fbeb106 100644 --- a/workspaces/announcements/plugins/announcements-backend/README.md +++ b/workspaces/announcements/plugins/announcements-backend/README.md @@ -1,6 +1,6 @@ -# announcements +# announcements-backend -This is the backend for the Announcements plugin. This plugin provides: +The backend for the Announcements plugin. This plugin provides: - REST APIs for managing announcements and categories - Integration with the [`@backstage/plugin-search`](https://github.com/backstage/backstage/tree/master/plugins/search) plugin @@ -8,7 +8,7 @@ This is the backend for the Announcements plugin. This plugin provides: ## Installation -This plugin is installed via the `@backstage-community/plugin-announcements-backend` package. To install it to your backend package, run the following command: +To install it to your backend package, run the following command: ```bash # From your root directory diff --git a/workspaces/announcements/plugins/announcements-node/README.md b/workspaces/announcements/plugins/announcements-node/README.md index 7a1a750c6e..786d4b56ec 100644 --- a/workspaces/announcements/plugins/announcements-node/README.md +++ b/workspaces/announcements/plugins/announcements-node/README.md @@ -2,6 +2,14 @@ Exports shared types and services for backend-related announcements functionality. +## Events support + +The announcements plugin supports the Backstage Event system. View the [events](./docs/events.md) documentation for more information. + +## Signals support + +The announcements plugin supports the Backstage Signal system. View the [signals](./docs/signals.md) documentation for more information. + ## Previously maintained by - [procore-oss](https://github.com/procore-oss/backstage-plugin-announcements/tree/main/plugins/announcements-node) diff --git a/workspaces/announcements/plugins/announcements-node/docs/events.md b/workspaces/announcements/plugins/announcements-node/docs/events.md new file mode 100644 index 0000000000..22fb5efd6a --- /dev/null +++ b/workspaces/announcements/plugins/announcements-node/docs/events.md @@ -0,0 +1,36 @@ +# Support for events + +The announcements plugin supports the Backstage Event system. + +```ts +import { createBackend } from '@backstage/backend-defaults'; + +const backend = createBackend(); +backend.add(import('@backstage/events-backend')); +backend.add(import('@backstage-community/plugin-announcements-backend')); + +backend.start(); +``` + +## Topic + +All events are published to the `announcements` topic. + +## Event actions + +The following event actions are supported + +### Announcements + +All announcement payloads include the entire contents of the announcement + +- 'create_announcement': Create a new announcement +- 'update_announcement': Update an existing announcement +- 'delete_announcement': Delete an existing announcement + +### Categories + +All category payloads include the category slug. + +- 'create_category': Create a new category +- 'delete_category': Delete an existing category diff --git a/workspaces/announcements/plugins/announcements-node/docs/signals.md b/workspaces/announcements/plugins/announcements-node/docs/signals.md new file mode 100644 index 0000000000..617ed16cc3 --- /dev/null +++ b/workspaces/announcements/plugins/announcements-node/docs/signals.md @@ -0,0 +1,20 @@ +# Support for signals + +The announcements plugin supports delivering announcements to the frontend in near real-time using the [@backstage/plugins-signals](https://github.com/backstage/backstage/tree/master/plugins/signals) plugin. This is currently supported in the `` [component](../../announcements/docs/latest-announcement-banner.md). + +## Installation + +> [!IMPORTANT] +> This feature requires the `@backstage/plugin-events-backend` plugin to be installed and running. + +```ts +import { createBackend } from '@backstage/backend-defaults'; + +const backend = createBackend(); +backend.add(import('@backstage/events-backend')); +... +backend.add(import('@backstage/signals-backend')); +backend.add(import('@backstage-community/plugin-announcements-backend')); + +backend.start(); +``` diff --git a/workspaces/announcements/plugins/announcements/README.md b/workspaces/announcements/plugins/announcements/README.md index 82098c6894..200c930d1d 100644 --- a/workspaces/announcements/plugins/announcements/README.md +++ b/workspaces/announcements/plugins/announcements/README.md @@ -1,6 +1,6 @@ # announcements -This is the frontend for the Announcements plugin. This plugin provides: +The frontend for the Announcements plugin. This plugin provides: - a component to display the latest announcements, for example on a homepage - pages to list, view, create, edit and delete announcements @@ -15,7 +15,7 @@ yarn --cwd packages/app add @backstage-community/plugin-announcements Expose the announcements page: -```ts +```tsx // packages/app/src/App.tsx import { AnnouncementsPage } from '@backstage-community/plugin-announcements'; @@ -42,7 +42,7 @@ yarn --cwd packages/app add @backstage-community/plugin-announcements Add the plugin to `packages/app/src/App.tsx`: -```ts +```tsx import announcementsPlugin from '@backstage-community/plugin-announcements/alpha'; // ... @@ -78,6 +78,54 @@ app: filter: kind:component,system,group,api ``` +## Components + +- [Display latest announcements on a page](./docs/latest-announcements-on-page.md) +- [Display a banner for the latest announcement](./docs/latest-announcement-banner.md) +- [Display announcements in a timeline](./docs/announcement-timeline.md) + +## Customization + +### Overriding the AnnouncementCard + +It is possible to specify the length of the title for announcements rendered on the `AnnouncementsPage`. You can do this by passing a `cardOptions` prop to the `AnnouncementsPage` component. The `cardOptions` prop accepts an object with the following properties: + +```ts +{ + titleLength: number; // defaults to 50 +} +``` + +Example + +```tsx + +``` + +### Overriding the AnnouncementsPage + +It is possible to specify the Announcements within a specific category rendered on the `AnnouncementsPage`. You can do this by passing a `category` prop to the `AnnouncementsPage` component. The `AnnouncementsPage` prop accepts an value such as: + +```ts +category = 'conferences'; +``` + +Example + +```tsx + +``` + +### Overriding the AnnouncementCreateButton + +It is possible to specify the text for the "New announcement" button rendered on the `AnnouncementsPage`. You can do this by passing a `buttonOptions` prop to the `AnnouncementsPage` component. The `buttonOptions` prop accepts an object with the following properties: + +```ts +{ + name: string; // defaults to 'announcement' +} +``` + ## Development ### Getting started diff --git a/workspaces/announcements/plugins/announcements/docs/announcement-timeline.md b/workspaces/announcements/plugins/announcements/docs/announcement-timeline.md new file mode 100644 index 0000000000..0c5dfbc46e --- /dev/null +++ b/workspaces/announcements/plugins/announcements/docs/announcement-timeline.md @@ -0,0 +1,21 @@ +# Display announcements in a timeline + +Adding the `AnnouncementsTimeline` component to a page will display a raw timeline of the latest announcements. + +```ts +import { AnnouncementsTimeline } from '@backstage-community/plugin-announcements'; + +export const TimelineExampleCard = () => { + return ( + + + + + + + + + + ); +}; +``` diff --git a/workspaces/announcements/plugins/announcements/docs/latest-announcement-banner.md b/workspaces/announcements/plugins/announcements/docs/latest-announcement-banner.md new file mode 100644 index 0000000000..f03690eab2 --- /dev/null +++ b/workspaces/announcements/plugins/announcements/docs/latest-announcement-banner.md @@ -0,0 +1,25 @@ +# Display a banner for the latest announcement + +Adding the `NewAnnouncementBanner` component to a page will display a banner with the title and excerpt of the latest unseen announcement. This banner will update in near real-time when a new announcement is created if your Backstage instance is configured to support signals. + +**Note:** if there are no announcements or the latest announcement has already been seen by the user, nothing will be displayed. + +```ts +import { NewAnnouncementBanner } from '@backstage-community/plugin-announcements'; + +export const HomePage = () => { + return ( + +
+ + + + + + + + + + ); +}; +``` diff --git a/workspaces/announcements/plugins/announcements/docs/latest-announcements-on-page.md b/workspaces/announcements/plugins/announcements/docs/latest-announcements-on-page.md new file mode 100644 index 0000000000..c07bc94b86 --- /dev/null +++ b/workspaces/announcements/plugins/announcements/docs/latest-announcements-on-page.md @@ -0,0 +1,24 @@ +# Display latest announcements on a page + +Adding the `AnnouncementsCard` component to a page will display a Card with the latest announcements. +Announcements yet unseen by the user will be prefixed by a specific icon. + +```ts +import { AnnouncementsCard } from '@backstage-community/plugin-announcements'; + +export const HomePage = () => { + return ( + +
+ + + + + + + + + + ); +}; +``` diff --git a/workspaces/announcements/plugins/search-backend-module-announcements/docs/search.md b/workspaces/announcements/plugins/search-backend-module-announcements/docs/search.md new file mode 100644 index 0000000000..a46efb54be --- /dev/null +++ b/workspaces/announcements/plugins/search-backend-module-announcements/docs/search.md @@ -0,0 +1,50 @@ +# Integration with `@backstage/plugin-search` + +## Installation + +Add the module to your backend app: + +```bash +yarn add --cwd packages/backend @backstage-community/plugin-search-backend-module-announcements +``` + +Update `packages/backend/src/index.ts` to import the announcements search module and register it with the backend: + +```ts +// ... +const backend = createBackend(); + +// ... + +backend.add(import('@backstage-community/plugin-announcements-backend')); +backend.add( + import('@backstage-community/plugin-search-backend-module-announcements'), +); +// ... +``` + +## Adding search support to the frontend + +```tsx +import { AnnouncementSearchResultListItem } from '@backstage-community/plugin-announcements'; +import RecordVoiceOverIcon from '@material-ui/icons/RecordVoiceOver'; + +// ... +, + }, + ]} +/> + + + // ... + + +```