EPIC: Add announcements to commons play page.

[github-actions[bot]]

Note: Please read through all the instructions on this epic - we do not expect you to complete all of it at once, and you should definitely split it into separate issues and PRs. Feel free to tackle as much as you can, in order as specified below.

Have you updated the title?

• [X] I have updated the issue's title.

As a...

admin

I can...

add an announcement at the top of the commons

So that...

I can communicate to the players

Discussion

The announcements box at the top of the commons play page is intended for the administrator of the game to post announcements for players. However, that feature hasn't been implemented yet.

This Epic (collection of stories) introduces that feature to the game. You should break this epic into multiple issues before working on it.

Copy the user stories/acceptance criteria into a separate issue before starting to work on it, and make PRs for each part separately. Benefits to this staged approach:

• You'll earn more points that way
• You'll earn them more quickly
• PRs are easier to code review and merge
• If you don't finish, you get partial credit for what you did complete, and students in a future class can finish off your work.

The issues below are broken up into:

• two backend issues that must be completed in sequence: first B1 then B2.
• two frontend issues that must be worked in in sequence, first F1 then F2. F1 can proceed in parallel with B1, B2 as long as the folks working on B2 and F1 coordinate the format of the fixtures.
• issue F2 depends on B2 and F1 being completed first.

Issue B1: Backend, Add Entity / Repository for announcements

Developer Story:

• As a developer
• I have access to a database table for announcements
• So that I can build future features using this table

Acceptance Criteria:

• [ ] There is an entity file for an Announcements table with field described below
• [ ] There is an repository file for a Announcements table

Fields:

• id, long autogenerated
• commonsId, required, id of the associated commons
• start (required, datetime to start showing the announcement, defaults to current datetime)
• end (optional, datetime to stop showing the announcement)
• announcement (String)

Issue B2: Backend Controller for CRUD operations for announcements

Developer Story:

• As an developer
• I have access to backend endpoints (through swagger) for CRUD operations for the Announcements table
• So that I can build future features using this table

Acceptance Criteria:

• [ ] There is a POST endpoint to create new announcements
• [ ] The POST endpoint to create new announcements rejects POST values with invalid data (e.g. a commonsId for a commons that doesn't exist, announcements with empty text, end date that is before start date, start date blank)
• [ ] The POST endpoint allows end date to be blank, in which case it is stored as NULL in the database
• [ ] There is a GET endpoint to get all announcements for a specified commons
• [ ] There is a GET endpoint to get an announcement by its individual id number
• [ ] There is a PUT endpoint that allows updating the announcement. It performs the same validations as the POST endpoing.
• [ ] There is a DELETE endpoint that allows deleting an announcement

Issue F1: fixtures/components for announcements

Developer Story:

• As an developer
• I have access to fixtures, components and storybook stories for a form and table for Announcements
• So that I can build future features for the Announcements table

Acceptance Criteria:

• [ ] There is a form component for announcements suitable for crud operations (similar to team03 form components, but with a nice large textarea for the announcement text.) Note that the commonsId is not part of the form; it will be set implicitly.
• [ ] There is a table component for announcements (similar to team03 table components) Note that the commonsId is not part of the table component; it will be the same for all entries in the table, so we will put it at the top of the page separately.
• [ ] There are fixtures that match the format of the GET operations for the API endpoints being worked on in the second issue. Note that the fixtures should be organized so that each set of announcements is for a single commons, since we only ever work with the announcements for one commons at at time, even though in the database they are all stored in the same database able.
• [ ] There are storybook entries for the form and table components. Note that the storybook entries for the table should focus on one commons at a time (see discussion above under fixtures).

Issue F2: Frontend Create. Read operations for announcements (and optionally Edit, Delete)

User story:

• As an admin
• I can create, read, update and destroy announcements for a user commons
• So that I can communicate important information to the users (farmers)

Acceptance Criteria:

• [ ] On the Admin Commons List page, there is a button next to the current buttons for Edit | Delete | Leaderboard | Stats CSV called Announcements that takes you to an index page with the url /admin/announcements/{commonsId} that shows a table containing the announcements for just that one commons.
• [ ] The page at /admin/announcements/{commonsId} should have a header that indicates which something like "Announcements for
• [ ] On the This page should include the name of the commons in the header so that the user knows which commons announcements are being created for.
• [ ] The Announcements Index page has a Create Announcement button that takes you to a page /admin/announcements/{commonsId}/create where you can create a new announcement for the commons identified by {commonsId}.
• [ ] On the Create Announcement page at /admin/announcements/{commonsId}/create, the commonsId field is not entered by the user, but is implicitly set; it will come from the {commonsId} in the url via the useParams hook.
• [ ] The page header at /admin/announcements/{commonsId}/create, should show the name of the commons. For example, if the name of the commons is Summer Meadows 123 the page should say something like Create Announcement for Commons Summer Meadows 123, with appropriate line breaks.
• [ ] The Delete button on the index page should work, or else it should be removed and factored out into a separate issue.
• [ ] The Edit button on the index page should work, or else it should be removed and factored out into a separate issue.
• [ ] Making the announcements actually appear on the Commons Page page is not part of this issue; that's separate.

Note: Additional issues if not dones as part of Issue F2 (defining the user stories and acceptance criteria is left as an exercise to the student):

• Issue F2a: Edit button added to Index page (if not done as part of Issue F2).
• Issue F2b: Delete button added to index page (if not done as part of Issue F2)

Issue F3: Frontend Make Announcements appear on Play Page

User stories:

• As an admin

• I can post messages that the users will see

• So that I can communicate important information to game players

• As a user (game player, farmer)

• I can see important announcements about game play

• So that I can see what's happening in the game

Note that you may want to implement a different component for announcements for the play page, perhaps based on the <Card> react component. See the way the commons cards are implemented on the HomePage as an example.

It's important that the announcements are clear, but also don't clutter up the play page too much.

If needed, you could make a component that shows, by default, only the first line of the text, and then has a place to click to see the full announcement, and then click to restore the compacted view. React offers a variety of ways to accomplish this; you may use your creativity. Don't get too fancy though; remember that this is intended to be a "minimum viable product" for announcements. Future functionality might include keeping track, for each individual user, which announcements they have seen or not seen, and differentiating new announcements from ones that have already been seen, using modals to alert the user about new announcements, but that's all for the future. Keep it simple in your first implementation, and then if there's time, you can propose additional issues to get fancier.

Acceptance Criteria:

• [ ] Announcements that have both a start and end specified appear at the top of the commons play page as long as the current date/time falls on or after the start date/time for the announcement, and is before the end date/time (if one is specified).
• [ ] Announcements that have no end specified appear at the top of the commons play page as long as the current date/time falls on or after the start date/time.
• [ ] The format of the announcements is clear and doesn't clutter up the play page too much.

Acceptance Criteria

• [ ] First thing that should be true when story is done.
• [ ] Second thing that should be true when story is done.

Implementation Todos

Frontend:

• [ ] First thing that must be done in the frontend code.
• [ ] Second thing that must be done in the frontend code.

Backend:

• [ ] First thing that must be done in the backend code.
• [ ] Second thing that must be done in the backend code.

Testing:

• [ ] Front end tests pass and there is adequate coverage
• [ ] Back end tests pass and there is adequate coverage