This example allows you to place a quick poll on a Web site. The poll can ask one question and has a multiple choice answer. Each site visitor can answer the poll and the results so far will be shown in a pop-up window. You can restrict visitors to voting once or once per hour, day, or month. Once a poll is complete it can be archived and its results will be shown permanently on your site.
The quick poll example demonstrates the following principles:
- How to use JavaScript to display a dynamic element within your site. The example uses a method similar to how some ad placement tools work.
- How to create a simple bar graph in HTML without using the image tags.
- How to use CSS to customize the display of text.
- How to keep track of unique visitors and how to check so they can only vote in the poll in the desired frequency.
The quick poll example can be used as-is to present polls to your site visitors or can be customized with your own CSS and HTML in order to make it fit into your site design better. The quick poll example can also be studied for ideas of how to present dynamic data on your sites, how to create a simple ad delivery system, and how to present data in bar graph form.
This documentation is split into two parts. The first part introduces the poll example and shows how you can use it to display polls on your own Web site without any programming. The second part dissects the example and shows how polls are served, how voters are checked for uniqueness, and how the administration interface is constructed.
Embedding a Poll
Polls are embedded into a Web site using a block of JavaScript code. The visitor's Web browser must support JavaScript in order for the quick poll example to work. Visitors who do not support JavaScript will not see anything in the location of the poll.
The following code is used to embed the "current" poll into a Web site. The "current" poll can be set in the administration interface (see below). Using this code makes it easy to present a new poll question daily or weekly by choosing a different "current" poll. The URL in the "src" attribute must point to the "Display" folder within the quick poll example folder.
<!-- Quick Poll - Current --> <script src="http://www.example.com/ExamplesPack/display/poll.lasso" type="text/javascript" /> <!-- Quick Poll - End -->
The script block returns an HTML div which is displayed at its location on your page. The div displays just as if it had been written directly into your HTML. The div has self contained CSS rules so that it displays appropriately even if your site uses its own stylesheet.
The "current" poll from the quick poll example is shown below live. By default this will show a poll "What is your favorite color?", but if you have created your own polls already then whichever has been set as the "current" poll will show below.
When the visitor clicks on the "Submit Answer" button their vote will be recorded and they will be shown the results of the poll so far in a pop-up window. If they have already voted within the allowed frequency then they will see a warning and the results of the poll. Alternately, the "View Results" button simply shows the results of the poll.
A specific poll can be embedded by specifying the poll's code in the script block. This allows you to use polls on several pages throughout your site. In addition, once a poll has been archived (see below) the results of the poll will show inline within your page rather than the form which allows the visitor to vote. The code below would show the poll "example".
<!-- Quick Poll - Current --> <script src="http://www.example.com/ExamplesPack/display/poll.lasso?code=example" type="text/javascript" /> <!-- Quick Poll - End -->
Note - The site which displays the poll does not need to be running Lasso. This example can actually be used to display dynamic polls on otherwise static Web sites.
Creating or Editing a Poll
Polls can be created or edited using the administration interface. This interface can be loaded through the following URL.
/ExamplesPack/Poll/index.lasso
Only the Lasso Site Administrator (or Server Administrator) or a member of the group "OP Quick Poll" can access the administration interface. Anybody can vote in a poll or view its results. In order to add additional administrators create a new user in the Setup > Security > Users section of Lasso Site Administration and add the user to the "OP Quick Poll" group.
The first page of the interface lists all of the polls that have been created. It includes a summary of the poll's attributes and a code snippet which can be used to place the poll on a page. The end of the page also includes a code snippet for placing the "current" poll on a page.
Clicking on the "Create New Poll" link will bring up the create poll page. The initial attributes of the poll can be setup and then the poll can be edited until it looks as desired.
Alternately, clicking on the name of any poll will bring up the editing page. The top of the page shows how the poll will display and its results. The remainder of the page allows the poll to be customized.
- The Title of the poll is displayed above both its display and results. The text and background color of the title can be customized by clicking on the label of the checkbox and typing a valid CSS color name (e.g. "red", "blue", "silver") or an HTML color entity (e.g. "#FF0000").
- The Code of the poll is used to reference it explicitly. The code should be used in the JavaScript to display a specific poll or a specific poll's results. The Current checkbox allows this poll to be set as the "current" poll. Note that there can only be one "current" poll so if this checkbox is checked any other "current" poll will be deselected.
- The Visibility allows a poll to be hidden. Even if the code is referenced explicitly neither the poll nor its results will be displayed.
- The Question for the poll is displayed above both its display and results. The default text color and background of the entire question and answer section for the poll can be customized.
- The Answers for the poll are each entered into a separate text input. As answers are added additional inputs are shown. Once the poll has been created the order of the answers can be changed and the text color of each answer can be customized.
- The Display Message and Results Message will be displayed below the poll display and results respectively. The message will display in the same color as the question.
- Finally, the poll can be set to allow visitors to vote with a specified frequency. Visitors can be allowed to vote only once, or once per hour, day, or month.
The buttons at the bottom of the page allow the poll to be updated or the update to be cancelled. The poll can also be archived, have its results reset, or be deleted.
Archiving a Poll
A poll should be archived when it is no longer open for voting. If the poll is displayed on your site then the results of the poll will be shown rather than the normal question display. When a poll is archived all of its vote history is deleted and only the summed results are retained.
Once a poll has been archived there is no way to simply re-open it. However, an archived poll can be re-opened by resetting its results. You can use the same poll on your site repeatedly by simply archiving it and then resetting it to show it again from scratch.
A poll's results can also be reset. This allows you to test a poll and then reset its results before making it live.
This section describes how the quick poll example is implemented. It is not necessary to read this section in order to use the quick poll on your site. You should read this section if you want to understand how the quick poll example works, if you want to customize the appearance or behavior of the example, or if you want to use it as the basis for a different solution.
Database Schema
The "op_quick_poll" database is automatically created in SQLite the first time the Quick Poll example is accessed. This database contains four tables. - "polls" includes one record for each poll. This database stores the title, question, display and results message, code, "current" status, archive status, and display option for each poll. The "prefs" field in this table stores a serialized map of stored style preferences for the display and results of the poll. - "answers" includes one record for each answer of a poll. Each answer includes the ID of a poll, the text of the answer, the "sort" order of the answer, and the running "results" total for the answer. - "results" includes one record for each vote that is case in an active poll. Each result includes the IDs of a poll and answer, the IP address of the voter, and the date/time of the vote. Once a poll has been archived all of its results are deleted, but the running totals in the answers table can still be used to display the poll's results. - "prefs" includes a single record which stores global preferences for the Quick Poll example.Quick Poll Display
The poll is displayed by calling the Display/poll.lasso file within an HTML script tag. The poll.lasso file attempts to find either the "current" poll or the poll with the specified code. Once the poll is found it includes the Display/display.lasso file in order to generate the HTML div which will display the poll.
However, the display code is not output directly. Instead, it is assembled into a JavaScript document.write() function. This allows the display code to replace the HTML script tag. The display code is interpreted by the browser as if it had been entered into the calling page at the location of the JavaScript block.
The display includes a form with a JavaScript function which opens a new window when the visitor selects either the "Submit Answer" or "View Results" buttons.
All of the styles for the poll display are generated inline based on the serialized "prefs" field from the record for the poll. This field is deserialized into a map and the values from the map are used to decide what colors to use for the poll display. Since all the styles are specified inline the stylesheet of the page that includes the poll should not affect the display of the poll.
Quick Poll Voting
When the visitor casts a vote in the poll a new window is opened which calls the Display/poll.lasso file. The poll.lasso file attempts to find the poll which was displayed based on the "code" parameter. The file also checks the "action" parameter to see whether the user submitted a vote or asked to see the results.
Depending on what frequency of voting is allowed a search of the results table is created. For example, if the visitors can vote daily then a search is performed for a vote that matches the current poll, the IP address of the current visitor, and the current day. If no records are found then the visitor is allowed to vote. If one or more records are found then the results of the poll are shown with a message saying that the visitor has already voted.
If the visitor can vote then the vote is recorded. A record is created in the results table which stores the visitor's IP address, the poll code, the answer code, and the current date/time. The answers table is also updated by counting the number of similar answers and updating the total in the answers table.
Quick Poll Results
When the Display/poll.lasso file is loaded with an "action" parameter of either "Submit Answer" or "View Results" then the results of the poll are displayed. Since each answer is maintained with a running total of the number of votes for that answer it is a simple matter of finding all the answers for the poll and displaying the count for each answer.
The bar graph is generated by stretching a 1x1 GIF based on the proportion of votes that were cast for each answer. The color of each graph is the same as the color of the text of the answer.
Quick Poll Administration
Only the Lasso Site Administrator (or Server Administrator) or a member of the group "OP Quick Poll" can access the administration interface. Anybody can vote in a poll or view its results. In order to add additional administrators create a new user in the Setup > Security > Users section of Lasso Site Administration and add the user to the "OP Quick Poll" group.
The poll administration consists of only three pages: A page to list all of the polls that have been created, a page to create a new poll, and a page to edit an existing poll. These three pages are described below and are commented extensively within their Lasso code.
Poll_List.Lasso - This page lists all of the polls that have been created. It generates a summary of each poll that includes its current status, code, and total number of responses. Clicking on the title of any poll brings up the Poll_Edit.Lasso page.
Poll_Create.Lasso - This page presents a form with default values for a new poll. It does not display a preview of the display or results of the poll. Once a new poll has been created the visitor sees the Poll_Edit.Lasso page with the new poll selected so they can continue editing it.
Poll_Edit.Lasso - This page presents a preview of the poll display and results at the top. These previews are generated "live" using the same HTML script code that will be used by a Web site author to display the poll. The page allows the attributes of the poll to be edited and also has options for archiving, resetting, or deleting a poll.