| 1 |
=== Timed Content === |
| 2 |
|
| 3 |
Contributors: kjvtough, awelzel |
| 4 |
Tags: marketing, marketing tool, post, page, date, time, timer, timed, show, hide, content, schedule, display |
| 5 |
Requires at least: 3.8 |
| 6 |
Tested up to: 6.2 |
| 7 |
Stable tag: 2.76 |
| 8 |
License: GPL2 |
| 9 |
|
| 10 |
Plugin to show or hide portions of a Page or Post based on specific date/time characteristics. |
| 11 |
|
| 12 |
== Description == |
| 13 |
|
| 14 |
The Timed Content plugin allows users to specify that a portion of a Page or Post should appear/be visible or disappear/be invisible based on given time characteristics. You can also make portions of a Post or Page be visible at certain dates and times; you can even set up a schedule! |
| 15 |
|
| 16 |
The plugin adds the following: |
| 17 |
|
| 18 |
* A "client-side" shortcode that allows the marking of content to appear or disappear after a given time interval; a "fade" effect is included. This functionality is intended to be used for special effects only, as content marked in this manner is still visible in the HTML source and, therefore, not a secure method of hiding content. |
| 19 |
* Two "server-side" shortcodes that allow the marking of content to be visible only during specified date/time intervals. This functionality **can** be used as a secure method of hiding content, because the marked content will be included in the Page/Post **only** when viewed in the specified date/time intervals. |
| 20 |
|
| 21 |
A TinyMCE dialog is included to help users build the shortcodes. See the Screenshots tab for more info. |
| 22 |
|
| 23 |
== Installation == |
| 24 |
|
| 25 |
1. Extract the contents of the package to the `/wp-content/plugins/timed-content` directory |
| 26 |
2. Activate the plugin through the 'Plugins' menu in WordPress |
| 27 |
|
| 28 |
== Frequently Asked Questions == |
| 29 |
|
| 30 |
= Old rules after updating to version 2.50 = |
| 31 |
|
| 32 |
In versions prior to 2.50 the date/time format was not handled very well which caused quite some confusion. Therefore version 2.50 now uses a fixed format similar to ISO 8601: yyyy-mm-dd HH:MM |
| 33 |
|
| 34 |
Existing shortcodes and rules containing dates in the format mm/dd/yyyy should still work, but when editing rules the date value is converted to the new format. |
| 35 |
|
| 36 |
To be sure, you should check your existing rules and shortcodes if you upgraded from a version below 2.50. |
| 37 |
|
| 38 |
= Using Timed Content in Gutenberg = |
| 39 |
|
| 40 |
If you want to use Timed Content with Gutenberg you have to add a "Classic" block. There is no way to show or hide other content blocks with Timed Content. |
| 41 |
|
| 42 |
== Screenshots == |
| 43 |
|
| 44 |
1. An example showing use of the `[timed-content-client]` shortcode. The "alarm clock" button on the editor menubar brings up a dialog box to help build the Timed Content shortcodes. |
| 45 |
2. The "Add Timed Content shortcode" dialog showing the Client tab. Check the attribute you want to add and fill in the textboxes. |
| 46 |
3. The "Add Timed Content shortcode" dialog showing the Server tab. Check the attribute you want to add, then click on the Date and Time textboxes. |
| 47 |
4. The date and time pickers help you format a correct date and time. Here's the jQuery UI Datepicker in action. |
| 48 |
5. The "Add Timed Content shortcode" dialog showing the Timed Content Rules tab. |
| 49 |
|
| 50 |
== Changelog == |
| 51 |
|
| 52 |
= 2.76 = |
| 53 |
|
| 54 |
* Fixed a bug which caused server side "hide" rules not to work any longer. |
| 55 |
|
| 56 |
= 2.75 = |
| 57 |
|
| 58 |
* Fixed a bug which caused client side "hide" rules not to work any longer. |
| 59 |
|
| 60 |
= 2.74 = |
| 61 |
|
| 62 |
* Fixed compatibility issue with PHP 7. |
| 63 |
|
| 64 |
= 2.73 = |
| 65 |
|
| 66 |
* Fixed security issue with client side shortcodes which allowed to insert raw HTML and JavaScript via the shortcode. |
| 67 |
* Refactored codebase according to WordPress Core coding guidelines. |
| 68 |
* Adjusted time calculation to keep time in rules independent of current DST. |
| 69 |
* Fixed a bug when creating new a server side rule and leaving the editor without saving it. |
| 70 |
|
| 71 |
= 2.72 = |
| 72 |
|
| 73 |
* Fixed deprecation warnings with PHP 8.1. |
| 74 |
|
| 75 |
= 2.71 = |
| 76 |
|
| 77 |
* Changed loading translations to support using custom translations by LOCO Translate. |
| 78 |
|
| 79 |
= 2.70 = |
| 80 |
|
| 81 |
* The number of calculated date/time values is limited to avoid too many values for very long periods. |
| 82 |
|
| 83 |
= 2.69 = |
| 84 |
|
| 85 |
* Updated compatibility for WordPress 6.0 |
| 86 |
|
| 87 |
= 2.68 = |
| 88 |
|
| 89 |
* Fixed a problem with shortcodes on pages without post object. |
| 90 |
|
| 91 |
= 2.67 = |
| 92 |
|
| 93 |
* Refactor backend code to avoid errors in situations when there is no current post but a post is expected. |
| 94 |
|
| 95 |
= 2.66 = |
| 96 |
|
| 97 |
* Updated compatibility information for WordPress 5.8. |
| 98 |
|
| 99 |
= 2.65 = |
| 100 |
|
| 101 |
* Fixed a PHP warning which could occur if no exceptions are defined in a rule. |
| 102 |
|
| 103 |
= 2.64 = |
| 104 |
|
| 105 |
* Fixed empty TinyMCE dialog. |
| 106 |
|
| 107 |
= 2.62-2.63 = |
| 108 |
|
| 109 |
* Fixed PHP 7.3 compatibility issues. |
| 110 |
|
| 111 |
= 2.61 = |
| 112 |
|
| 113 |
* Fixed PHP notice when using rules without exceptions. |
| 114 |
|
| 115 |
= 2.60 = |
| 116 |
|
| 117 |
* Fixed broken handling of rule exceptions. |
| 118 |
* Changed label for intervals in rule editor. |
| 119 |
|
| 120 |
= 2.58 = |
| 121 |
|
| 122 |
* Changed the way how debug output is generated to the old variant without HTML sanitizing to make it easier to understand the output (thanks to Enrico Bacis for this). |
| 123 |
|
| 124 |
= 2.57 = |
| 125 |
|
| 126 |
* Extended `debug` parameter: it's now also possible to show debug output only if content is hidden (thanks to Enrico Bacis for this). |
| 127 |
|
| 128 |
= 2.56 = |
| 129 |
|
| 130 |
* Use of 'UTC' instead of '+0000' as default time zone to avoid problems with older PHP versions (eventhough you should better update to a supported PHP version). |
| 131 |
|
| 132 |
= 2.55 = |
| 133 |
|
| 134 |
* Better handling of shortcodes with invalid timezones to avoid unhandled runtime exceptions. |
| 135 |
* Improved debug output. |
| 136 |
|
| 137 |
= 2.54 = |
| 138 |
|
| 139 |
* Default date values for new rules will now be in the correct format and not in the local date format of WordPress. |
| 140 |
|
| 141 |
= 2.53 = |
| 142 |
|
| 143 |
* Added support for old shortcodes with localized date formats again. Every date/time which can be used in `strtotime()` should work now as well. |
| 144 |
* Improved format of debug output. |
| 145 |
|
| 146 |
= 2.52 = |
| 147 |
|
| 148 |
* Fixed a bug for server side shortcodes without or invalid "hide" attribute which did always hide the content. |
| 149 |
|
| 150 |
= 2.51 = |
| 151 |
|
| 152 |
* Fixed a bug where the "hide" attribute of server side shortcodes did not get parsed correctly. |
| 153 |
|
| 154 |
= 2.50 = |
| 155 |
|
| 156 |
* Major code refactoring and cleanup - please check your existing rules and shortcodes if they still work as expected and change them if needed! |
| 157 |
* Increased minimum required WordPress version to 3.8 |
| 158 |
* Date format for new shortcodes and rules is now always "yyyy-mm-dd HH:MM" (similar to ISO 8601) |
| 159 |
* Existing dates in rules and shortcodes will be parsed as "mm/dd/yyyy HH:MM" if they contain slashes |
| 160 |
* Time values containing "AM" or "PM" will still work but converted to 24h format internally |
| 161 |
|
| 162 |
= 2.15 = |
| 163 |
|
| 164 |
* Fixed 404 error caused by wrong URL for jquery date/time picker localization. |
| 165 |
* Current date/time in TinyMCE dialog will be displayed as "yyyy-mm-dd HH:MM" as well. |
| 166 |
|
| 167 |
= 2.10 = |
| 168 |
|
| 169 |
* Fixed a problem with unexpected `p` elements inside server side timed content sections. |
| 170 |
|
| 171 |
= 2.9 = |
| 172 |
|
| 173 |
* Changed default sort order of the rules in the backend to the title. |
| 174 |
|
| 175 |
= 2.8 = |
| 176 |
|
| 177 |
* Added debug parameter `tctest`. |
| 178 |
|
| 179 |
= 2.7 = |
| 180 |
|
| 181 |
* Fixed deprecated class constructors. |
| 182 |
|
| 183 |
= 2.6 = |
| 184 |
|
| 185 |
* New action hooks. |
| 186 |
* `[timed-content-rule]` shortcode now accepts a Timed Content Rule name as well as an ID. |
| 187 |
* Streamlined i18n for date/time pickers (Use values available in Wordpress settings and `$wp_locale` when available, combined *-i18n.js files into one). |
| 188 |
* Some developer docs in the `readme.txt` |
| 189 |
|
| 190 |
= 2.5.1 = |
| 191 |
|
| 192 |
* Fixed `current_time()` bug in __rulesShowHTML() introduced in 2.5. |
| 193 |
|
| 194 |
= 2.5 = |
| 195 |
|
| 196 |
* Removed dependency on jQuery UI Dialog; now uses Thickbox. |
| 197 |
* Added and modified `fix_date_i18n()` from https://core.trac.wordpress.org/ticket/25768 to better handle DST and timezones with i18n. |
| 198 |
* Added custom filter `timed_content_filter_override` so admins can modify/replace `timed_content_filter` if necessary. |
| 199 |
* Using built-in spinner image now instead of `wpspin.gif` |
| 200 |
|
| 201 |
= 2.4 = |
| 202 |
|
| 203 |
* Removed `timed-content-admin-tinymce.js` (No need anymore; required JS variables now hooked directly into editor). Fixes incompatibility with OptimizePress. |
| 204 |
|
| 205 |
= 2.3.1 = |
| 206 |
|
| 207 |
* Fixed minor bugs related to Exception Dates. |
| 208 |
* Optimized rule periods arrays (array only needs 'status' and 'time' when it's meant to be human-readable). |
| 209 |
* Added custom filter `timed_content_filter` to emulate `apply_filter( 'the_content', ... )` functionality for content. |
| 210 |
|
| 211 |
= 2.3 = |
| 212 |
|
| 213 |
* Fixed bug when setting up weekly recurrence for Timed Content Rules. |
| 214 |
* NEW! Exception Dates (dates on which your Timed Content Rule shouldn't run). |
| 215 |
|
| 216 |
= 2.2 = |
| 217 |
|
| 218 |
* Much improved i18n |
| 219 |
* New Spanish translation - Many thanks to Andrew Kurtis and Jelena Kovacevic from WebHostingHub (Nueva traducción de español - Muchas gracias a Andrew Kurtis y Jelena Kovacevic desde WebHostingHub). |
| 220 |
|
| 221 |
= 2.1.5 = |
| 222 |
|
| 223 |
* Unified dashicons among all of my plugins. |
| 224 |
* Minor improvements in TinyMCE dialog UI and Date/Time UI controls. |
| 225 |
|
| 226 |
= 2.1.4 = |
| 227 |
|
| 228 |
* Fixed TinyMCE editor button for TinyMCE 4.x. |
| 229 |
|
| 230 |
= 2.1.3 = |
| 231 |
|
| 232 |
* Removed support for PHP4 in `customFieldsInterface.php`. |
| 233 |
* Fixed Wordpress version check for deciding which image to use for TinyMCE button. |
| 234 |
* Fixed "Strict Standards" warning in PHP 5.4 in `__getNextWeek()`. |
| 235 |
|
| 236 |
= 2.1.2 = |
| 237 |
|
| 238 |
* Dashicons support for WP 3.8 + added. Support for old-style icons in Admin/TinyMCE is deprecated. |
| 239 |
* Added versioning to all `wp_enqueue_style()` calls. |
| 240 |
|
| 241 |
= 2.1.1 = |
| 242 |
|
| 243 |
* CSS for JQuery UI now loaded locally as required by Wordpress plugin repository rules. |
| 244 |
* Improved UX on TinyMCE dialog and Timed Content Rules detail page. |
| 245 |
|
| 246 |
= 2.1 = |
| 247 |
|
| 248 |
* Fixed inconsistency in how the days of week to repeat on were being set up between the front and back ends. |
| 249 |
* Fixed variable scope bug that occurred on activation. |
| 250 |
* Improved i18n. |
| 251 |
|
| 252 |
= 2.0 = |
| 253 |
|
| 254 |
* Added Timed Content Rules. |
| 255 |
* Replaced AnyTime plugin with jQuery UI Timepicker (http://fgelinas.com/code/timepicker) and Wordpress's internal jQuery UI Datepicker. |
| 256 |
* HTML code created by `[timed-content-client]` can now either be enclosed in either `<div>` or `<span>` tags. |
| 257 |
* Debugging statements for `[timed-content-server]` now displayed on Post/Page (only if logged in and have the rights to edit that Post/Page - no more digging into the HTML source). |
| 258 |
* Improved code documentation. |
| 259 |
|
| 260 |
= 1.2 = |
| 261 |
|
| 262 |
* Upgraded AnyTime jQuery plugin. |
| 263 |
* `timed-content.js` is now always loaded (Size > 1KB, so not a lot of extra overhead); fixes bug when multiple/nested shortcodes are used. |
| 264 |
|
| 265 |
= 1.1 = |
| 266 |
|
| 267 |
* Fixed some internal filename discrepancies. |
| 268 |
|
| 269 |
= 1.0 = |
| 270 |
|
| 271 |
* Initial release. |
| 272 |
|
| 273 |
== Examples == |
| 274 |
|
| 275 |
`[timed-content-client show="1:00"]Show me after one minute. Since we don't want a fade-in, we can leave it out of the "show" attribute completely.[/timed-content-client]` |
| 276 |
|
| 277 |
`[timed-content-client show="1:00:1000"]Show me after one minute with a 1000 millisecond (1 second) fade-in.[/timed-content-client]` |
| 278 |
|
| 279 |
`[timed-content-client hide="1:00:1000"]Hide me after one minute with a 1000 millisecond (1 second) fade-out.[/timed-content-client]` |
| 280 |
|
| 281 |
`[timed-content-client show="1:00:500" hide="5:00:2000"]Show me after one minute with a 500 millisecond (a half-second) fade-in, then hide me after five minutes with a 2000 millisecond (2 seconds) fade-out.[/timed-content-client]` |
| 282 |
|
| 283 |
`[timed-content-server show="2013-09-13 20:30:00 -0600"]Show me starting at 8:30 PM Central Standard Time on September 13th, 2013. I will not be displayed before then.[/timed-content-server]` |
| 284 |
|
| 285 |
`[timed-content-server hide="2013-09-13 20:30:00 America/Chicago"]Hide me starting at 8:30 PM Central Daylight Time (i.e., the same timezone as Chicago) on September 13th, 2013. I will not be displayed after then[/timed-content-server]` |
| 286 |
|
| 287 |
`[timed-content-server show="2013-09-13 20:30:00 -0600" hide="2013-09-13 21:30:00 -0600"]Show me starting at 8:30 PM Central Standard Time on September 13th, 2013, then hide me an hour later. I will not be displayed before or after then.[/timed-content-server]` |
| 288 |
|
| 289 |
`[timed-content-rule id="164"]Display me based on the settings for the Timed Content Rule whoseID is 164.[/timed-content-rule]` |
| 290 |
|
| 291 |
== Usage == |
| 292 |
|
| 293 |
NOTE: All shortcodes can be built using the TinyMCE dialog. When in doubt, use the dialog to create correctly formed shortcodes. |
| 294 |
|
| 295 |
**The timed-content-client shortcode** |
| 296 |
|
| 297 |
`[timed-content-client show="mm:ss:fff" hide="mm:ss:fff"]Example Text[/timed-content-client]` |
| 298 |
|
| 299 |
* `show` - Specifies the time interval after loading the web page when the marked content should be displayed. The attribute consists of three parts, |
| 300 |
separated by colons: `mm` - minutes, `ss` - seconds, and `fff` - if greater than `0`, a fade-in effect lasting `fff` milliseconds is applied. |
| 301 |
* `hide` - Specifies the time interval after loading the web page when the marked content should be hidden. The attribute consists of three parts, |
| 302 |
separated by colons: `mm` - minutes, `ss` - seconds, and `fff` - if greater than `0`, a fade-out effect lasting `fff` milliseconds is applied. |
| 303 |
|
| 304 |
Both attributes are optional, but at least one attribute must be included. Leading zeros (0) are optional. The shortcode's behaviour depends on which attributes are used: |
| 305 |
|
| 306 |
* `show` only - Marked content is initially not visible, then appears `mm` minutes and `ss` seconds after loading with a `fff` millisecond fade-in. |
| 307 |
* `hide` only - Marked content is initially visible, then disappears `mm` minutes and `ss` seconds after loading with a `fff` millisecond fade-out. |
| 308 |
* `show` and `hide` - Marked content is initially not visible, then appears according to the values set in `show`, then disappears according to the values set in `hide`. |
| 309 |
|
| 310 |
Your users must have JavaScript enabled for this shortcode to work. |
| 311 |
|
| 312 |
**The timed-content-server shortcode** |
| 313 |
|
| 314 |
`[timed-content-server show="datetime" hide="datetime" debug="true|false|when_hidden"]Example Text[/timed-content-server]` |
| 315 |
|
| 316 |
* `show` - Specifies the date/time when the marked content should start being included on the web page. |
| 317 |
* `hide` - Specifies the date/time after which the marked content should stop being included on the web page. |
| 318 |
* `debug` - If `true`, adds some debugging statements to the web page as HTML comments. If `when_hidden`, the debugging statements are added only when the content is hidden. Defaults to `false`. |
| 319 |
|
| 320 |
The date and time are expected to be yyyy-mm-dd HH:MM (similar to ISO 8601), for example `2019-04-07 15:30` for April 7, 2019, 15:30. For backward compatiblity old "human readable" date formats should also work, but these should not be used any longer! |
| 321 |
|
| 322 |
Both `show` and `hide` attributes are optional, but at least one attribute must be included. The shortcode's behaviour depends on which attributes are used: |
| 323 |
|
| 324 |
* `show` only - Marked content is outputted only after the date/time set here. |
| 325 |
* `hide` only - Marked content is outputted only before the date/time set here. |
| 326 |
* `show` and `hide` - Marked content is outputted only during the time period defined by the `show` and `hide` attributes. |
| 327 |
|
| 328 |
**The timed-content-rule shortcode** |
| 329 |
|
| 330 |
`[timed-content-rule id="{rule_id}|{rule_name}"]Example Text[/timed-content-rule]` |
| 331 |
|
| 332 |
You can find the correct shortcode from the Timed Content Rules overview page, or use the TinyMCE dialog. |
| 333 |
|
| 334 |
**Testing server side rules** |
| 335 |
|
| 336 |
For testing the behaviour of server side rules at specific times, you may use the GET parameter `tctest` in an URL, followed by date and time in the format `YYYY-MM-DD+hh:mm:ss`. This works only you are logged in with a user which has the right to edit the displayed page or post. For example: `http://mysite.example?tctest=2018-02-10+19:16:00` will show the content as if it was February 10, 2018 at 19:16. |
| 337 |
|
| 338 |
== Developer Documentation == |
| 339 |
|
| 340 |
**Action hooks** |
| 341 |
|
| 342 |
`add_action( "timed_content_server_show", "{function_name}", {priority_level}, 4 );` |
| 343 |
|
| 344 |
Fired when the `[timed-content-server]` shortcode is encountered *AND* the content is to be displayed based on the shortcode's show/hide attributes. Functions using this hook should accept the following arguments in order: |
| 345 |
|
| 346 |
* `$post_id` - the ID of the currently displayed Post/Page |
| 347 |
* `$show` - the value of the `show` attribute. If not set, defaults to "1970-Jan-01 00:00:00 +000" |
| 348 |
* `$hide` - the value of the `hide` attribute. If not set, defaults to "2038-Jan-19 03:14:07 +000" |
| 349 |
* `$content` - The content enclosed by the shortcode |
| 350 |
|
| 351 |
`add_action( "timed_content_server_hide", "{function_name}", {priority_level}, 4 );` |
| 352 |
|
| 353 |
Fired when the `[timed-content-server]` shortcode is encountered *AND* the content is to be hidden based on the shortcode's show/hide attributes. Functions using this hook should accept the following arguments in order: |
| 354 |
|
| 355 |
* `$post_id` - the ID of the currently displayed Post/Page |
| 356 |
* `$show` - the value of the `show` attribute. If not set, defaults to "1970-Jan-01 00:00:00 +000" |
| 357 |
* `$hide` - the value of the `hide` attribute. If not set, defaults to "2038-Jan-19 03:14:07 +000" |
| 358 |
* `$content` - The content enclosed by the shortcode |
| 359 |
|
| 360 |
`add_action( "timed_content_rule_show", "{function_name}", {priority_level}, 3 );` |
| 361 |
|
| 362 |
Fired when the `[timed-content-rule]` shortcode is encountered *AND* the content is to be displayed based on the Timed Content Rule's properties. Functions using this hook should accept the following arguments in order: |
| 363 |
|
| 364 |
* `$post_id` - the ID of the currently displayed Post/Page |
| 365 |
* `$rule_id` - the ID of the Timed Content Rule being called. Use `get_post_meta( $rule_id )` to get the Rule's properties. |
| 366 |
* `$content` - The content enclosed by the shortcode |
| 367 |
|
| 368 |
`add_action( "timed_content_rule_hide", "{function_name}", {priority_level}, 3 );` |
| 369 |
|
| 370 |
Fired when the `[timed-content-rule]` shortcode is encountered *AND* the content is to be hidden based on the Timed Content Rule's properties. Functions using this hook should accept the following arguments in order: |
| 371 |
|
| 372 |
* `$post_id` - the ID of the currently displayed Post/Page |
| 373 |
* `$rule_id` - the ID of the Timed Content Rule being called. Use `get_post_meta( $rule_id )` to get the Rule's properties. |
| 374 |
* `$content` - The content enclosed by the shortcode |
| 375 |
|
| 376 |
**Filter hooks** |
| 377 |
|
| 378 |
`timed_content_filter` |
| 379 |
|
| 380 |
Filter for any content enclosed by a Timed Content shortcode. Implements the same filters as `the_content`: |
| 381 |
|
| 382 |
* `wptexturize` |
| 383 |
* `convert_smilies` |
| 384 |
* `convert_chars` |
| 385 |
* `wpautop` |
| 386 |
* `prepend_attachment` |
| 387 |
* `do_shortcode` |
| 388 |
|
| 389 |
`timed_content_filter_override` |
| 390 |
|
| 391 |
Replaces the `timed_content_filter` with another pre-existing filter to use for any content enclosed by a Timed Content shortcode. Any function hooked into this filter must return the name of a filter (as a string). |
| 392 |
|
