=== Quillvote - Poll Block ===
Contributors: maksymkotenko
Tags: poll, polls, voting, survey, block
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A poll block with live results. Votes stay in your own database: no account, no external service, and it works with page caching.

== Description ==

Quillvote adds a **Quillvote Poll** block to the block editor. Type the question and the answers right in your post, publish, and visitors vote without leaving the page. Results appear as bars with percentages the moment they vote.

There is nothing to sign up for. Every vote is stored in your own WordPress database, and no data is sent to a third party.

= Features =

* **Inline editing** - write the question and answers in the post, press Enter for the next answer, reorder or remove answers with one click.
* **Live results** - bars, percentages and vote counts right after voting, with the visitor's own choice marked.
* **Single or multiple choice** - optionally limit how many answers one visitor may pick.
* **Repeat-vote protection** - one vote per browser by default, one vote per browser and network for stricter polls, or unlimited votes.
* **Results when you want them** - after voting, any time with a "View results" link, only after the poll closes, or never.
* **Close a poll** - manually, or automatically at a date and time in your site's timezone.
* **Results in the editor** - see the counts and reset the votes in the block sidebar.
* **Works with page caching** - the page itself carries no expiring tokens, so cached pages and CDNs keep accepting votes.
* **Light** - one 3 KB (gzipped) script without jQuery or other libraries, loaded only on pages that contain a poll.
* **Fits your theme** - inherits your fonts and colors and supports the block color, typography and spacing settings.
* **Accessible** - native radio buttons and checkboxes in a labelled group, keyboard friendly, status messages announced to screen readers.

= Privacy =

Quillvote stores the chosen answers together with a keyed one-way hash of a random identifier that the visitor's browser keeps in local storage; the hash is different in every poll, so ballots in different polls cannot be linked. For polls set to "One vote per browser and network" it also stores a keyed hash of the visitor's IP address for that poll. To stop vote flooding, a hash of the IP address is kept for up to two minutes. IP addresses themselves are never stored. Quillvote sets no cookies and loads nothing from other sites. A suggested paragraph for your privacy policy is added under Settings > Privacy; depending on your jurisdiction, local storage may need the same consent as cookies.

= For developers =

* `quillvote_can_vote` filter - return a `WP_Error` to refuse a vote, for example once a poll has reached a quota. Votes are sent without login cookies, so the current user is always a visitor here.
* `quillvote_vote_recorded` action - runs after a vote is stored.
* `quillvote_client_ip` filter - the visitor address used for network protection, for sites behind a trusted proxy.
* `quillvote_votes_per_minute` filter - how many votes one network may cast per minute across all polls (default 120, 0 turns the limit off).

== Installation ==

1. Install Quillvote from Plugins > Add New, or upload the plugin folder to `/wp-content/plugins/`, and activate it.
2. Add the Quillvote Poll block (search for "poll" in the block inserter), type your question and answers.
3. Choose the voting and results settings in the block sidebar and publish.

== Frequently Asked Questions ==

= Do I need an account or an API key? =

No. Quillvote works on its own and keeps the votes in your WordPress database.

= Where are the votes stored? =

In the `{prefix}quillvote_votes` table of your site's database, one row per vote. Deleting the plugin from the Plugins screen removes the table.

= Does it work with caching plugins and CDNs? =

Yes. The poll loads its current state from the WordPress REST API after the page loads, and votes are sent the same way without a nonce, so cached pages keep working. When you change or close a poll, a visitor who still sees an older cached copy of the page is asked to reload it before voting. Your site must not block the REST API for visitors.

= How does it stop people from voting twice? =

By default each browser can vote once. With "One vote per browser and network", a second vote from the same network is refused as well, which also stops someone who clears their browser data. People who share a network, such as an office or a school, can then vote only once between them, so use this setting for polls where that is acceptable.

= My site is behind Cloudflare or another proxy. What should I know? =

Behind a proxy every visitor can arrive from the proxy's address. Unless your host restores the real visitor address, "One vote per browser and network" would treat all visitors as one network. Either keep the default "One vote per browser", or, if your site can only be reached through the proxy, tell Quillvote which header carries the visitor address:

`add_filter( 'quillvote_client_ip', function ( $ip ) { return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) : $ip; } );`

= Can I show the same poll on several pages? =

Yes. Put the poll into a synced pattern and insert the pattern wherever you need it; every copy counts toward the same results. A poll block that you copy and paste also shares its votes with the original until you click "Use a new ID" in the block's Poll ID panel.

= Can I reset the votes? =

Yes. Select the poll in the editor and click "Reset votes" in the Results panel of the sidebar. Editors can reset any poll; authors can reset a poll that appears only in their own posts.

= Does it work without JavaScript? =

Voting needs JavaScript. Without it the poll shows the question and answers.

== Screenshots ==

1. Results after voting, with the visitor's own choice marked.
2. Editing a poll: question and answers inline, settings and live results in the sidebar.
3. A multiple-choice poll before voting.

== Changelog ==

= 0.1.0 =
* First release: poll block with single and multiple choice, live results, repeat-vote protection, results visibility, closing date, results and reset in the editor.
