WP Notices

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).

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.

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

Yes.

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

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.

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.

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.

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.

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