Vote System Implementation Documentation

An implementation guide for the vote system.

Javascript Configuration

Implementing a Vote on your site follows these requirements:

build: Setup the vote on the system and obtain the UUID link: obtain the encoded UUID for the javascript deploy: Deploy the code on your site

Here's a simple example of how to include the Digital Research Vote in your site:


<script src="https://www.digitalresearch.uk/vote.js">
<script>
        function voteDR() {
            DigitalResearchModal.show({
                title: "Rate this page?", // Heading
                question: "How would you rate this page?", // Question
                reference: "vote.php", // Reference passed back
                buttonPair: "goodbad", // yesno, truefalse, thumbs, highlow, onoff, openclose, inout, lightdark, updown 
                uuid: "Y1gxd0pvWWdYdDFjZGdNaStVa0QyZzVTWVFEVDhJa04vc2Y3cVIvUlRoZ1NaSzRk", // Link generated for this vote
                scoreElementId: "DRvotescore", // Optional DOM element that receives the live score
                position: "center", // Position in the center of the screen
                theme: "dark", // light, dark, blue, green, grey, contrast, pastel
                onComplete: function(response, data) {
                    console.log("User selected: " + response);
                    console.log("Server response:", data);
                }
            });
        }
</script>

The javascript call has a collection of parameters that need to be configured before it will work:

  • title: Appears at the top of the dialogue as a header
  • question: The question asked in the dialogue, e.g. "Did you like this story?"
  • reference: A reference to the item being voted on, text alpha-numeric
  • buttonPair: Choice of options:
    • goodbad: Good and Bad
    • yesno: Yes and No
    • truefalse: True and False
    • thumbs: A HTML Thumbs up and thumbs down
    • highlow: High and Low
    • onoff: On and Off
    • openclose: Open and Close
    • inout: In and Out
    • lightdark: Light and Dark
    • updown: Up and Down
    • A|B: A = 1 and B = 0
  • uuid: Encoded UUID Link obtained from the API
  • scoreElementId: Optional DOM element id used to display the live vote SCORE. Defaults to DRvotescore
  • position: Left, Right, Top, Bottom, Middle
  • theme: The Colour Scheme
    • light: Normal Light Theme
    • dark: Normal Dark Theme
    • blue: Blues Theme
    • green: Greens Theme
    • grey: Greys Theme
    • contrast: A Nice Pastel Theme
  • onComplete: Boolean

The vote script now supports automatic live score retrieval. If an element with id DRvotescore is present on the page when vote.js loads, it will call GET /vote.php using the configured UUID and reference, then insert the returned SCORE into that element.

The score element can also carry its own values via dataset attributes:

  • data-dr-uuid: Encoded vote UUID
  • data-dr-reference: Reference to query

After the score is fetched, the script also stores:

  • data-score: Current cumulative score
  • data-totalvotes: Current total vote count

The Button

Calling for a Vote 


<style>
    .rate-this-page {
        position: fixed;
        bottom: 30px;
        left: 30px;
        z-index: 100;
    }

    .rate-button {
        color: white !important;
        font-weight: 600;
        padding: 0.75rem 1.25rem;
        transform: scale(1);
    }

    .rate-button:hover {
        transform: scale(1.05);
        box-shadow: 0 6px 12px rgba(0,0,0,0.3);
        background: linear-gradient(45deg, #221c54, #0099ff) !important;
    }

    .rate-button .icon {
        margin-right: 0.5rem;
    }

    @media screen and (max-width: 768px) {
        .rate-this-page {
            display: none; /* Hide on mobile devices */
        }

        .rate-button {
            padding: 0.5rem 1rem;
        }
    }
</style>
<div class="rate-this-page">
    <button class="button is-rounded is-primary is-outlined is-small rate-button" onclick="voteDR()">
      <span class="icon">
        <i class="fas fa-star">
      </span>
      <span>Rate this page (<span id="DRvotescore" data-dr-uuid="YOUR_ENCODED_UUID" data-dr-reference="vote.php">0</span>)</span>
    </button>
</div>

The button can be any DOM object that can invoke javascript, and by simply calling voteDR() the vote will be shown, captured and uploaded to your account.

In this example we're using BULMA CSS but it really doesn't matter how you style it or implement it.

If the DRvotescore span exists, vote.js will automatically populate it on page load and refresh it again after each successful vote.

Live Vote Score Retrieval

The vote endpoint now supports score lookup using GET. This is what vote.js uses behind the scenes when a score element is present.


GET /vote.php?uuid=ENCODED_UUID&reference=page-reference

{
  "success": true,
  "message": "Vote summary",
  "surveyid": 123,
  "reference": "about.php",
  "totalvotes": 12,
  "score": 4,
  "firstvote": "2026-04-10 17:00:00",
  "lastvote": "2026-04-10 17:10:00"
}

SCORE is cumulative: a positive vote (1) adds +1 and a negative vote (0) adds -1.