PHPackages                             soderlind/content-poll - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. soderlind/content-poll

ActiveWordpress-plugin[Utility & Helpers](/categories/utility)

soderlind/content-poll
======================

ContentPoll AI – AI-assisted contextual polls (2–6 options) for engaging readers directly on content pages.

0.10.0(4mo ago)2448↑50%[6 PRs](https://github.com/soderlind/content-poll/pulls)GPL-2.0-or-laterPHPPHP ^8.3CI passing

Since Nov 13Pushed 3mo agoCompare

[ Source](https://github.com/soderlind/content-poll)[ Packagist](https://packagist.org/packages/soderlind/content-poll)[ Fund](https://paypal.me/PerSoderlind)[ RSS](/packages/soderlind-content-poll/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (4)Versions (40)Used By (0)

ContentPoll AI
==============

[](#contentpoll-ai)

**A modern, accessible polling block that lets visitors vote on questions about your content, with beautiful card-style options and optional AI suggestions.**

Engage your audience by asking them to vote on aspects of the page they're reading. AI analyzes your content and suggests relevant polling questions, or create your own. Visitors vote once anonymously, then see real-time results with visual progress bars.

**Perfect for**: Blog posts, product pages, documentation, news articles, tutorials, reviews – any content where you want to gauge reader opinions or preferences.

     content-poll-edit.mp4

[![Image](.screenshots/content-vote-settings.png)](.screenshots/content-vote-settings.png)[![Image](.screenshots/content-vote-edit.png)](.screenshots/content-vote-edit.png)[![Image](.screenshots/content-poll.png)](.screenshots/content-poll.png)[![Image](.screenshots/content-poll-analytics-single.png)](.screenshots/content-poll-analytics-single.png)

[Features](#-features) | [Installation](#-installation) | [Usage](#-usage) | [Design Features](#-design-features) | [Development](#-development) | [Privacy & Security](#-privacy--security) | [REST API](#-rest-api) | [Roadmap](#-roadmap)

✨ Features
----------

[](#-features)

### Core Voting

[](#core-voting)

- **Card-Style Interface**: Modern, clickable option cards with radio button indicators (no traditional buttons)
- **Ordered Options**: Automatic A, B, C, D labeling for clarity
- **Anonymous & Secure**: Cookie-based deduplication with SHA-256 hashing
- **One Vote Per Visitor**: Secure token prevents duplicate voting
- **Visual Results**: Progress bars with percentages and vote counts
- **Theme Adaptive**: Automatically matches your WordPress theme colors
- **Persistent Selection**: Returning voters see their previously selected option checked

### AI-Powered Suggestions (7 Providers)

[](#ai-powered-suggestions-7-providers)

AI reads your page content and generates contextually relevant poll questions:

- **Heuristic** (Default) - Built-in keyword extraction from your content, no API required. Use it for tests and basic suggestions.
- **OpenAI** - GPT models analyze your content using a multi-step PocketFlow pipeline (topics → poll draft → validation) for structured, topic-aware questions and options.
- **Azure OpenAI** - Enterprise Azure OpenAI Service using the same PocketFlow multi-step flow as OpenAI.
- **Anthropic Claude** - Claude 3.5 Sonnet analyzes content context
- **Google Gemini** - Gemini 1.5 Flash (free tier available)
- **Ollama** - Self-hosted local models process content privately
- **Grok (xAI)** - Real‑time reasoning model from xAI; concise, context-aware poll suggestions

**Example**: On a blog post about photography tips, AI might suggest: "Which photography technique interests you most?" with options like "Composition", "Lighting", "Editing", "Equipment".

### Admin Features

[](#admin-features)

- **Settings Page**: Configure AI provider, API keys, and models at Settings → ContentPoll AI
- **Flexible Options**: Choose 2-6 voting options per block
- **Lock on First Vote**: Options become immutable after the first vote to preserve data integrity
- **Debug Mode**: Test reset functionality when WP\_DEBUG is enabled
- **Model Validation**: Real-time API testing when saving AI settings

### Developer-Friendly

[](#developer-friendly)

- **REST API**: Complete endpoints for voting, results, and suggestions
- **Modern Stack**: Built with @wordpress/scripts, React hooks, and webpack
- **CSP Compliant**: No inline scripts, data attributes for i18n
- **Accessibility**: ARIA labels, keyboard navigation, semantic HTML
- **Internationalization**: Translation-ready with `.pot` file

📦 Installation
--------------

[](#-installation)

### Quick Install

[](#quick-install)

1. Download [`content-poll.zip`](https://github.com/soderlind/content-poll/releases/latest/download/content-poll.zip)
2. Upload via `Plugins → Add New → Upload Plugin`
3. Activate via `WordPress Admin → Plugins`

**Configuration (Optional)**

1. Go to `Settings → ContentPoll AI`
2. Choose an AI provider for suggestions
3. Enter your API key or endpoint details
4. Click Save Settings (plugin tests API connection automatically)

See [AI Provider Integration Guide](https://github.com/soderlind/content-poll/blob/main/docs/AI-PROVIDERS.md) for detailed setup instructions for each AI provider.

**Environment Variables / Constants**

For deployment automation (Docker, CI/CD), configure AI settings via environment variables or `wp-config.php` constants:

```
// wp-config.php
define( 'CONTENT_POLL_AI_PROVIDER', 'openai' );
define( 'CONTENT_POLL_OPENAI_KEY', 'sk-your-api-key' );
```

```
# Environment variables
export CONTENT_POLL_AI_PROVIDER=openai
export CONTENT_POLL_OPENAI_KEY=sk-your-api-key
```

See the [AI Provider Integration Guide](./docs/AI-PROVIDERS.md#environment-variables--constants) for the full list of configuration variables.

**Updates**

- Plugin [updates are handled automatically](https://github.com/soderlind/wordpress-plugin-github-updater#readme) via GitHub. No need to manually download and install updates.

### Development Install

[](#development-install)

```
# Install via Composer
composer require soderlind/content-poll
# Install dependencies
composer install
npm install

# Build assets
npm run build

# Or watch for changes
npm run start
```

🚀 Usage
-------

[](#-usage)

### Basic Usage

[](#basic-usage)

1. **Add Block**: In the editor, insert the "ContentPoll AI" block (display name may appear as ContentPoll) into your post/page
2. **Set Question**: Enter a question about your content (or use AI to generate one)
3. **Configure Options**: Add 2-6 answer options related to your content
4. **Publish**: Visitors reading that page can now vote on your question and see results

### AI Suggestions (Content-Aware)

[](#ai-suggestions-content-aware)

1. Go to **Settings → ContentPoll AI**
2. Select an AI provider (OpenAI, Anthropic, Gemini, Ollama, Grok, or Azure)
3. Enter your API key/endpoint
4. **Write your post content first** (AI needs content to analyze)
5. Add the ContentPoll AI block
6. Click **Generate Suggestions** - AI reads the page content and suggests a relevant question
7. Review and adjust the AI-generated question and options

### Results Display

[](#results-display)

After voting, visitors see:

- Their selected option marked with a checkmark
- Vote counts for each option (e.g., "3 votes")
- Visual progress bars showing percentages
- Clean card layout with A, B, C, D labels

🎨 Design Features
-----------------

[](#-design-features)

- **No Buttons**: Uses semantic `` elements styled as interactive cards
- **Radio Indicators**: Visual radio button circles that fill when selected
- **Hover Effects**: Cards lift and shadow on hover with smooth transitions
- **Pointer Cursor**: Clear visual feedback that options are clickable
- **Theme Colors**: Uses WordPress CSS custom properties (`--wp--preset--color--*`)
- **Responsive**: Works beautifully on all screen sizes
- **Box Sizing**: Proper containment prevents overflow issues

### CSS Customization

[](#css-customization)

You can fully restyle the poll via standard CSS. The front‑end markup exposes predictable class names and leverages WordPress design tokens (`--wp--preset--color--*`) plus a custom radius variable (`--wp--custom--border--radius`). Override these in your theme or a custom stylesheet.

Key wrapper & structural classes:

- `.content-poll` – Outer container (padding, border, background, overall radius)
- `.content-poll__question` – Question text
- `.content-poll__options` – List wrapper for interactive options
- `.content-poll__option` – Individual clickable card
- `.content-poll__radio` – Circular selection indicator within each option
- `.content-poll__label` – Option text span inside the card
- `.content-poll__message` – Post‑vote message container
- `.content-poll__results` – Wrapper for results view
- `.content-poll__result-item` – Individual result card
- `.content-poll__result-label` – Flex row containing option label + percentage
- `.content-poll__result-count` – Percentage text (now showing % after changes)
- `.content-poll__result-bar` / `.content-poll__result-fill` – Progress bar track & fill (gradient)
- `.content-poll__results-total` – Total votes summary element (appended dynamically)
- State class: `.content-poll--results-only` – Hides interactive option list after voting

Useful CSS variables (fallbacks shown in code):

- `--wp--preset--color--primary`
- `--wp--preset--color--secondary`
- `--wp--preset--color--contrast`
- `--wp--preset--color--base`
- `--wp--custom--border--radius`

#### Quick Examples

[](#quick-examples)

Rounded cards & softer shadow:

```
.content-poll__option {
  border-radius: 16px;
  box-shadow: 0 4px 20px rgba(0,0,0,0.08);
}
```

Custom gradient for result bar:

```
.content-poll__result-fill {
  background: linear-gradient(90deg,#667eea,#764ba2);
}
```

Larger percentage emphasis:

```
.content-poll__result-count {
  font-size: 0.95em;
  font-weight: 600;
  opacity: 1;
}
```

Change option hover behavior:

```
.content-poll__option:hover {
  transform: scale(1.01);
  box-shadow: 0 6px 18px rgba(0,0,0,0.12);
}
```

Adjust overall corner radius globally:

```
.content-poll {
  --wp--custom--border--radius: 12px;
}
```

Minimal flat style:

```
.content-poll__option {
  box-shadow: none;
  border: 1px solid #e0e0e0;
}
.content-poll__option:hover {
  transform: none;
  box-shadow: none;
  background: #f9f9f9;
}
```

Hide total votes (if you prefer only percentages):

```
.content-poll__results-total { display: none; }
```

#### Accessibility Notes

[](#accessibility-notes)

- Percentages are rendered with an `aria-label` containing both the raw vote count and percentage for screen readers.
- Preserve contrast when changing gradients or text colors.

#### Best Practices

[](#best-practices)

- Prefer overriding variables for broad changes (theme color alignment).
- Keep hover/active transitions <= 0.25s for responsiveness.
- Maintain readable touch targets: keep option padding ≥ 0.75em.
- Test focus outlines after customizations to retain keyboard accessibility.

🔧 Development
-------------

[](#-development)

Start with the [tutorial](./tutorial/#chapters).

**Architecture**: See [ContentPoll AI Flow Architecture](./docs/ContentPoll-AI-Flow-Architecture.md) for detailed documentation on the PocketFlow-inspired multi-step AI pipeline, including the Flow/Node pattern, sequence diagrams, and code examples.

### Available Scripts

[](#available-scripts)

```
npm run build        # Production build (minified)
npm run start        # Development mode with watch
npm test             # Run all tests (JS + PHP linting)
npm run test:js      # Vitest unit tests
npm run lint:js      # ESLint JavaScript files
composer test        # PHPUnit tests
```

### Testing

[](#testing)

- **JavaScript**: Vitest for helper functions and logic
- **PHP**: PHPUnit for storage, aggregation, and API validation
- **Linting**: WordPress coding standards via @wordpress/scripts
- **Database Safety**: Tests include safeguards to prevent accidental data loss

**Run Tests Safely**:

```
# JavaScript tests (safe - no database changes)
npm test

# PHP tests with production database protection
composer test

# PHP tests with separate test database (recommended)
WP_TESTS_DB_PREFIX=test_ composer test
```

See [tests/README.md](tests/README.md) for detailed testing documentation and database safety configuration.

### Project Structure

[](#project-structure)

```
content-poll/
├── src/
│   ├── block/vote-block/      # Gutenberg block (JS + CSS)
│   └── php/                    # Backend logic
│       ├── Admin/              # Settings page
│       ├── Blocks/             # Block registration
│       ├── REST/               # API endpoints
│       ├── Security/           # Nonce & token handling
│       └── Services/           # Vote storage & AI
├── build/                      # Compiled assets (webpack)
├── tests/                      # PHPUnit tests
├── languages/                  # Translation files
└── docs/                       # Documentation

```

🔒 Privacy & Security
------------------------

[](#-privacy--security)

### Data Collection

[](#data-collection)

- **Block ID**: UUID for each vote instance
- **Option Index**: Which option was selected (0-5)
- **Hashed Token**: SHA-256 hash of cookie + AUTH\_KEY

### What We DON'T Collect

[](#what-we-dont-collect)

- ❌ IP addresses
- ❌ User agents
- ❌ Email addresses
- ❌ Personal information

### GDPR Compliance

[](#gdpr-compliance)

- Anonymous voting only
- No personally identifiable information
- Uninstall script removes all data
- Cookie notice: Site owners should inform users about voting cookies

🌐 REST API
----------

[](#-rest-api)

### Vote

[](#vote)

```
POST /wp-json/content-poll/v1/block/{blockId}/vote
Headers: X-WP-Nonce
Body: { "optionIndex": 0, "postId": 123 }

```

### Results

[](#results)

```
GET /wp-json/content-poll/v1/block/{blockId}/results
Response: {
  "blockId": "...",
  "totalVotes": 42,
  "counts": { "0": 15, "1": 12, "2": 10, "3": 5 },
  "percentages": { "0": 35.71, "1": 28.57, "2": 23.81, "3": 11.90 },
  "userVote": 1  // If user has voted
}

```

### AI Suggestions (Editor Only)

[](#ai-suggestions-editor-only)

```
GET /wp-json/content-poll/v1/suggest?postId=123
Response: {
  "question": "What aspect interests you most?",
  "options": ["Option A", "Option B", "Option C", "Option D"]
}

```

🗺️ Roadmap
----------

[](#️-roadmap)

- Admin dashboard with vote analytics
- Export votes to CSV
- Transient caching for high-traffic sites
- Custom result templates
- Vote scheduling (start/end dates)
- Multiple votes per user (optional)
- Integration with popular form plugins

📄 Copyright and License
-----------------------

[](#-copyright-and-license)

ContentPoll AI is copyright 2025 Per Soderlind

ContentPoll AI is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

ContentPoll AI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with the Extension. If not, see .

🙏 Credits
---------

[](#-credits)

Built with modern WordPress tools and best practices. Uses @wordpress/scripts for building, WordPress design system for styling, and follows WordPress coding standards.

PocketFlow-inspired multi-step poll generation flow design is based on ideas and patterns from the [PocketFlow project](https://medium.com/@zh2408/i-built-an-llm-framework-in-just-100-lines-83ff1968014b).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance79

Regular maintenance activity

Popularity18

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Recently: every ~8 days

Total

16

Last Release

147d ago

PHP version history (2 changes)0.5.0PHP ^8.1

0.9.0PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1649452?v=4)[Per Søderlind](/maintainers/soderlind)[@soderlind](https://github.com/soderlind)

---

Top Contributors

[![soderlind](https://avatars.githubusercontent.com/u/1649452?v=4)](https://github.com/soderlind "soderlind (114 commits)")

---

Tags

contentpollwordpress-blockwordpress-plugin

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/soderlind-content-poll/health.svg)

```
[![Health](https://phpackages.com/badges/soderlind-content-poll/health.svg)](https://phpackages.com/packages/soderlind-content-poll)
```

###  Alternatives

[10up/10up-experience

The 10up Experience plugin configures WordPress to better protect and inform clients, aligned to 10up's best practices

139477.6k](/packages/10up-10up-experience)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)