WP Notices

How to Use

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.5×11 (612.00, 792.00)
• 8.5×14 (612.00, 1008.0)
• 11×17 (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.

Questions and Answers

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

1.2.4 – 9th September 2016

• Why, oh, why SVN… 1.2.4 Released to correct release error when this plugin was uploaded to SVN tag 1.2.2 and 1.2.3

1.2.3 – 9th September 2016

• Dummy Release: Corrected SVN upload error to tag 1.2.2

1.2.2 – 9th September 2016

• WordPress 4.6.1 compatibility flag
• Updated DOMPDF
• Moved dompdf directory from includes/dompdf to includes/vendor/dompdf. This fits in better with dompdf files being built via Composer

1.2.1 – 26th June 2016

• Added option to choose which download links to display of the files for PDF, HTML and PNG.
• Separated file creation into individual functions. Now file generation can happen whether images are created or not, but only if files=” is set e.g. files=’html,pdf’ or files=’html,pdf,png’.
• Added multisite compatibility.
• Forced no-caching of pages that display content to site members.
• Began process of converting the plugin into a class.

1.2.0 – 25th June 2016

• Security improvement. DOMPDF directory is renamed on plugin activation. The new name is created via a randomly generated sha2 hash. Directory name is created on plugin installation and is created afresh on reinstallation.
• New css=” attribute. This is used to specify inline CSS for the alert or to specify a custom CSS file to load from wp-notices/css (an upcoming version of WP Notices will include an options screen for CSS file management)
• Activation routine. Install directories wp-content/wp-notices/css and wp-content/wp-notices/tmp
• Deactivation routine. Plugin deactivation removes scheduled event and deletes the dirctory wp-notices/tmp. wp-notices/css remains intact in case it contains custom CSS files.
• Added file download feature. Files created during image creation can now be downloaded. Set files=’true’ to display a link below the image notice. A future update of WP Notices will move file creation to a separate process and thereby permit file downloads for none image notices too.

1.1.0 – 24th June 2016

• Enabled HTML5 support for dompdf. Enabled by default.
• Introduced new shortcode attribute to disable HTML5 support. html5=”. Set to fals to disable HTML5 support.
• Fixed typos in plugin index.php. The intro info needed a few fixes.
• Enabled nested shortcode support. Notices can include shortcodes.
• Added filter to enable oEmbeds and shortcodes in text widgets. Undecided whether to keep this filter in index.php or move it to the FAQ section.
• Added test for ImageMagick support. Conversion of PDFs to images requires ImageMagick. No ImageMagick = no image creation. Help message when enabled displays warning when ImageMagick is not enabled.
• Adjusted help=” attribute to accept @username, a WordPress user role, WordPress user capability or admin as the intended viewer of the help notice.
• Added option to set custom image dimensions using image=’@number’ format=’number’ (width & height).

1.0.0 – First Public Release

23rd June 2016