flaskbb-plugin-vote 1.0.0__py3-none-any.whl

flaskbb_plugin_vote-1.0.0.dist-info/METADATA

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: flaskbb-plugin-vote
+Version: 1.0.0
+Summary: A polls plugin for FlaskBB - attach single or multiple choice polls to topics and posts
+Project-URL: Homepage, https://github.com/flaskbb/flaskbb-plugin-vote
+Project-URL: Repository, https://github.com/flaskbb/flaskbb-plugin-vote
+Project-URL: Issues, https://github.com/flaskbb/flaskbb-plugin-vote/issues
+Project-URL: Changelog, https://github.com/flaskbb/flaskbb-plugin-vote/blob/master/CHANGELOG.md
+Author-email: Peter Justin <peter.justin@outlook.com>
+Maintainer-email: Peter Justin <peter.justin@outlook.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: flaskbb,plugin,poll,polls,vote
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: flaskbb>=3.0.0
+Description-Content-Type: text/markdown
+
+Vote
+====
+
+A polls plugin for FlaskBB. Lets a user create polls in a topic or post.
+
+
+Installation
+------------
+
+Install *flaskbb-plugin-vote* with
+``pip install flaskbb-plugin-vote``
+
+License
+-------
+This project is licensed under the terms of the [BSD License](/LICENSE).

flaskbb_plugin_vote-1.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+vote/__init__.py,sha256=qe5fCgir2CuecJQiHLamJ-u54lS8LTM18TYrmmaigiE,7928
+vote/forms.py,sha256=ZbVW5wXcAJ0jO99VWquk8ko2UrSGFi_eEEv84UWfsNg,724
+vote/models.py,sha256=1n1emFlRvjDuGGGG6-FU_wjnCEx2FJwWFbejbb30uwc,3908
+vote/utils.py,sha256=gHaXezSrHHN4sU6Bt9CXHKG7Pf6qNIpzQA1ncd3DG_0,4967
+vote/views.py,sha256=uL65qSqRTip-DfK5qNxL4Z7YvUG2vKde7g8PektKvK4,2436
+vote/migrations/202607301200_a1f3c9d7e2b4_add_vote_polls.py,sha256=nz2fNmvsm-djuhjYP5nfLQyNPDO-58TqIaFEyz56nxY,3202
+vote/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vote/static/vote.js,sha256=rKPYgXvz6UTWvs3HBXZ1OsGo-W74x7VWTmPWUDM3sqo,5192
+vote/templates/vote/_cheatsheet.html,sha256=cDqTxG7yrvgjjj9eOygIOeVbUDbh00O-BMlaYcwoWxs,165
+vote/templates/vote/_form_extra.html,sha256=i7TVZyGMaVBtUUcWdiPK98gYrTzTlVbi1FFZ0V7ea0I,2497
+vote/templates/vote/_poll_widget.html,sha256=PsWxWtD3jb1rqYoFF8lAXNAI1xZ_kyRcMNcdXjjmRuE,2828
+vote/templates/vote/_scripts.html,sha256=QGjcrojf6FzIA__K3u6SJJiCGS_tbBT4Pdulr9FOiUo,73
+vote/templates/vote/_toolbar_button.html,sha256=Mfg44LoleFEZ2S54l9ELsvtO7S_UQzNQK22gWHf325E,230
+flaskbb_plugin_vote-1.0.0.dist-info/METADATA,sha256=3_n0vONq3NtZwT2LEaXmlOe5jBCn8rPkYM_c5aTJnSc,1596
+flaskbb_plugin_vote-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+flaskbb_plugin_vote-1.0.0.dist-info/entry_points.txt,sha256=5Hc1Y1P4hLv9NSVwnBIiHzIVicSv7vEMzuFoNSfwHHM,30
+flaskbb_plugin_vote-1.0.0.dist-info/licenses/LICENSE,sha256=ebP4t6o_-IT9SPVkjzUZTaUR3CX0QsZ8qLSFbbUSSUM,1500
+flaskbb_plugin_vote-1.0.0.dist-info/RECORD,,

flaskbb_plugin_vote-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

flaskbb_plugin_vote-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[flaskbb_plugins]
+vote = vote

flaskbb_plugin_vote-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,31 @@
+Copyright (c) 2026 by Peter Justin and contributors. See AUTHORS for more
+details.
+
+Some rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+* The names of the contributors may not be used to endorse or
+  promote products derived from this software without specific
+  prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

vote/__init__.py

@@ -0,0 +1,257 @@
+"""
+vote
+~~~~
+
+A polls plugin for FlaskBB. Lets a poster attach a single- or
+multiple-choice poll to a topic or a reply, via a button on the markdown
+editor's toolbar.
+
+:copyright: (c) 2026 by Peter Justin.
+:license: BSD License, see LICENSE for more details.
+"""
+
+import os
+
+from flask import Flask
+from flask_login import current_user
+from flaskbb.core.settings import BoolSetting, IntSetting, SettingGroup, flaskbb_config
+from flaskbb.forum.forms import NewTopicForm, ReplyForm
+from flaskbb.forum.models import Post
+from flaskbb.utils.helpers import real, render_template
+from pluggy import HookimplMarker
+from wtforms import HiddenField
+
+from .forms import DeletePollForm, VoteForm
+from .models import Poll
+from .utils import can_delete_poll, create_poll_for_post, parse_poll_payload
+from .views import vote_bp
+
+__version__ = "1.0.0"
+
+hookimpl = HookimplMarker("flaskbb")
+
+# Stashes a pending poll payload on the Post between save and post-save hooks,
+# until the post has an id to attach it to.
+# Hooks: flaskbb_form_{topic,post}_save (before the post is saved) and
+# flaskbb_event_post_save_after (once it has an id to attach to).
+_PENDING_ATTR = "_vote_pending_payload"
+
+
+@hookimpl
+def flaskbb_load_migrations():
+    return os.path.join(os.path.dirname(__file__), "migrations")
+
+
+@hookimpl
+def flaskbb_load_translations():
+    return os.path.join(os.path.dirname(__file__), "translations")
+
+
+@hookimpl
+def flaskbb_load_blueprints(app: Flask):
+    app.register_blueprint(
+        vote_bp, url_prefix=app.config.get("PLUGIN_VOTE_URL_PREFIX", "/vote")
+    )
+
+
+SETTINGS = SettingGroup(
+    key="vote",
+    name="Vote Settings",
+    description="Settings for the poll plugin.",
+    settings=(
+        IntSetting(
+            key="MAX_OPTIONS",
+            value=10,
+            min=2,
+            max=50,
+            name="Maximum poll options",
+            description="The maximum number of options a poll may have.",
+        ),
+        BoolSetting(
+            key="TOPICS_ONLY",
+            value=False,
+            name="Only allow polls on topics",
+            description=(
+                "If enabled, a poll can only be attached to a topic's first "
+                "post, not to a reply. Polls already attached to a reply "
+                "are unaffected."
+            ),
+        ),
+    ),
+)
+
+
+@hookimpl
+def flaskbb_load_setting_groups():
+    return SETTINGS
+
+
+_DEFAULT_MAX_OPTIONS = SETTINGS.settings[0].value
+_DEFAULT_TOPICS_ONLY = SETTINGS.settings[1].value
+
+
+def _max_options() -> int:
+    # Falls back to the setting's own default when the plugin hasn't been
+    # installed yet (admin panel > Plugins > Install seeds it into the
+    # settings table) - a poll shouldn't be impossible to create just
+    # because nobody has visited that page yet.
+    value = flaskbb_config["VOTE_MAX_OPTIONS"]
+    return int(value) if value is not None else _DEFAULT_MAX_OPTIONS
+
+
+def _topics_only() -> bool:
+    value = flaskbb_config["VOTE_TOPICS_ONLY"]
+    return bool(value) if value is not None else _DEFAULT_TOPICS_ONLY
+
+
+# Attaching the hidden poll_data field to the topic/post forms
+@hookimpl
+def flaskbb_form_topic(form: type[NewTopicForm]):
+    form.poll_data = HiddenField()
+
+
+@hookimpl
+def flaskbb_form_post(form: type[ReplyForm]):
+    # Skipping the field entirely when polls are topics-only means a reply
+    # form never has anything to submit or stash - no separate enforcement
+    # needed at save time, and the toolbar button hides itself here the
+    # same way it already does for the quick-reply box (see
+    # flaskbb_tpl_form_new_post_after below).
+    #
+    # form is the *class*, shared and re-patched on every request - if the
+    # setting was off on some earlier request, poll_data is still sitting
+    # in form.__dict__ from that call and has to be explicitly removed, or
+    # toggling the setting on would have no effect until the process
+    # restarts.
+    if _topics_only():
+        if "poll_data" in form.__dict__:
+            delattr(form, "poll_data")
+        return
+    form.poll_data = HiddenField()
+
+
+@hookimpl
+def flaskbb_form_topic_save(form, topic):
+    poll_data = getattr(form, "poll_data", None)
+    post = getattr(topic, "_post", None)
+    if poll_data is not None and post is not None:
+        setattr(post, _PENDING_ATTR, poll_data.data)
+
+
+@hookimpl
+def flaskbb_form_post_save(form, post: Post):
+    poll_data = getattr(form, "poll_data", None)
+    if poll_data is not None:
+        setattr(post, _PENDING_ATTR, poll_data.data)
+
+
+@hookimpl
+def flaskbb_event_post_save_after(post: Post, is_new: bool):
+    if not is_new:
+        return
+
+    raw = getattr(post, _PENDING_ATTR, None)
+    if not raw:
+        return
+
+    payload = parse_poll_payload(raw, max_options=_max_options())
+    if payload is None:
+        return
+
+    create_poll_for_post(post, payload)
+
+
+# --- Rendering ---
+
+
+def _render_existing_poll(post: Post | None):
+    """Renders ``post``'s poll (if it has one) read-only, for display on an
+    edit form - editing a post/topic never touches its poll, only the
+    dedicated delete action does, so this never offers a voting UI.
+    """
+    if post is None:
+        return None
+
+    poll: Poll | None = post.poll  # pyright: ignore[reportAttributeAccessIssue]
+    if poll is None:
+        return None
+
+    user = real(current_user)
+    return render_template(
+        "vote/_poll_widget.html",
+        poll=poll,
+        user_vote_ids=[],
+        can_vote=False,
+        editing=True,
+        can_delete=user.is_authenticated and can_delete_poll(user, poll),
+        form=VoteForm(),
+        delete_form=DeletePollForm(),
+    )
+
+
+@hookimpl
+def flaskbb_tpl_form_new_topic_after(form):
+    if hasattr(form, "poll_data"):
+        return render_template("vote/_form_extra.html", form=form)
+
+    # EditTopicForm - flaskbb_form_topic(form=NewTopicForm) above patches a
+    # sibling class of EditTopicForm (both just subclass TopicForm), so an
+    # EditTopicForm instance never has poll_data. Show its topic's existing
+    # poll read-only instead, since flaskbb_form_topic_save never fires a
+    # poll onto it either.
+    topic = getattr(form, "topic", None)
+    if topic is None:
+        return None
+    return _render_existing_poll(topic.first_post)
+
+
+@hookimpl
+def flaskbb_tpl_form_new_post_after(form):
+    # ReplyForm is shared between NewPost and EditPost (see forum/views.py) -
+    # form.post is only set when editing. A poll attached while editing
+    # would never be created (flaskbb_event_post_save_after only fires for
+    # is_new=True posts), so the create-poll field must not render there -
+    # show the post's existing poll read-only instead.
+    post = getattr(form, "post", None)
+    if post is not None:
+        return _render_existing_poll(post)
+    if hasattr(form, "poll_data"):
+        return render_template("vote/_form_extra.html", form=form)
+    return None
+
+
+@hookimpl
+def flaskbb_tpl_markdown_toolbar_buttons():
+    return render_template("vote/_toolbar_button.html")
+
+
+@hookimpl
+def flaskbb_tpl_markdown_cheatsheet():
+    return render_template("vote/_cheatsheet.html")
+
+
+@hookimpl
+def flaskbb_tpl_scripts():
+    return render_template("vote/_scripts.html")
+
+
+@hookimpl
+def flaskbb_tpl_post_content_before(post: Post):
+    # Post doesn't declare `poll` itself - it's added by Poll.post's backref
+    # in models.py, since Post is a core model this plugin doesn't own.
+    poll: Poll | None = post.poll  # pyright: ignore[reportAttributeAccessIssue]
+    if poll is None:
+        return None
+
+    user = real(current_user)
+    user_vote_ids = poll.option_ids_voted_by(user.id) if user.is_authenticated else []
+    return render_template(
+        "vote/_poll_widget.html",
+        poll=poll,
+        user_vote_ids=user_vote_ids,
+        can_vote=user.is_authenticated,
+        editing=False,
+        can_delete=user.is_authenticated and can_delete_poll(user, poll),
+        form=VoteForm(),
+        delete_form=DeletePollForm(),
+    )

vote/forms.py

@@ -0,0 +1,29 @@
+"""
+vote.forms
+~~~~~~~~~~
+
+Forms used to cast a vote or delete a poll. Their only real job is to
+carry the CSRF token - a vote's option ids are read straight from
+``request.form`` in the view since the set of valid choices is only known
+once the poll is loaded, and depends on whether it's single or multiple
+choice.
+
+:copyright: (c) 2026 by Peter Justin.
+:license: BSD License, see LICENSE for more details.
+"""
+
+from flask_wtf import FlaskForm
+
+
+class VoteForm(FlaskForm):
+    """Used in _poll_widget.html to cast the vote.
+    It just contains the hidden CSRF field
+    """
+
+    pass
+
+
+class DeletePollForm(FlaskForm):
+    """Used in _poll_widget.html to delete a poll.
+    It just contains the hidden CSRF field
+    """

vote/migrations/202607301200_a1f3c9d7e2b4_add_vote_polls.py

@@ -0,0 +1,91 @@
+"""Add vote_polls, vote_poll_options and vote_poll_votes
+
+Revision ID: a1f3c9d7e2b4
+Revises:
+Create Date: 2026-07-30 12:00:00.000000
+
+"""
+
+import flaskbb
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "a1f3c9d7e2b4"
+down_revision = None
+branch_labels = ("vote",)
+depends_on = "8ad96e49dc6"  # flaskbb core init migration - creates posts/users
+
+
+def upgrade():
+    con = op.get_bind()
+
+    if not sa.inspect(con.engine).has_table("vote_polls"):
+        op.create_table(
+            "vote_polls",
+            sa.Column("id", sa.Integer(), nullable=False),
+            sa.Column("post_id", sa.Integer(), nullable=False),
+            sa.Column("question", sa.String(length=255), nullable=False),
+            sa.Column("poll_type", sa.String(length=10), nullable=False),
+            sa.Column(
+                "date_created",
+                flaskbb.utils.database.UTCDateTime(timezone=True),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(
+                ["post_id"],
+                ["posts.id"],
+                name=op.f("fk_vote_polls_post_id_posts"),
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_vote_polls")),
+            sa.UniqueConstraint("post_id", name=op.f("uq_vote_polls_post_id")),
+        )
+
+    if not sa.inspect(con.engine).has_table("vote_poll_options"):
+        op.create_table(
+            "vote_poll_options",
+            sa.Column("id", sa.Integer(), nullable=False),
+            sa.Column("poll_id", sa.Integer(), nullable=False),
+            sa.Column("text", sa.String(length=255), nullable=False),
+            sa.Column("position", sa.Integer(), nullable=False),
+            sa.ForeignKeyConstraint(
+                ["poll_id"],
+                ["vote_polls.id"],
+                name=op.f("fk_vote_poll_options_poll_id_vote_polls"),
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_vote_poll_options")),
+        )
+
+    if not sa.inspect(con.engine).has_table("vote_poll_votes"):
+        op.create_table(
+            "vote_poll_votes",
+            sa.Column("id", sa.Integer(), nullable=False),
+            sa.Column("poll_option_id", sa.Integer(), nullable=False),
+            sa.Column("user_id", sa.Integer(), nullable=False),
+            sa.Column(
+                "date_created",
+                flaskbb.utils.database.UTCDateTime(timezone=True),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(
+                ["poll_option_id"],
+                ["vote_poll_options.id"],
+                name=op.f("fk_vote_poll_votes_poll_option_id_vote_poll_options"),
+                ondelete="CASCADE",
+            ),
+            sa.ForeignKeyConstraint(
+                ["user_id"],
+                ["users.id"],
+                name=op.f("fk_vote_poll_votes_user_id_users"),
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id", name=op.f("pk_vote_poll_votes")),
+        )
+
+
+def downgrade():
+    op.drop_table("vote_poll_votes")
+    op.drop_table("vote_poll_options")
+    op.drop_table("vote_polls")

vote/models.py

@@ -0,0 +1,115 @@
+"""
+vote.models
+~~~~~~~~~~~
+
+The models for polls, their options and votes.
+
+:copyright: (c) 2026 by Peter Justin.
+:license: BSD License, see LICENSE for more details.
+"""
+
+import datetime
+import logging
+
+from flaskbb.extensions import db
+from flaskbb.forum.models import Post
+from flaskbb.utils.database import CRUDMixin, UTCDateTime
+from flaskbb.utils.helpers import time_utcnow
+from sqlalchemy import ForeignKey, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+logger = logging.getLogger(__name__)
+
+SINGLE_CHOICE = "single"
+MULTIPLE_CHOICE = "multiple"
+POLL_TYPES = (SINGLE_CHOICE, MULTIPLE_CHOICE)
+
+
+class Poll(db.Model, CRUDMixin):
+    __tablename__ = "vote_polls"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    post_id: Mapped[int] = mapped_column(
+        ForeignKey("posts.id", ondelete="CASCADE"),
+        unique=True,
+        nullable=False,
+    )
+    question: Mapped[str] = mapped_column(String(255), nullable=False)
+    poll_type: Mapped[str] = mapped_column(String(10), nullable=False)
+    date_created: Mapped[datetime.datetime] = mapped_column(
+        UTCDateTime(timezone=True), default=time_utcnow, nullable=False
+    )
+
+    # ``single_parent`` is required by SQLAlchemy for a delete-orphan cascade
+    # on a one-to-one backref. Declared here (not on Post) since Post is a
+    # core model this plugin doesn't own - see docs/development/plugin/editor.rst
+    # in flaskbb for why plugins extend core models this way instead of
+    # patching flaskbb.forum.models.
+    post: Mapped["Post"] = relationship(
+        "Post",
+        backref=db.backref(
+            "poll", uselist=False, cascade="all, delete-orphan", single_parent=True
+        ),
+    )
+
+    options: Mapped[list["PollOption"]] = relationship(
+        "PollOption",
+        back_populates="poll",
+        cascade="all, delete-orphan",
+        order_by="PollOption.position",
+    )
+
+    @property
+    def is_multiple_choice(self) -> bool:
+        return self.poll_type == MULTIPLE_CHOICE
+
+    @property
+    def total_votes(self) -> int:
+        return sum(option.vote_count for option in self.options)
+
+    def option_ids_voted_by(self, user_id: int) -> list[int]:
+        """Returns the ids of the options ``user_id`` has voted for."""
+        option_ids = [option.id for option in self.options]
+        if not option_ids:
+            return []
+        votes = PollVote.get_all(
+            PollVote.user_id == user_id, PollVote.poll_option_id.in_(option_ids)
+        )
+        return [vote.poll_option_id for vote in votes]
+
+
+class PollOption(db.Model, CRUDMixin):
+    __tablename__ = "vote_poll_options"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    poll_id: Mapped[int] = mapped_column(
+        ForeignKey("vote_polls.id", ondelete="CASCADE"), nullable=False
+    )
+    text: Mapped[str] = mapped_column(String(255), nullable=False)
+    position: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    poll: Mapped["Poll"] = relationship("Poll", back_populates="options")
+    votes: Mapped[list["PollVote"]] = relationship(
+        "PollVote", back_populates="option", cascade="all, delete-orphan"
+    )
+
+    @property
+    def vote_count(self) -> int:
+        return PollVote.count(PollVote.poll_option_id == self.id)
+
+
+class PollVote(db.Model, CRUDMixin):
+    __tablename__ = "vote_poll_votes"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    poll_option_id: Mapped[int] = mapped_column(
+        ForeignKey("vote_poll_options.id", ondelete="CASCADE"), nullable=False
+    )
+    user_id: Mapped[int] = mapped_column(
+        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    date_created: Mapped[datetime.datetime] = mapped_column(
+        UTCDateTime(timezone=True), default=time_utcnow, nullable=False
+    )
+
+    option: Mapped["PollOption"] = relationship("PollOption", back_populates="votes")

vote/static/vote.js

@@ -0,0 +1,161 @@
+(function () {
+  "use strict";
+
+  function optionRow(value) {
+    const row = document.createElement("div");
+    row.className = "input-group input-group-sm mb-2";
+
+    const input = document.createElement("input");
+    input.type = "text";
+    input.className = "form-control vote-poll-option-input";
+    input.maxLength = 255;
+    input.value = value || "";
+
+    const removeBtn = document.createElement("button");
+    removeBtn.type = "button";
+    removeBtn.className = "btn btn-white";
+    removeBtn.innerHTML = '<span class="fas fa-xmark"></span>';
+    removeBtn.addEventListener("click", () => row.remove());
+
+    row.append(input, removeBtn);
+    return row;
+  }
+
+  function setupPollDialog() {
+    const dialog = document.getElementById("vote-poll-dialog");
+    if (!dialog) {
+      return;
+    }
+
+    const questionInput = document.getElementById("vote-poll-question");
+    const typeSingle = document.getElementById("vote-poll-type-single");
+    const typeMultiple = document.getElementById("vote-poll-type-multiple");
+    const optionsContainer = document.getElementById("vote-poll-options");
+    const addOptionBtn = document.getElementById("vote-poll-add-option");
+    const insertBtn = document.getElementById("vote-poll-insert");
+    const removeBtn = document.getElementById("vote-poll-remove");
+    const cancelBtn = document.getElementById("vote-poll-cancel");
+    const closeBtn = document.getElementById("vote-poll-close");
+
+    let activeField = null;
+
+    function addOptionRow(value) {
+      optionsContainer.append(optionRow(value));
+    }
+
+    function notifyFieldChanged() {
+      activeField.dispatchEvent(new CustomEvent("change", { bubbles: true }));
+    }
+
+    // Exposed on the dialog element itself so <vote-poll-button> instances
+    // don't need to know the dialog's internal field/option-row wiring.
+    dialog.openForField = function (field) {
+      activeField = field;
+
+      let payload = null;
+      if (field.value) {
+        try {
+          payload = JSON.parse(field.value);
+        } catch (error) {
+          payload = null;
+        }
+      }
+
+      questionInput.value = payload ? payload.question || "" : "";
+      typeMultiple.checked = Boolean(payload) && payload.type === "multiple";
+      typeSingle.checked = !typeMultiple.checked;
+
+      optionsContainer.innerHTML = "";
+      const options =
+        payload && Array.isArray(payload.options) ? payload.options : [];
+      for (const option of options) {
+        addOptionRow(option);
+      }
+      while (optionsContainer.children.length < 2) {
+        addOptionRow("");
+      }
+
+      removeBtn.hidden = !payload;
+      dialog.showModal();
+    };
+
+    addOptionBtn.addEventListener("click", () => addOptionRow(""));
+
+    insertBtn.addEventListener("click", () => {
+      const question = questionInput.value.trim();
+      const options = [
+        ...optionsContainer.querySelectorAll(".vote-poll-option-input"),
+      ]
+        .map((input) => input.value.trim())
+        .filter((value) => value.length > 0);
+
+      if (!question || options.length < 2) {
+        window.alert(dialog.dataset.validationMessage);
+        return;
+      }
+
+      activeField.value = JSON.stringify({
+        question,
+        type: typeMultiple.checked ? "multiple" : "single",
+        options,
+      });
+      notifyFieldChanged();
+      dialog.close();
+    });
+
+    removeBtn.addEventListener("click", () => {
+      activeField.value = "";
+      notifyFieldChanged();
+      dialog.close();
+    });
+
+    cancelBtn.addEventListener("click", () => dialog.close());
+    closeBtn.addEventListener("click", () => dialog.close());
+  }
+
+  setupPollDialog();
+
+  class VotePollButtonElement extends window.MarkdownButtonElement {
+    connectedCallback() {
+      super.connectedCallback();
+
+      const form = this.closest("form");
+      // form.elements.namedItem returns a single element normally, but a
+      // RadioNodeList if the form ever has more than one field with this
+      // name (no addEventListener) - treat that as "not found" too rather
+      // than throwing.
+      const field = form ? form.elements.namedItem("poll_data") : null;
+      this.hiddenField = field instanceof HTMLInputElement ? field : null;
+      const dialog = document.getElementById("vote-poll-dialog");
+
+      // Missing either one means this editor instance has no wired-up poll
+      // support (e.g. the quick-reply box, which has no dialog, or editing
+      // an existing post) - hide rather than offer a button that can't do
+      // anything.
+      if (!this.hiddenField || !dialog) {
+        this.hidden = true;
+        return;
+      }
+
+      this.refreshActiveState();
+      this.hiddenField.addEventListener("change", () =>
+        this.refreshActiveState()
+      );
+
+      this.addEventListener("click", (event) => {
+        event.preventDefault();
+        if (dialog.openForField) {
+          dialog.openForField(this.hiddenField);
+        }
+      });
+    }
+
+    refreshActiveState() {
+      this.classList.toggle("active", Boolean(this.hiddenField.value));
+    }
+  }
+
+  if (!window.customElements.get("vote-poll-button")) {
+    window.customElements.define("vote-poll-button", VotePollButtonElement);
+  }
+})();

vote/templates/vote/_cheatsheet.html

@@ -0,0 +1,4 @@
+<h2>{{ _("Polls") }}</h2>
+<p class="text-center">
+    {{ _("Click the poll button in the toolbar to attach a single- or multiple-choice poll to your post.") }}
+</p>

vote/templates/vote/_form_extra.html

@@ -0,0 +1,41 @@
+<!-- poll_data itself is already rendered by this page's form.hidden_tag() call,
+     since it's a HiddenField - only the supporting dialog belongs here. -->
+<dialog id="vote-poll-dialog" class="border-0 rounded p-3"
+        style="width: 500px; max-width: 90vw; position: fixed; top: 50%; left: 50%; transform: translate(-50%, -50%); margin: 0;"
+        data-validation-message="{{ _('A poll needs a question and at least two options.') }}">
+    <div class="modal-content">
+        <div class="modal-header">
+            <h5 class="modal-title">{{ _("Insert Poll") }}</h5>
+            <button type="button" class="btn-close" id="vote-poll-close" aria-label="{{ _('Close') }}"></button>
+        </div>
+        <div class="modal-body">
+            <div class="mb-3">
+                <label class="form-label" for="vote-poll-question">{{ _("Question") }}</label>
+                <input type="text" class="form-control" id="vote-poll-question" maxlength="255">
+            </div>
+            <div class="mb-3">
+                <label class="form-label">{{ _("Choice type") }}</label>
+                <div class="form-check">
+                    <input class="form-check-input" type="radio" name="vote-poll-type" id="vote-poll-type-single" checked>
+                    <label class="form-check-label" for="vote-poll-type-single">{{ _("Single choice") }}</label>
+                </div>
+                <div class="form-check">
+                    <input class="form-check-input" type="radio" name="vote-poll-type" id="vote-poll-type-multiple">
+                    <label class="form-check-label" for="vote-poll-type-multiple">{{ _("Multiple choice") }}</label>
+                </div>
+            </div>
+            <div class="mb-3">
+                <label class="form-label">{{ _("Options") }}</label>
+                <div id="vote-poll-options"></div>
+                <button type="button" class="btn btn-sm btn-white mt-1" id="vote-poll-add-option">
+                    <span class="fas fa-plus"></span> {{ _("Add option") }}
+                </button>
+            </div>
+        </div>
+        <div class="modal-footer">
+            <button type="button" class="btn btn-white me-auto" id="vote-poll-remove" hidden>{{ _("Remove poll") }}</button>
+            <button type="button" class="btn btn-white me-1" id="vote-poll-cancel">{{ _("Cancel") }}</button>
+            <button type="button" class="btn btn-primary" id="vote-poll-insert">{{ _("Insert") }}</button>
+        </div>
+    </div>
+</dialog>

vote/templates/vote/_poll_widget.html

@@ -0,0 +1,56 @@
+<div class="mb-3 col-12">
+    <div class="card my-2 vote-poll">
+        <div class="card-body">
+            <h6 class="card-title">{{ poll.question }}</h6>
+
+            {% if can_vote and not editing and not user_vote_ids %}
+            <form method="post" action="{{ url_for('vote.cast_vote', poll_id=poll.id) }}">
+                {{ form.hidden_tag() }}
+                {% for option in poll.options %}
+                <div class="form-check">
+                    <input class="form-check-input" type="{{ 'checkbox' if poll.is_multiple_choice else 'radio' }}"
+                           name="option_id" value="{{ option.id }}" id="vote-poll-{{ poll.id }}-option-{{ option.id }}">
+                    <label class="form-check-label" for="vote-poll-{{ poll.id }}-option-{{ option.id }}">
+                        {{ option.text }}
+                    </label>
+                </div>
+                {% endfor %}
+                <button type="submit" class="btn btn-sm btn-primary mt-2">{{ _("Vote") }}</button>
+            </form>
+            {% else %}
+            <ul class="list-unstyled mb-1">
+                {% for option in poll.options %}
+                {% set percentage = (100 * option.vote_count / poll.total_votes) if poll.total_votes else 0 %}
+                <li class="mb-1 {{ 'fw-bold' if option.id in user_vote_ids }}">
+                    <div class="d-flex justify-content-between">
+                        <span>{{ option.text }}</span>
+                        <span>{{ "%.0f"|format(percentage) }}% ({{ option.vote_count }})</span>
+                    </div>
+                    <div class="progress" style="height: 4px;">
+                        <div class="progress-bar" role="progressbar" style="width: {{ percentage }}%"></div>
+                    </div>
+                </li>
+                {% endfor %}
+            </ul>
+            <small class="text-muted">
+                {% if editing %}
+                {{ _("This poll cannot be changed here.") }}
+                {% else %}
+                {{ _("%(count)s total votes", count=poll.total_votes) }}
+                {% if not can_vote %} &middot; {{ _("Log in to vote.") }}{% endif %}
+                {% endif %}
+            </small>
+            {% endif %}
+
+            {% if can_delete %}
+            <form method="post" action="{{ url_for('vote.delete_poll', poll_id=poll.id) }}" class="mt-2">
+                {{ delete_form.hidden_tag() }}
+                <button type="button" class="btn btn-sm btn-outline-danger" data-bs-toggle="modal" data-bs-target="#confirmModal"
+                        data-tooltip="tooltip" title="{{ _('Delete this poll') }}">
+                    <span class="fas fa-trash fa-fw"></span> {{ _("Delete Poll") }}
+                </button>
+            </form>
+            {% endif %}
+        </div>
+    </div>
+</div>

vote/templates/vote/_scripts.html

@@ -0,0 +1 @@
+<script src="{{ url_for('vote.static', filename='vote.js') }}"></script>

vote/templates/vote/_toolbar_button.html

@@ -0,0 +1,5 @@
+<div class="btn-group btn-group-sm me-2">
+    <vote-poll-button class="btn btn-white" data-tooltip="tooltip" title="{{ _('Insert Poll') }}">
+        <span class="fas fa-square-poll-vertical"></span>
+    </vote-poll-button>
+</div>

vote/utils.py

@@ -0,0 +1,159 @@
+"""
+vote.utils
+~~~~~~~~~~
+
+Helpers for parsing and validating polls and for creating polls.
+
+:copyright: (c) 2026 by Peter Justin.
+:license: BSD License, see LICENSE for more details.
+"""
+
+import json
+import logging
+from dataclasses import dataclass
+
+from flask_allows2 import And, Or, Permission
+from flaskbb.extensions import db
+from flaskbb.forum.models import Forum, Post
+from flaskbb.user.models import User
+from flaskbb.utils.requirements import Has, IsAtleastSuperModerator, IsModeratorInForum
+
+from .models import MULTIPLE_CHOICE, POLL_TYPES, Poll, PollOption, PollVote
+
+logger = logging.getLogger(__name__)
+
+MIN_OPTIONS = 2
+QUESTION_MAX_LENGTH = 255
+OPTION_MAX_LENGTH = 255
+
+
+@dataclass(frozen=True)
+class PollPayload:
+    question: str
+    poll_type: str
+    options: tuple[str, ...]
+
+
+def parse_poll_payload(raw: str | None, max_options: int) -> PollPayload | None:
+    """Parses and validates the JSON poll payload submitted alongside a post.
+
+    Returns ``None`` if ``raw`` is empty or fails validation - callers treat
+    that the same as "no poll was attached", since the field is optional and
+    a malformed payload (a tampered request, most likely) shouldn't block
+    the post/topic it rode in on from being created.
+    """
+    if not raw:
+        return None
+
+    try:
+        data = json.loads(raw)
+    except ValueError:
+        logger.info("Discarding poll payload: invalid JSON")
+        return None
+
+    if not isinstance(data, dict):
+        return None
+
+    question = data.get("question")
+    poll_type = data.get("type")
+    options = data.get("options")
+
+    if not isinstance(question, str) or not isinstance(poll_type, str):
+        return None
+
+    question = question.strip()
+    if not question or len(question) > QUESTION_MAX_LENGTH:
+        return None
+
+    if poll_type not in POLL_TYPES:
+        return None
+
+    if not isinstance(options, list):
+        return None
+
+    cleaned_options: list[str] = []
+    for option in options:
+        if not isinstance(option, str):
+            return None
+        option = option.strip()
+        if not option:
+            continue
+        if len(option) > OPTION_MAX_LENGTH:
+            return None
+        cleaned_options.append(option)
+
+    if not (MIN_OPTIONS <= len(cleaned_options) <= max_options):
+        return None
+
+    return PollPayload(
+        question=question, poll_type=poll_type, options=tuple(cleaned_options)
+    )
+
+
+def create_poll_for_post(post: Post, payload: PollPayload) -> Poll:
+    """Creates a poll and its options for ``post`` in a single transaction."""
+    poll = Poll(post_id=post.id, question=payload.question, poll_type=payload.poll_type)
+    db.session.add(poll)
+    db.session.flush()
+
+    for position, text in enumerate(payload.options):
+        db.session.add(PollOption(poll_id=poll.id, text=text, position=position))
+
+    db.session.commit()
+    return poll
+
+
+def can_access_poll(user: User, poll: Poll) -> bool:
+    """Mirrors ``CanAccessForum.fulfill`` for a forum reached via a poll,
+    rather than via the current request's URL - the vote endpoint has no
+    ``current_forum`` to check against.
+    """
+    forum: Forum = poll.post.topic.forum
+    forum_group_ids = {group.id for group in forum.groups}
+    user_group_ids = {group.id for group in user.groups}
+    return bool(forum_group_ids & user_group_ids)
+
+
+def cast_vote(poll: Poll, user: User, option_ids: list[int]) -> None:
+    """Replaces ``user``'s vote(s) in ``poll`` with ``option_ids``.
+
+    Callers are expected to have already validated that every id in
+    ``option_ids`` belongs to ``poll``, and that ``option_ids`` has exactly
+    one entry for a single-choice poll.
+    """
+    valid_option_ids = {option.id for option in poll.options}
+    existing = PollVote.get_all(
+        PollVote.user_id == user.id, PollVote.poll_option_id.in_(valid_option_ids)
+    )
+    for vote in existing:
+        db.session.delete(vote)
+
+    for option_id in option_ids:
+        db.session.add(PollVote(poll_option_id=option_id, user_id=user.id))
+
+    db.session.commit()
+
+
+def can_delete_poll(user: User, poll: Poll) -> bool:
+    """Mirrors flaskbb's staff branches of ``CanDeletePost`` - only an
+    admin, a super moderator, or a moderator of the poll's forum with the
+    ``editpost`` permission may delete a poll. Unlike editing/deleting a
+    post, the poster themselves is never allowed to delete their own poll.
+    """
+    forum = poll.post.topic.forum
+    requirement = Or(
+        IsAtleastSuperModerator,
+        And(IsModeratorInForum(forum=forum), Has("editpost")),
+    )
+    return bool(Permission(requirement, identity=user))
+
+
+def poll_type_is_valid_for(poll: Poll, option_ids: list[int]) -> bool:
+    valid_option_ids = {option.id for option in poll.options}
+    if not option_ids:
+        return False
+    if not set(option_ids) <= valid_option_ids:
+        return False
+    if poll.poll_type != MULTIPLE_CHOICE and len(option_ids) > 1:
+        return False
+    return True

vote/views.py

@@ -0,0 +1,86 @@
+"""
+vote.views
+~~~~~~~~~~
+
+The views for casting a vote in a poll and for deleting one.
+
+:copyright: (c) 2026 by Peter Justin.
+:license: BSD License, see LICENSE for more details.
+"""
+
+import logging
+
+from flask import Blueprint, abort, flash, redirect, request
+from flask.views import MethodView
+from flask_babelplus import gettext as _
+from flask_login import current_user, login_required
+from flaskbb.utils.helpers import real, register_view
+
+from .forms import DeletePollForm, VoteForm
+from .models import Poll
+from .utils import can_access_poll, can_delete_poll, cast_vote, poll_type_is_valid_for
+
+logger = logging.getLogger(__name__)
+
+vote_bp = Blueprint(
+    "vote", __name__, template_folder="templates", static_folder="static"
+)
+
+
+class CastVote(MethodView):
+    decorators = [login_required]
+
+    def post(self, poll_id: int):
+        poll = Poll.get_or_404(Poll.id == poll_id)
+        user = real(current_user)
+
+        if not can_access_poll(user, poll):
+            abort(404)
+
+        form = VoteForm()
+        if not form.validate_on_submit():
+            flash(_("Could not verify the vote request, please try again."), "danger")
+            return redirect(poll.post.url)
+
+        option_ids = [int(v) for v in request.form.getlist("option_id") if v.isdigit()]
+
+        if not poll_type_is_valid_for(poll, option_ids):
+            flash(_("That is not a valid choice for this poll."), "danger")
+            return redirect(poll.post.url)
+
+        cast_vote(poll, user, option_ids)
+        flash(_("Your vote has been recorded."), "success")
+        return redirect(poll.post.url)
+
+
+class DeletePoll(MethodView):
+    decorators = [login_required]
+
+    def post(self, poll_id: int):
+        poll = Poll.get_or_404(Poll.id == poll_id)
+        user = real(current_user)
+
+        if not can_delete_poll(user, poll):
+            abort(404)
+
+        form = DeletePollForm()
+        if not form.validate_on_submit():
+            flash(_("Could not verify the delete request, please try again."), "danger")
+            return redirect(poll.post.url)
+
+        post_url = poll.post.url
+        poll.delete()
+        flash(_("The poll has been deleted."), "success")
+        return redirect(post_url)
+
+
+register_view(
+    vote_bp,
+    routes=["/<int:poll_id>/vote"],
+    view_func=CastVote.as_view("cast_vote"),
+)
+register_view(
+    vote_bp,
+    routes=["/<int:poll_id>/delete"],
+    view_func=DeletePoll.as_view("delete_poll"),
+)