This document explains the Kuadratic val, a voting component that can be deployed on val.town. It exports an HTML component which displays one or more selectable voting elements and allows users to cast votes. Voting results are stored in the val.town SQLite database while enforcing limits on the number of votes both per element and per individual.

Kuadratic is a val that provides an embeddable voting widget for HTML pages. Key features include:

• Multiple Options: The component is capable of displaying more than one voteable element (or option) on the same page.

• Persistent Storage: All vote data is persisted in the val.town SQLite database, ensuring that votes are durable and can be retrieved or analyzed later.

• Vote Count Limiting: Each HTML instance using the component has a capped total number of votes. This setting prevents any single poll from being overloaded with votes and helps to maintain fair voting practices.

• Individual Vote Limits: The component enforces a limit on the number of votes an individual can cast. This helps maintain balanced participation and prevents abuse. Vote attribution (e.g., via IP check, device cookies, or user tokens) is integrated to track or limit individual participation.

1. HTML Component Exportation:

   • The Kuadratic val exports an HTML component that can be embedded in any webpage.
   • This component dynamically renders multiple vote options and an interactive interface (e.g., radio buttons, checkboxes, or custom vote buttons).

2. Voting Process:

   • Users view the available options and cast their votes by interacting with the UI.
   • Each vote is processed and immediately stored in the SQLite database provided by val.town.
   • Confirmation or error messages are presented to users (e.g., when they try to exceed their permitted vote count).

3. Vote Count & Validity Checks:

   • The server side (inside the val) enforces:
     • A total vote count limit per poll, ensuring that only a defined number of votes are accepted.
     • An individual vote count limit, ensuring that each user can only cast a predetermined number of votes.
   • If limits are reached, the component notifies the user that they have reached their vote limit.

4. Data Persistence:

   • Voting data, including option identifiers, vote counts, and voter metadata, is stored in the val.town SQLite database.
   • This allows for easy retrieval, analysis, and display of up-to-date voting results.

The exported component generally consists of:

• Container Element: A dedicated div or section where the voting options and controls are rendered.
• Option Elements: Each option (or element) is presented in a similar UI pattern, such as buttons or list items.
• Vote Button: A button that submits the vote and communicates with the backend API to store the vote.

The component communicates with a minimal API that includes endpoints to:

• Submit a vote.
• Retrieve current voting counts.
• Validate a vote submission against defined limits for the total count and per individual.

• Database Schema:
  A typical schema might include tables for:

  • votes (columns: id, option_id, voter_id, timestamp)
  • options (columns: option_id, description, vote_count)

• Query Handling:
  The val code will:

  • Insert new votes into the votes table.
  • Update the vote count for the respective option.
  • Check if the vote limit for the user or overall poll is reached before processing new votes.

• Global Vote Limit: A parameter (e.g., totalVotesAllowed) limits the number of votes across all users.
• Per-User Vote Limit: Each individual's session or identifier (like an IP address or a cookie token) is tracked to limit the number of votes they can cast. Before accepting a vote, the backend checks:
  • Has the global vote limit been reached?
  • Has this voter already used their available votes?

1. A page owner embeds the Kuadratic HTML component into their website.
2. A user navigates to the page and sees a list of voteable options.
3. The user selects an option and clicks the vote button.
4. A backend call is made to submit the vote.
5. The backend:
   • Checks the global and per-user vote limits.
   • If valid, stores the vote in the SQLite database.
   • Returns a response updating the UI (e.g., new vote counts or limit reached notification).
6. The component updates in real-time (or upon reload) to reflect the new vote counts.

To deploy the Kuadratic val:

• Ensure the hosting environment supports val.town’s mechanism for exporting HTML components and connecting to the SQLite database.

• Configure the vote limits (global and per-user) in your val settings.

• Embed the exported HTML component onto your target webpage using the provided script or iframe.

• Monitor the SQLite database to verify that votes are being recorded properly and that limits are enforced as expected.

Kuadratic offers a robust and secure way to integrate user voting on websites via an exported HTML component. Its features — including multiple voteable elements, enforced vote count restrictions, and persistent storage using val.town’s SQLite database — ensure both ease of integration and data integrity. This document serves as a guide for developers to understand and implement the Kuadratic voting component seamlessly within their val.town environment.