Help for WP Notices v1.2.2

WP Notices is a flexible way to display notices to readers.

Notices can be targeted by WordPress user role (admin, editor, contributor, author, subscriber, reader, anon or any other configured role), by WordPress capabilities (manage_plugins, read, delete_pages or any other configured capability) or targeted at a specific user.

Notice messages can be displayed as text or each message can be automatically converted to a PNG image. Useful for displaying advisory notices that you prefer search engines do not index as text. Useful for creating post images on the fly. The image directory is wiped periodically so download and move images to your WordPress media library if you want to keep them (remember to add them to the post as images from the media library).

The time or period of display can be set using natural language. Display notices forever (by leaving out a start and end time period), from a set start time to an open ended end date, for a specific day, range of days for one time or ad infinnitum. For example start="Thursday 8am" End="Friday" would display a notice every Thursday from 8am until start of Friday or start="Thursday 8am" End="Friday 4:30pm" would display a notice every Thursday from 8am until 4:30pm Friday; you can even say start="Wednesday 1st June 2016 8am" End="Friday 24th June 2016".

The notice can be styled to change its appearance. There are four inbuilt style classes (alert-success, alert-info, alert-warning and alert-danger).

There is a help message built into WP Notices. When using the WP Notices shortcode set help=\true\ to display the help information.

WP Notices is written to be used to display notices to specific users, user groups or to all readers. It can easily also be used as a flexible lightweight way to show page content to specific users (the style classes are optional) or as a membership plugin (though you would need to configure your membership roles manually).

WP Notices has been tested. It is known to work. If you find a bug, let us know. Support will be provided to fix bugs. We are busy with regular work duties so support may be slow on occasion and anyone who does not read the FAQs before posting a support request will be promptly pointed to read the FAQs.

Instructions

WP Notices is shortcode driven.

The shortcode with all attributes is:

[wp-notice to='admin' class='alert alert-success' css='' start='Tuesday 1pm' end='Tuesday 5pm' image='portrait' format='c4' files='pdf,html,png' html5='false' help='true']Message to display to admin users every Tuesday between 1pm and 5pm.[/wp-notice]

The shortcode has 10 attributes: to='', class='', css='', start='', end='', image='', format='', files='', html5='' and help=''.

to='' (required) is the addressee of the notice. This can be a WordPress user role, a WordPress capability or a registered username. Usernames must be prefixed with an @. See notes below for more details.
class='' (optional) but determines the design of the notice. Any custom CSS class can be used. The default CSS classes are alert-info, alert-success, alert-warning and alert-danger. These correspond to Bootstrap alerts.
css='' (optional) Add custom CSS to load inline or load the custom stylesheet stored in wp-content/uploads/wp-notices/css/custom.css. Use @ to load a file e.g. css='@'.
start='' and end='' (optional) attributes set the start date and end date for the notice to display. These attributes accept the time of day as well. These attributes accept natural language date and time expressions as well as regular year-month-day formats. You can specify times after the date such as start='2016-12-28 10pm' end='2016-12-28 11pm'. Unless a time is specified, the start date will begin at 12 midnight and the end date will end at 12 midnight e.g start='1st Jan 2016' end='2nd Jan 2016' will count as 24 hours i.e start of day on the 1st to start of day on the second. If no end date is given then the end date will always default to 'tomorrow' i.e. never expires. State no start date to show the message forever. Want the notice to display at a particular period of the day every day? Specify times without dates.
image='' (optional) is used to convert the notice into an image file. The image file is then displayed instead of any text. This is useful for when you prefer to not have text in a public notice indexed by a search engine. For example, you may need to display a sponsored post awareness message above posts; instead of displaying the message as text you can choose to display it as an image. The options are image='portrait' and image='landscape'. See the note below Custom Image Dimensions to learn how to specify exact image dimensions.
format='' (optional) is used to specify the paper sized format of the images. For example, A4, B4 or C4. Adjusting this setting could improve legibility of the text within the image. The default value is C4. See notes below for more information.
files='' (optional) Shows download links for HTML, PDF and PNG versions of the notice message. Separate each required file type with a comma e.g. files='pdf,html,png'. The download links expire one hour after creation.
html5='false' (optional) is used to disable HTML5 support for the PDF creator. HTML5 support is enabled by default. Only use this attribute if HTML renders poorly.
help='' (optional) Display link to shortcode help page and help messages (if any). Accepts a user role, user capability, username (@username) or admin.

The message displayed can contain any HTML that is allowed within regular post content such as <h1>, <p>, <em>, <strong>, <br>, <hr>, <ul> and so on. If you use HTML tags that do not show in the message then that will be because they were filtered out.

As well as regular WordPress user roles and capabilities, there are several aliases you can use in the to='' attribute. For example to='admin' is the same as to='administrator', use 'anon' to reach all none logged in users, use 'loggedin' to reach all loggedin users and use 'everyone' to display your message to everyone.

User roles, capabilities and usernames cannot currently be combined to reach multiple groups or multiple users.

User roles are role specific e.g. to='admin' will display a message to admin users but not to editors, authors, contributors or subscribers.

Notices that target user capabilities cascade upwards to users with higher capabilities but not downwards to those with lower capabilities e.g. if the notice is to='delete_others_pages' then editors and admins will see the message (they both share this capability) but authors, contributors and subscribers will not see the message.

Image inbuilt formats for format='' are ( format (width*height) ):

4a0 (4767.87, 6740.79)
2a0 (3370.39, 4767.87)
a0 (2383.94, 3370.39)
a1 (1683.78, 2383.94)
a2 (1190.55, 1683.78)
a3 (841.89, 1190.55)
a4 (595.28, 841.89)
a5 (419.53, 595.28)
a6 (297.64, 419.53)
a7 (209.76, 297.64)
a8 (147.40, 209.76)
a9 (104.88, 147.40)
a10 (73.70, 104.88)
b0 (2834.65, 4008.19)
b1 (2004.09, 2834.65)
b2 (1417.32, 2004.09)
b3 (1000.63, 1417.32)
b4 (708.66, 1000.63)
b5 (498.90, 708.66)
b6 (354.33, 498.90)
b7 (249.45, 354.33)
b8 (175.75, 249.45)
b9 (124.72, 175.75)
b10 (87.87, 124.72)
c0 (2599.37, 3676.54)
c1 (1836.85, 2599.37)
c2 (1298.27, 1836.85)
c3 (918.43, 1298.27)
c4 (649.13, 918.43)
c5 (459.21, 649.13)
c6 (323.15, 459.21)
c7 (229.61, 323.15)
c8 (161.57, 229.61)
c9 (113.39, 161.57)
c10 (79.37, 113.39)
ra0 (2437.80, 3458.27)
ra1 (1729.13, 2437.80)
ra2 (1218.90, 1729.13)
ra3 (864.57, 1218.90)
ra4 (609.45, 864.57)
sra0 (2551.18, 3628.35)
sra1 (1814.17, 2551.18)
sra2 (1275.59, 1814.17)
sra3 (907.09, 1275.59)
sra4 (637.80, 907.09)
letter (612.00, 792.00)
legal (612.00, 1008.00)
ledger (1224.00, 792.00)
tabloid (792.00, 1224.00)
executive (521.86, 756.00)
folio (612.00, 936.00)
commercial #10 envelope (684, 297)
catalog #10 1/2 envelope (648, 864)
8.5x11 (612.00, 792.00)
8.5x14 (612.00, 1008.0)
11x17 (792.00, 1224.00)

Custom Image Dimensions

Custom image dimensions can be set using the attributes image='' and format=''. Instead of using image='landscape' or image='portrait' you can use image='@number', replacing number with an actual integer value such as image='@400'. Use format='' to specify the height e.g. format='300' (the @ sign is optional for format). For example, to describe an image of 400 points by 800 points, use image='@400' format='800'.

Reference Links

PHP natural language time reference information (Relative Times).

WordPress roles and capabilities list. These are used in the "to" field.

Frequently Asked Questions

Why do iFrames and videos not show in image mode?

This is a limitation of the software used to create PDFs. In order to create images we first convert the notice message to PDF format. The PDF is then converted to an image. The image is what you see.

iFrame content will display as a non-clickable link.

Can I use images in the notice message?

Yes you can. Add the image as you normally would for a post or text widget.

Can I use shortcodes within the WP-Notices shortcode (nested shortcodes)?

Yes.

Can I use background images?

Yes. Either in the CSS or using the background='' attribute.

Can I use my own CSS?

Yes. Use the css='' attribute to add CSS style attributes. Use css='@' to load the custom.css stylesheet. The custom.css stylesheet is in wp-content/wp-uploads/wp-notices/SITE-ID/css/custom.css

We are still deciding whether to allow specific custom CSS files to be called. The option may be added at a future date.

Why does my notice message not include my CSS styles when image mode is used?

The CSS style rules must be loaded through css='' either as inline styles or through the custom.css file. This is because PDF creation (which leads to image creation) takes place outside of the WordPress core code.

Why do some messages still show after the message has expired?

This is caused by a limitation in cache plugins. We can either not cache pages that display notice messages (we're considering adding a nocache='' option but are worried notices shown in widget areas would then cause all pages to not be cached...) or we can ask you to clear the cache for specific pages or clear the cache for the whole site manually. We prefer to ask you to clear the page/site cache if you notice a message is cached too long.

We do send a 'Do Not Cache' alert to cache plugins for pages that display WP Notices to logged in readers. This prevents leakage to unintended readers.

Can I use the shortcode in widget areas?

You can. The WP Notices shortcode can be used in a text widget. Keep in mind that WP Notices sends a Do Not Cache alert to file cache plugins to prevent notice messages being displayed after expiration or to the wrong users. When you use WP Notices in a widget area you will need to use widget visibility controls, such as with the Jetpack Widget Visibility module, to narrow display of the text widget to only the pages where you want the widget to display. The next version of WP Notices will implement a method of notice display without need to disable page caching.

Where can I send donations?

Donations are welcome. They can be sent to us through [PayPal](https://paypal.me/vr51)

Can I contribute

Yes you can! Join us on [GitHub](https://github.com/VR51/WP-Notices/)