Docs for the views

Author: pilz

docs/docs/how-to-guides/index.md

@@ -18,6 +18,13 @@ This part of the documentation contains how-to guides, including installation an
 https://diataxis.fr/how-to-guides/
 ```
 
+## Polls
+
+```{toctree}
+:maxdepth: 1
+
+vote-on-a-poll
+```
 
 ## Authors
 

docs/docs/how-to-guides/vote-on-a-poll.md

@@ -0,0 +1,57 @@
+---
+myst:
+  html_meta:
+    "description": "How to vote on a poll and read the results in experimental.doodle"
+    "property=og:description": "How to vote on a poll and read the results"
+    "property=og:title": "Vote on a poll"
+    "keywords": "Plone, experimental.doodle, poll, vote, results"
+---
+
+# Vote on a poll
+
+This guide explains how a visitor casts a vote on a published Poll and
+reads the aggregated results.
+
+## Prerequisites
+
+- A Plone site with `experimental.doodle` installed.
+- At least one published Poll with two or more time slots.
+
+## Cast a vote
+
+1. Open the Poll in your browser. The default view shows the vote form.
+2. Enter your name in the **Your name** field. Any non-empty string is
+   accepted; no account is needed.
+3. For each proposed time slot, select **Yes** or **No**. Every slot
+   defaults to **No** when the page loads.
+4. Click **Cast vote**. The page reloads and confirms your vote was
+   recorded. You can vote again at any time. Casting a second vote with
+   the same name replaces your earlier response.
+
+## Read the results
+
+Click **View results** below the vote form, or navigate to the Poll's
+`@@results` view directly (append `/@@results` to the Poll address). The
+results page shows:
+
+- A table with each time slot and the number of **Yes** votes it received.
+- A proportional bar for each slot so you can see relative support at a
+  glance.
+- A list of participants who have voted.
+
+Click **Back to poll** to return to the vote form.
+
+## Create a poll (for editors)
+
+1. Navigate to the folder where you want to create the poll.
+2. Add a new **Poll** content item.
+3. Enter a **title** and, optionally, a **description**.
+4. Add at least two **time slots** using the date/time picker for each
+   entry in the **Proposed time slots** field.
+5. Save the item and publish it so visitors can reach it without logging
+   in.
+
+## Related references
+
+- {doc}`/reference/poll-content-type`: the Poll schema and FTI details.
+- {doc}`/reference/vote-storage`: the Python API behind the vote form.

docs/docs/reference/index.md

@@ -34,6 +34,14 @@ poll-content-type
 vote-storage
 ```
 
+## Views
+
+```{toctree}
+:maxdepth: 1
+
+poll-views
+```
+
 ## Configuration
 
 -   {doc}`plone:contributing/documentation/themes-and-extensions`

docs/docs/reference/poll-views.md

@@ -0,0 +1,91 @@
+---
+myst:
+  html_meta:
+    "description": "Reference for the Poll browser views in experimental.doodle"
+    "property=og:description": "Reference for the Poll browser views"
+    "property=og:title": "Poll views"
+    "keywords": "Plone, experimental.doodle, poll, view, results, browser"
+---
+
+# Poll views
+
+`experimental.doodle` ships two browser views for `Poll` objects, both
+registered against `IPoll` on `IBrowserLayer`.
+
+## Vote form (`@@poll_view`)
+
+**Class:** `experimental.doodle.browser.poll.PollView`
+**Permission:** `zope2.View` (no login required)
+**Default view:** yes (`default_view` on the FTI since profile version `1002`)
+
+The vote form renders the poll title, description, and a `<form>` with:
+
+- a text field for the participant's name;
+- one `yes`/`no` radio pair per proposed time slot;
+- a submit button.
+
+### Form submission
+
+On submit the view:
+
+1. Strips the `name` field; returns a form error if the result is empty.
+2. Reads `votes_0`, `votes_1`, … from the request; absent values default
+   to `"false"`.
+3. Calls `IVoteStorage(context).cast_vote(name, votes)`.
+4. Redirects to `@@poll_view` (Post/Redirect/Get pattern).
+
+Any `ValueError` from `cast_vote` is caught and shown as an inline error
+without a redirect.
+
+### Template helpers
+
+| Property | Returns |
+|---|---|
+| `options` | `[(index, label), ...]` where `label` is a human-readable date/time string. |
+| `error` | The current error string, or `None`. |
+| `participant_count` | Number of participants who have already voted. |
+
+## Results (`@@results`)
+
+**Class:** `experimental.doodle.browser.poll.PollResultsView`
+**Permission:** `zope2.View`
+
+The results view shows the aggregated tally and a participant list. It
+is read-only; there is no form or POST handling.
+
+### Template helpers
+
+| Property | Returns |
+|---|---|
+| `rows` | `[(label, yes_count, max_count), ...]`, one row per slot. `max_count` is the highest yes-count across all slots, used to compute proportional bar widths. |
+| `participants` | `list[str]`, participant names sorted alphabetically. |
+
+A `@@results` link appears on the vote form. A "Back to poll" link
+returns to `@@poll_view` from the results.
+
+## Styles
+
+Both views include `++plone++experimental.doodle/poll.css` from
+`src/experimental/doodle/browser/static/`. The stylesheet covers only
+poll-specific elements and makes no global overrides.
+
+## Profile version
+
+The FTI change (`default_view` set to `poll_view`, `results` added to
+`view_methods`) ships at profile version `1002`. Sites on `1001` can
+upgrade through the {guilabel}`Add-ons` control panel or
+programmatically:
+
+```python
+from plone import api
+
+api.portal.get_tool("portal_setup").upgradeProfile(
+    "experimental.doodle:default"
+)
+```
+
+## Related
+
+- {doc}`vote-storage`: the adapter the views delegate to.
+- {doc}`poll-content-type`: the content type the views render.
+- {doc}`/how-to-guides/vote-on-a-poll`: step-by-step voting guide.

src/experimental/doodle/browser/poll.py

@@ -42,8 +42,7 @@ def __call__(self):
     def options(self):
         """Return ``[(index, label), ...]`` for every proposed slot."""
         return [
-            (i, _format_slot(dt))
-            for i, dt in enumerate(self.context.options or [])
+            (i, _format_slot(dt)) for i, dt in enumerate(self.context.options or [])
         ]
 
     @property