to dirprocess: writing shortcodes                                     rev 21 apr 2020

Category: web:cms:cp/wp


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] &nbsp;</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/
    


_______________________________________________________
begin 12 may 2020
-- 0 --