to dir<![CDATA[process: writing shortcodes rev 21 apr 2020
Category: web:cms:cp/wp
➤ how-tos↓ general issues↓ security↓ using shortcodes↓
more how-tos↓ references↓
Shortcodes can be really useful.
Also can be maintenance nightmare if not clear,
not secure, not well-documented.
.......................................................
➢ how-tos:
o specs:
* Shortcode
https://developer.wordpress.org/plugins/shortcodes/
https://developer.wordpress.org/apis/handbook/shortcode/
https://codex.wordpress.org/Shortcode
https://codex.wordpress.org/Function_Reference/shortcode_atts
WP Codex
* Shortcode API
https://codex.wordpress.org/Shortcode_API
WP Codex
* WordPress Shortcodes: Complete Guide
https://www.smashingmagazine.com/2012/05/wordpress-shortcodes-complete-guide/
SmashingMagazine.com
[may 2012]
o how-tos and examples:
* https://premium.wpmudev.org/blog/10-awesome-shortcodes-for-your-wordpress-blog/
* https://www.smashingmagazine.com/2012/05/wordpress-shortcodes-complete-guide/
+ Using in a plugin, needs to wait until WordPress is initialized,
so use init action hook.
https://developer.wordpress.org/plugins/shortcodes/basic-shortcodes/
* Security:
+ Validate the data
- https://developer.wordpress.org/plugins/security/data-validation/
- https://codex.wordpress.org/Validating_Sanitizing_and_Escaping_User_Data
+ Sanitize the input and escape the output.
- easiest way to sanitize data is with built-in WordPress functions sanitize_*
- https://codex.wordpress.org/Validating_Sanitizing_and_Escaping_User_Data
- https://developer.wordpress.org/plugins/security/securing-input/
- https://developer.wordpress.org/themes/theme-security/data-sanitization-escaping/
* Shortcodes with Parameters - Extracting the attributes
+ Don't use extract() - since 2009!
- it looks like a nice function but it is insecure, and has bad side effects.
- even deprecated by wordpress coding standards.
- https://blog.josephscott.org/2009/02/05/i-dont-like-phps-extract-function/
- https://core.trac.wordpress.org/ticket/22400
+ How to get the attributes:
3 of them have defaults, 'q' has no default.
...............................
// get the atts:
$h_args = shortcode_atts(
array(
'w' => '500',
'h' => '330',
'q' => '',
'geo' => 'US',
),
$atts
);
// clean the atts:
$w = (int) $h_args['w'];
$h = (int) $h_args['h'];
$q = esc_attr( $h_args['q'] );
...............................
+ tutorial on attributes:
https://pippinsplugins.com/shortcodes-101-shortcode-attributes/
+ Function reference: shortcode_atts()
https://codex.wordpress.org/Function_Reference/shortcode_atts
+ Shortcodes with Parameters
https://developer.wordpress.org/plugins/shortcodes/shortcodes-with-parameters/
WP Developer Manual
+ https://wordpress.stackexchange.com/questions/266896/how-to-get-shortcodes-input-values-inside-a-filter
StackExchange [2017]
+ Multiple Parameters for a Shortcode
https://wordpress.stackexchange.com/questions/84450/multiple-parameters-for-a-shortcode
StackExchange [2013]
+ Adding an array parameter to a Wordpress shortcode
https://www.experts-exchange.com/questions/29066779/Adding-an-array-parameter-to-a-Wordpress-shortcode-PHP-script.html
Experts-Exchange.com [6 nov 2017]
* 7 Essential Tips for Using Shortcodes in WordPress
https://www.wpbeginner.com/beginners-guide/7-essential-tips-for-using-shortcodes-in-wordpress/
WPBeginner.com [5 apr 2018]
* Example simple shortcode function:
https://pippinsplugins.com/shortcodes-101-shortcode-attributes/
* Example complex shortcode function "gallery", by WordPress:
https://core.trac.wordpress.org/browser/tags/5.2.1/src/wp-includes/media.php#L0
function gallery_shortcode()
.......................................................
➢ writing shortcodes: general issues and infos
o Can't use hyphens in shortcode names.
https://developer.wordpress.org/apis/handbook/shortcode/#hyphens
I do see hyphens in shortcode names for
contact-form-7, contact-form, and cfdb-*
(hmmm these are all contact form 7 shortcodes).
And they work fine.
I would rather use hyphens as it's easier to type.
Guess i will start using nothing - like, drglink, drgscript
o Can use hyphens in shortcode attributes.
https://developer.wordpress.org/apis/handbook/shortcode/#attributes
Attribute names can have: letters, digits, underscore, hyphen.
o Using shortcode _between_ html tags, causes the html tags to be removed (by wp?)
[11 aug 2018]
ex: <p>[reg_fee_info]</p>
<p> [reg_fee_info] </p>
<p> [reg_fee_info] </p>
only thing that stopped it was actual text inserted:
<p> [reg_fee_info] Thank you.</p>
or
put shortcode on separate line (can do if have Raw HTML -> Disable auto para enabled.)
another solution: pass tag to shortcode function
[reg_fee_info tag="p"]
might want class or id in the tag. so it gets complicated (quotes).
o Using shortcode _within_ html tags ...
- https://wordpress.stackexchange.com/questions/241634/how-do-i-use-shortcodes-inside-of-html-tags
- https://wpseek.com/function/do_shortcodes_in_html_tags/
o Using shortcode in a widget.
- Yes you can.
- This feature is not enabled by default in WordPress.
If you can’t see your shortcode in a widget,
add this code in your theme’s functions.php file
(or a site-specific plugin).
-- https://www.wpbeginner.com/beginners-guide/7-essential-tips-for-using-shortcodes-in-wordpress/
o Using shortcode in a theme file.
- Yes you can.
- <?php echo do_shortcode( "[example_shortcode]" ); ?>
o Prefix your shortcode names with some unique string
namespaces!
also make them easier to search for,
and will group together in shortcode-reference
.......................................................
➢ writing shortcodes: security
o Data validation process:
* https://developer.wordpress.org/plugins/security/data-validation/
* https://developer.wordpress.org/plugins/security/securing-output/
* https://codex.wordpress.org/Validating_Sanitizing_and_Escaping_User_Data
sanitize_*() class of helper functions
o wordpress functions for security:
* sanitize_text_field()
https://duckduckgo.com/?q=sanitize_text_field()
https://developer.wordpress.org/reference/functions/sanitize_text_field/
* sanitize_textarea_field()
https://duckduckgo.com/?q=sanitize_textarea_field()
https://developer.wordpress.org/reference/functions/sanitize_textarea_field/
* wp_check_invalid_utf8()
https://duckduckgo.com/?q=wp_check_invalid_utf8()
https://developer.wordpress.org/reference/functions/wp_check_invalid_utf8/
* wp_wp_strip_all_tags()
https://duckduckgo.com/?q=wp_strip_all_tags()
https://developer.wordpress.org/reference/functions/wp_strip_all_tags/
o php functions for security:
.......................................................
➢ using shortcodes: broken shortcodes
o this can happen if a plugin or theme is changed/deleted
o Solutions:
1. Manually remove the shortcode from every post.
2. Hide the broken shortcode with this;
add_shortcode( 'shortcodetag', '__return_false' );
This adds back the orphan shortcode with no output.
https://www.wpbeginner.com/beginners-guide/7-essential-tips-for-using-shortcodes-in-wordpress/
3. Write code to find them:
https://www.wpbeginner.com/wp-tutorials/how-to-find-and-remove-unused-shortcodes-from-wordpress-posts/
4. Plugins:
These are nice because
You don't have to know exactly what to remove/hide.
They will intercept the WordPress filter that
processes shortcodes, and detect which ones
are not being used.
They don't remove the shortcode from the content,
just stop it from displaying (in case you want to use it again later).
https://wordpress.org/plugins/remove-orphan-shortcodes/
Does just that. no options.
https://wordpress.org/plugins/hide-broken-shortcodes/
Provides filters to allow you to customize what,
if anything, gets displayed when a broken shortcode
is encountered.
.......................................................
➢ auxiliary how-tos:
o Display shortcodes used in site:
* Plugin Shortcode Reference
https://wordpress.org/plugins/shortcode-reference/
- This is nice. It displays all shortcodes available.
Lists built-in shortcodes, then those from plugins,
then those from your theme.
- It also picks up comments to your shortcode function
if you write them as PHPDocs (i.e., start with '/**').
So you can put usage info in there, like what parameters
for the shortcode, and then as user you can remember
what they are.
- i am using it - as of jun 2018.
o adding a button in editor to insert a shortcode:
* How to, at StackExchange
https://wordpress.stackexchange.com/questions/72394/how-to-add-a-shortcode-button-to-the-tinymce-editor
o using multiple shortcodes for one function:
* Three good use cases
https://code.tutsplus.com/tutorials/multiple-shortcodes-with-a-single-function-3-killer-examples--wp-30966
o seven useful tips for using shortcodes:
* future-proof: add in a plugin, not in theme.
* use in widgets.
* find shortcodes used in posts (also there's a plugin for that)
https://www.wpbeginner.com/beginners-guide/7-essential-tips-for-using-shortcodes-in-wordpress/
.......................................................
➢ references:
PHPDoc Blocks
@link https://en.wikipedia.org/wiki/PHPDoc
@link https://docs.phpdoc.org/references/phpdoc/
@link https://docs.phpdoc.org/guides/docblocks.html
PHPDoc Markdown
@link https://sourceforge.net/p/phpdocu/wiki/markdown_syntax/
WordPress Shortcodes
@link https://developer.wordpress.org/plugins/shortcodes/
Useful plugins
@link https://developer.wordpress.org/plugins/shortcode-reference/
@link https://developer.wordpress.org/plugins/shortcodes-finder/
_______________________________________________________
begin 12 may 2020
-- 0 --
]]>