Basic poll content type to add time slots

Author: pilz

docs/docs/concepts/domain-model.md

@@ -0,0 +1,69 @@
+---
+myst:
+  html_meta:
+    "description": "The Doodle-style domain model used by experimental.doodle"
+    "property=og:description": "The Doodle-style domain model used by experimental.doodle"
+    "property=og:title": "Domain model"
+    "keywords": "Plone, Experimental Doodle, domain, model, poll, vote"
+---
+
+# Domain model
+
+`experimental.doodle` provides a Doodle-style service to find the best time
+for an appointment among several people. This page explains the building
+blocks of that model.
+
+## Poll
+
+A **Poll** is the central object. It represents one scheduling question
+("Lunch this week, when?") and carries:
+
+- a **title** and an optional **description**, both provided by the
+  standard Plone Dublin Core behavior;
+- a list of **proposed time slots**: at least two date/time options that
+  participants can vote on.
+
+A Poll is a leaf content type and holds no sub-content. The Poll stores
+its own voting data directly, rather than relying on separate content
+objects.
+
+## Options
+
+The **options** form an ordered list of timezone-aware date/time values.
+The order matters: each vote refers to options by their position in this
+list. Editing or reordering options after participants have voted will
+therefore break existing votes. Treat options as fixed once you share the
+poll with participants.
+
+The current version enforces a minimum of two options at the schema level.
+A single-option poll isn't a poll.
+
+## Participants and votes
+
+A **participant** identifies themselves with a free-text name. Voting
+requires no Plone account, which matches how Doodle itself works: you
+share a poll by link, and anyone with the link can respond.
+
+A **vote** is one participant's response to a poll. It contains a `yes` or
+`no` choice for each option. The current version intentionally omits a
+`maybe` value.
+
+```{note}
+Votes and the vote-casting API arrive in a later step. This page describes
+the target model; the `Poll` content type is the first piece in place.
+```
+
+## Tally
+
+The **tally** is the aggregated result of all votes: for each option, the
+number of `yes` responses. The package computes it on demand from the
+stored votes and doesn't persist it.
+
+## Why these choices
+
+- A single Dexterity content type keeps the data flat and easy to reason
+  about. There are no per-option or per-vote objects polluting the catalog.
+- Votes live as annotations on the Poll because they belong to that poll
+  and have no independent lifecycle.
+- Free-text participant names match Doodle's actual product behavior and
+  keep the current version usable without authentication infrastructure.

docs/docs/concepts/index.md

@@ -18,3 +18,11 @@ The Diátaxis framework also calls this class of documentation _explanation_.
 ```{seealso}
 https://diataxis.fr/explanation/
 ```
+
+## Available concepts
+
+```{toctree}
+:maxdepth: 1
+
+domain-model
+```

docs/docs/glossary.md

@@ -8,7 +8,7 @@ myst:
 ---
 
 This glossary provides example terms and definitions relevant to **Experimental Doodle**.
-A new addon for Plone
+A new add-on for Plone
 
 ```{note}
 This is an example glossary demonstrating MyST Markdown’s `{glossary}` directive. You can adapt it for your project’s appendix by editing or replacing these entries with your own terms and definitions.

docs/docs/index.md

@@ -1,16 +1,16 @@
 ---
 myst:
   html_meta:
-    "description": "A new addon for Plone"
-    "property=og:description": "A new addon for Plone"
+    "description": "A new add-on for Plone"
+    "property=og:description": "A new add-on for Plone"
     "property=og:title": "Experimental Doodle"
-    "keywords": "Experimental Doodle, documentation, A new addon for Plone"
+    "keywords": "Experimental Doodle, documentation, A new add-on for Plone"
 ---
 
 # Experimental Doodle
 
 Welcome to the documentation for Experimental Doodle!
-A new addon for Plone
+A new add-on for Plone
 
 This scaffold provides a ready-to-use environment for creating comprehensive documentation for {term}`Plone` projects, based on {term}`Plone Sphinx Theme`.
 

docs/docs/reference/index.md

@@ -18,6 +18,14 @@ This part of the documentation contains reference material, including APIs, conf
 https://diataxis.fr/reference/
 ```
 
+## Content types
+
+```{toctree}
+:maxdepth: 1
+
+poll-content-type
+```
+
 ## Configuration
 
 -   {doc}`plone:contributing/documentation/themes-and-extensions`

docs/docs/reference/poll-content-type.md

@@ -0,0 +1,144 @@
+---
+myst:
+  html_meta:
+    "description": "Reference for the Poll Dexterity content type"
+    "property=og:description": "Reference for the Poll Dexterity content type"
+    "property=og:title": "Poll content type"
+    "keywords": "Plone, Dexterity, Poll, content type, experimental.doodle"
+---
+
+# `Poll` content type
+
+The `Poll` Dexterity content type represents a single Doodle-style poll.
+The `experimental.doodle:default` GenericSetup profile registers it, and
+the type is globally addable to any folderish container.
+
+## Schema
+
+The module `experimental.doodle.content.poll` defines the `IPoll` schema.
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `title` | `TextLine` (via `plone.dublincore`) | yes | Inherited from the standard Dublin Core behavior. |
+| `description` | `Text` (via `plone.dublincore`) | no | Inherited from the standard Dublin Core behavior. |
+| `options` | `List(value_type=Datetime)` | yes | Proposed time slots. A schema invariant enforces a minimum of two entries. |
+
+The `options` field uses `defaultFactory=list` so each new Poll instance
+starts with a fresh empty list rather than a shared mutable default. The
+"at least two options" rule lives in a schema invariant rather than the
+field's `min_length`, so the add form can render with an empty list and
+only complains on submit.
+
+## Factory type information
+
+The package ships the Factory Type Information (FTI) at
+`src/experimental/doodle/profiles/default/types/Poll.xml`.
+
+Key properties:
+
+- **`klass`**: `experimental.doodle.content.poll.Poll`
+- **`schema`**: `experimental.doodle.content.poll.IPoll`
+- **`factory`**: `Poll`
+- **`add_permission`**: `cmf.AddPortalContent`
+- **`global_allow`**: `True`
+- **`filter_content_types`**: `True` with an empty `allowed_content_types`
+  list. A Poll is a leaf and can't contain other content.
+- **`default_view`** and **`immediate_view`**: `view` (the standard
+  Dexterity default view; a dedicated view ships in a later step).
+
+### Enabled behaviors
+
+- `plone.dublincore`: title, description, dates, language, and related metadata.
+- `plone.namefromtitle`: derives the id from the title.
+- `plone.shortname`: supports manual override of the id when needed.
+- `plone.ownership`: tracks creator and contributors.
+
+## Creating a poll programmatically
+
+```python
+from datetime import datetime, timedelta, timezone
+from plone import api
+
+
+def create_lunch_poll(container):
+    now = datetime.now(tz=timezone.utc)
+    return api.content.create(
+        container=container,
+        type="Poll",
+        title="Team lunch",
+        description="When can everyone make it?",
+        options=[
+            now + timedelta(days=1, hours=12),
+            now + timedelta(days=1, hours=13),
+            now + timedelta(days=2, hours=12),
+        ],
+    )
+```
+
+The `options` list must contain at least two date/time values. Otherwise,
+schema validation raises `zope.interface.Invalid`.
+
+## Creating a poll through `plone.restapi`
+
+```http
+POST /plone/@@plone.restapi.services HTTP/1.1
+Content-Type: application/json
+Accept: application/json
+
+{
+    "@type": "Poll",
+    "title": "Team lunch",
+    "description": "When can everyone make it?",
+    "options": [
+        "2026-06-01T12:00:00+00:00",
+        "2026-06-01T13:00:00+00:00",
+        "2026-06-02T12:00:00+00:00"
+    ]
+}
+```
+
+`plone.restapi` handles the standard create endpoint via `POST` on the
+container address with `@type: "Poll"`.
+
+## Validation
+
+Schema-level constraints enforced today:
+
+- The `options` field is **mandatory**.
+- Every element of `options` must be a `datetime`.
+- The schema invariant `at_least_two_options` rejects a submission whose
+  `options` list has fewer than two entries. The invariant runs on form
+  submit, not on widget render, so the add form opens cleanly.
+
+Other rules, for example forbidding past date/time values, removing
+duplicate slots, or restricting how options can change after votes exist,
+are intentionally out of scope for the current version. Follow-up steps
+will address them.
+
+## Upgrading existing sites
+
+The `experimental.doodle:default` profile registers the `Poll` FTI at
+version `1001`. Sites installed with profile version `1000` can upgrade in
+place:
+
+1. Open the Plone control panel.
+2. Go to {guilabel}`Add-ons` and run the available upgrade step for
+   `experimental.doodle` ("Install Poll content type").
+
+You can run the same step programmatically:
+
+```python
+from plone import api
+
+setup_tool = api.portal.get_tool("portal_setup")
+setup_tool.upgradeProfile("experimental.doodle:default")
+```
+
+The upgrade handler lives at
+`experimental.doodle.upgrades.v1001.install_poll_type` and re-imports the
+GenericSetup `typeinfo` step. The step is idempotent: it's safe to run on
+sites that already have the `Poll` FTI.
+
+## Related concepts
+
+- {doc}`/concepts/domain-model`: the overall Doodle-style domain.

news/poll-type.feature

@@ -0,0 +1 @@
+Add `Poll` content type with title, description, and a list of proposed time slots.

src/experimental/doodle/configure.zcml

@@ -16,6 +16,7 @@
   <include file="profiles.zcml" />
   <include file="permissions.zcml" />
 
+  <include package=".content" />
   <include package=".controlpanels" />
   <include package=".indexers" />
   <include package=".vocabularies" />

src/experimental/doodle/content/configure.zcml

@@ -0,0 +1,10 @@
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    i18n_domain="experimental.doodle"
+    >
+
+  <!-- Dexterity classes are wired through the FTI XML in
+       profiles/default/types/Poll.xml. This file exists so the content
+       subpackage can be included from the main configure.zcml. -->
+
+</configure>

src/experimental/doodle/content/poll.py

@@ -0,0 +1,44 @@
+"""Poll content type: a Doodle-style scheduling poll."""
+
+from experimental.doodle import _
+from plone.dexterity.content import Item
+from plone.supermodel import model
+from zope import schema
+from zope.interface import implementer
+from zope.interface import Invalid
+from zope.interface import invariant
+
+
+MIN_OPTIONS = 2
+
+
+class IPoll(model.Schema):
+    """Schema for a Doodle-style poll.
+
+    A poll proposes a list of date/time options and collects yes/no votes
+    from participants who identify themselves by a free-text name.
+    """
+
+    options = schema.List(
+        title=_("Proposed time slots"),
+        description=_("Date and time options that participants can vote on."),
+        value_type=schema.Datetime(
+            title=_("Time slot"),
+        ),
+        required=True,
+        defaultFactory=list,
+    )
+
+    @invariant
+    def at_least_two_options(data):
+        """A poll needs at least two distinct time slots to be meaningful."""
+        options = getattr(data, "options", None) or []
+        if len(options) < MIN_OPTIONS:
+            raise Invalid(
+                _("A poll needs at least two proposed time slots."),
+            )
+
+
+@implementer(IPoll)
+class Poll(Item):
+    """A Doodle-style poll."""