README.md 8.52 KB
Newer Older
Lester Chan's avatar
EOL    
Lester Chan committed
1
# WP-Polls
Lester Chan's avatar
Lester Chan committed
2
Contributors: GamerZ  
Lester Chan's avatar
Lester Chan committed
3
Donate link: https://lesterchan.net/site/donation/  
Lester Chan's avatar
Lester Chan committed
4
Tags: poll, polls, polling, vote, booth, democracy, ajax, survey, post, widget  
5
Requires at least: 4.9.6  
Lester Chan's avatar
Lester Chan committed
6
Tested up to: 5.1  
Lester Chan's avatar
Lester Chan committed
7
Stable tag: 2.75.3  
Lester Chan's avatar
EOL    
Lester Chan committed
8
9
10
11
12
13

Adds an AJAX poll system to your WordPress blog. You can also easily add a poll into your WordPress's blog post/page.

## Description
WP-Polls is extremely customizable via templates and css styles and there are tons of options for you to choose to ensure that WP-Polls runs the way you wanted. It now supports multiple selection of answers.

Lester Chan's avatar
Lester Chan committed
14
15
16
### Build Status
[![Build Status](https://travis-ci.org/lesterchan/wp-polls.svg?branch=master)](https://travis-ci.org/lesterchan/wp-polls)

Lester Chan's avatar
EOL    
Lester Chan committed
17
### Development
Lester Chan's avatar
Lester Chan committed
18
[https://github.com/lesterchan/wp-polls](https://github.com/lesterchan/wp-polls "https://github.com/lesterchan/wp-polls")
Lester Chan's avatar
EOL    
Lester Chan committed
19
20

### Credits
Lester Chan's avatar
Lester Chan committed
21
* Plugin icon by [Freepik](http://www.freepik.com) from [Flaticon](http://www.flaticon.com)
Lester Chan's avatar
EOL    
Lester Chan committed
22
23

### Donations
Lester's avatar
-m    
Lester committed
24
I spent most of my free time creating, updating, maintaining and supporting these plugins, if you really love my plugins and could spare me a couple of bucks, I will really appreciate it. If not feel free to use it without any obligations.
Lester Chan's avatar
EOL    
Lester Chan committed
25
26

## Changelog
Lester Chan's avatar
Lester Chan committed
27
28
### VErsion 2.75.3
* FIXED: Broken filter for templates
Lester Chan's avatar
Lester Chan committed
29
* FIXED: Divison by 0 by totalvoters
Lester Chan's avatar
Lester Chan committed
30

Lester Chan's avatar
Lester Chan committed
31
32
33
### Versiob 2.75.2
* FIXED: Missing str_replace for wp_polls_template filter

Lester Chan's avatar
Lester Chan committed
34
35
36
37
### Version 2.75.1
* FIXED: Use array() instead of [] as a few users are still on < PHP 5.4. Props @bearlydoug.
* FIXED: pollq_expiry is now 0 instead of blank string. Props @hpiirainen.

38
39
40
41
### Version 2.75
* FIXED: Standardize all filters to begin with `wp_polls` rather than `poll`
* NEW: Added `wp_polls_ipaddress` and `wp_polls_hostname` to allow user to overwrite it.

Lester Chan's avatar
2.74.1    
Lester Chan committed
42
43
44
### Version 2.74.1
* FIXED: Don't use PHP 5.4 Short array syntax.
* FIXED: Division by zero 
Lester Chan's avatar
Lester Chan committed
45
* FIXED: Wrong database column type for pollq_expiry
Lester Chan's avatar
2.74.1    
Lester Chan committed
46

47
### Version 2.74
Lester Chan's avatar
Lester Chan committed
48
* NEW: Hashed IP and anonymize Hostname to make it GDPR compliance
49
* NEW: If Do Not Log is set in Poll Options, do not log to DB
50
* NEW: Support %POLL_MULTIPLE_ANSWER_PERCENTAGE%. This is total votes divided by total voters.
51

Lester Chan's avatar
Bump    
Lester Chan committed
52
53
54
55
### Version 2.73.8
* FIXED: Bug fixes and stricter type checking

### Version 2.73.7
Lester Chan's avatar
Lester Chan committed
56
57
* FIXED: Unable to save input HTML tags for footer templates

Lester Chan's avatar
Lester Chan committed
58
59
### Version 2.73.6
* FIXED: Unable to vote for multiple answers
60
* FIXED: input HTML tags being removed when saving templates
Lester Chan's avatar
Lester Chan committed
61

Lester Chan's avatar
Lester Chan committed
62
63
64
### Version 2.73.5
* FIXED: Parsed error in SERVER variable.

65
66
67
### Version 2.73.4
* FIXED: sanitize_key on top of intval.

68
### Version 2.73.3
69
* NEW: Added sort by votes casted to poll answers.
Lester Chan's avatar
Lester Chan committed
70
* NEW: For polls with mutiple answers, we divided by total votes instead of total voters. Props @ljxprime.
71
* FIXED: Do not display poll option is not respected when poll is closed.
72
73
* FIXED: pollip_qid, pollip_aid, pollip_timestamp are now int(10) in pollsip table.
* FIXED: pollq_expiry is now int(10) in pollsq table.
Lester Chan's avatar
Lester Chan committed
74

Lester Chan's avatar
Lester Chan committed
75
### Version 2.73.2
Lester Chan's avatar
Lester Chan committed
76
* NEW: Bump WordPress 4.7
Lester Chan's avatar
Lester Chan committed
77
78
* FIXED: Change cron to hourly instead of twice daily.

Lester Chan's avatar
Lester Chan committed
79
80
### Version 2.73.1
* FIXED: Allow local IP
Lester's avatar
Lester committed
81
82
* FIXED: XSS on Poll bar option. Props [Netsparker Web Application Security Scanner](https://www.netsparker.com/)
* FIXED: Stricter Poll pptions check
Lester Chan's avatar
Lester Chan committed
83
 
Lester's avatar
Lester committed
84
85
86
87
### Version 2.73
* NEW: Display Poll Questions at the top of the Poll Logs table
* FIXED: Remove slashes

88
89
90
91
### Version 2.72
* NEW: Use translate.wordpress.org to translate the plugin
* FIXED: SQL Injection fixes. Props [Jay Dansand](https://github.com/jaydansand)
* FIXED: Use $wpdb->insert(), $wpdb->update() and $wpdb->delete() as much as possible
Lester's avatar
Lester committed
92
* FIXED Remove poll_archive_show option from UI
93

Lester's avatar
Lester committed
94
### Version 2.71
Lester's avatar
Lester committed
95
* FIXED: Use wp_kses_post() to get filter always bad tags
Lester's avatar
Lester committed
96

97
### Version 2.70
98
* NEW: Add wp_polls_vote_poll_success action hook
Lester's avatar
Lester committed
99
100
101
* NEW: Add wp_polls_add_poll, wp_polls_update_poll, wp_polls_delete_poll action hooks
* FIXED: PHP Notices
* FIXED: Removed not needed wp_print_scripts
Lester's avatar
Lester committed
102
* FIXED: Use esc_attr() and esc_textarea() instead of htmlspecialchars(). Props [Govind Singh](https://in.linkedin.com/pub/govind-singh/21/1a9/bab)
103

Lester Chan's avatar
EOL    
Lester Chan committed
104
105
106
107
108
109
110
111
112
113
114
115
116
117
## Screenshots

1. Admin - All Poll
2. Admin - Manage Polls
3. Admin - Poll Options
4. Admin - Poll Templates
5. Admin - Poll Widget
6. Admin - Uninstall Poll
7. Poll - Single Poll Answer
8. Poll - Mutiple Poll Answers
9. Poll - Results
10. Poll - Archive

## Frequently Asked Questions
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

### General Usage (Without Widget)

```php
<?php if ( function_exists( 'vote_poll' ) && ! in_pollarchive() ): ?>
	<li>
		<h2>Polls</h2>
		<ul>
			<li><?php get_poll();?></li>
		</ul>
		<?php display_polls_archive_link(); ?>
	</li>
<?php endif; ?>
```

* To show specific poll, use `<?php get_poll(2); ?>` where 2 is your poll id.
* To show random poll, use `<?php get_poll(-2); ?>`
* To embed a specific poll in your post, use `[poll id="2"]` where 2 is your poll id.
* To embed a random poll in your post, use `[poll id="-2"]`
* To embed a specific poll's result in your post, use `[poll id="2" type="result"]` where 2 is your poll id.

### General Usage (With Widget)
1. Go to `WP-Admin -> Appearance -> Widgets`.
2. You can add the Polls Widget by clicking on the 'Add' link besides it.
3. After adding, you can configure the Polls Widget by clicking on the 'Edit' link besides it.
4. Click 'Save Changes'.
5. Scroll down for instructions on how to create a Polls Archive.

Lester Chan's avatar
EOL    
Lester Chan committed
146
147
148
149
150
151
152
153
154
155
### How To Add A Polls Archive?
1. Go to `WP-Admin -> Pages -> Add New`.
2. Type any title you like in the post's title area.
3. If you ARE  using nice permalinks,  after typing the title, WordPress will generate the permalink to the page. You will see an 'Edit' link just beside the permalink.
4. Click 'Edit' and type in `pollsarchive` in the text field and click 'Save'.
5. Type `[page_polls]` in the post's content area.
6. Click 'Publish'.

* If you ARE NOT using nice permalinks, you need to go to `WP-Admin -> Polls -> Poll Options` and under `Poll Archive -> Polls Archive URL`, you need to fill in the URL to the Polls Archive Page you created above.

156
### Why doesn't my poll's answers add up to 100%?
Lester Chan's avatar
Add ;    
Lester Chan committed
157
* It is because of rounding issues. To make it always round up to 100%, the last poll's answer will get the remainding percentage added to it. To enable this feature, add this to your theme's functions.php: `add_filter( 'wp_polls_round_percentage', '__return_true' );`
158

Lester Chan's avatar
EOL    
Lester Chan committed
159
### How Does WP-Polls Load CSS?
Lester Chan's avatar
Lester Chan committed
160
161
* WP-Polls will load `polls-css.css` from your theme's directory if it exists.
* If it doesn't exists, it will just load the default `polls-css.css` that comes with WP-Polls.
Lester Chan's avatar
EOL    
Lester Chan committed
162
163
164
165
166
167
168
169
170
171
172
173
* This will allow you to upgrade WP-Polls without worrying about overwriting your polls styles that you have created.

### Why In Internet Explorer (IE) The poll's Text Appear Jagged?
* To solve this issue, Open poll-css.css
* Find: `/* background-color: #ffffff; */`
* Replace: `background-color: #ffffff;` (where #ffffff should be your background color for the poll.)

### How Do I Have Individual Colors For Each Poll's Bar?
* Courtesy Of [TreedBox.com](http://treedbox.com "TreedBox.com")
* Open poll-css.css
* Add to the end of the file:

Lester Chan's avatar
Lester Chan committed
174
```
Lester Chan's avatar
Lester Chan committed
175
176
177
178
179
180
181
182
183
184
185
.wp-polls-ul li:nth-child(01) .pollbar{ background:#8FA0C5}
.wp-polls-ul li:nth-child(02) .pollbar{ background:#FF8}
.wp-polls-ul li:nth-child(03) .pollbar{ background:#ff8a3b}
.wp-polls-ul li:nth-child(04) .pollbar{ background:#a61e2a}
.wp-polls-ul li:nth-child(05) .pollbar{ background:#4ebbff}
.wp-polls-ul li:nth-child(06) .pollbar{ background:#fbca54}
.wp-polls-ul li:nth-child(07) .pollbar{ background:#aad34f}
.wp-polls-ul li:nth-child(08) .pollbar{ background:#66cc9a}
.wp-polls-ul li:nth-child(09) .pollbar{ background:#98CBCB}
.wp-polls-ul li:nth-child(10) .pollbar{ background:#a67c52}
.wp-polls-ul li .pollbar{ transition: background 0.7s ease-in-out }
Lester Chan's avatar
Lester Chan committed
186
.wp-polls-ul li .pollbar:hover{ background:#F00 }
Lester Chan's avatar
Lester Chan committed
187
```
Lester Chan's avatar
EOL    
Lester Chan committed
188
189

### To Display Total Polls
Lester Chan's avatar
Lester Chan committed
190

Lester Chan's avatar
Lester Chan committed
191
```php
Lester Chan's avatar
Lester Chan committed
192
193
194
<?php if ( function_exists( 'get_pollquestions' ) ): ?>
	<?php get_pollquestions(); ?>
<?php endif; ?> 
Lester Chan's avatar
Lester Chan committed
195
```
Lester Chan's avatar
Lester Chan committed
196
 
Lester Chan's avatar
EOL    
Lester Chan committed
197
### To Display Total Poll Answers
Lester Chan's avatar
Lester Chan committed
198

Lester Chan's avatar
Lester Chan committed
199
```php
Lester Chan's avatar
Lester Chan committed
200
201
202
203
<?php if ( function_exists( 'get_pollanswers' ) ): ?>
	<?php get_pollanswers(); ?>
<?php endif; ?> 
```
Lester Chan's avatar
Lester Chan committed
204
 
Lester Chan's avatar
EOL    
Lester Chan committed
205
### To Display Total Poll Votes
Lester Chan's avatar
Lester Chan committed
206

Lester Chan's avatar
Lester Chan committed
207
```php
Lester Chan's avatar
Lester Chan committed
208
209
210
211
<?php if ( function_exists( 'get_pollvotes' ) ): ?>
	<?php get_pollvotes(); ?>
<?php endif; ?> 
```
Lester Chan's avatar
Lester Chan committed
212
 
Thomas Brace's avatar
Thomas Brace committed
213
214
215
216
217
218
219
220
### To Display Poll Votes by ID

```php
<?php if ( function_exists( 'get_pollvotes_by_id' ) ): ?>
	<?php get_pollvotes_by_id($poll_id); ?>
<?php endif; ?>
```

Lester Chan's avatar
EOL    
Lester Chan committed
221
### To Display Total Poll Voters
Lester Chan's avatar
Lester Chan committed
222

Lester Chan's avatar
Lester Chan committed
223
```php
Lester Chan's avatar
Lester Chan committed
224
225
226
227
<?php if ( function_exists( 'get_pollvoters' ) ): ?>
	<?php get_pollvoters(); ?>
<?php endif; ?> 
```
Thomas Brace's avatar
Thomas Brace committed
228

229
### To Display Poll Time by ID and date format
Thomas Brace's avatar
Thomas Brace committed
230
231

```php
232
<?php if ( function_exists( 'get_polltime' ) ): ?>
Lester Chan's avatar
Lester Chan committed
233
	<?php get_polltime( $poll_id, $date_format ); ?>
Thomas Brace's avatar
Thomas Brace committed
234
235
<?php endif; ?>
```