WordPress do_shortcode – The Shortcode API

WordPress do_shortcode – WordPress के 2.5 Version के साथ ही WordPress Core में Shortcode API को Include किया गया है। Shortcode API हमें ऐसे Simple Macro Code या Tag Syntax Create करने की सुविधा Provide करते हैं, जिन्हें हम हमारे WordPress Page/Post के Content के बीच Use कर सकते हैं व इन Shortcodes से Associated Function द्वारा Generate होने वाले Data या Content को Page/Post के Content के बीच Embed कर सकते हैं।

Shortcodes को हमेंशा [Square Bracket] के बीच Enclose किया जाता है। जैसे [ audio ], [ caption ], [ embed ], [ gallery ], [ video ], हालांकि ये पांचों WordPress के Reserved Shortcodes हैं, इसलिए हमें कभी भी इन्हें अपने Custom Shortcode के रूप में Use नहीं करना चाहिए।

Shortcodes को हमेंशा एक Handler Function Provide करते हुए लिखा जाता है। ये Shortcode Handlers मूलत: WordPress Filters के समान ही होते हैं, जो कि Parameters (Attributes) Accept करते हैं और Result यानी Shortcode द्वारा Generate होने वाला Output Return करते हैं।

Shortcodes के नाम के रूप में हम Lowercase व Uppercase Letters, Numbers व Underscore का प्रयोग कर सकते हैं लेकिन हमें नाम के बीच कभी भी Dash का प्रयोग नहीं करना चाहिए न ही Special Symbols का प्रयोग करना चाहिए। यानी हमें Variable Naming Conventions को पूरी तरह से Follow करना चाहिए।

Adding Shortcode Handler

Shortcode Handler Add करने के लिए WordPress हमें add_shortcode() नाम का एक API Function Provide करता है, जिसका प्रयोग WordPress Engine के साथ किसी Shortcode Handler Function को Register करने के लिए किया जाता है। इस API Function का Syntax कुछ निम्नानुसार होता है:

    add_shortcode(‘date‘, ‘showdate‘);

ये API Function दो Parameters Accept करता है, जहां पहला Parameter हमारे Newly Create होने वाले Tag को Represent करता है जबकि दूसरा Parameter उस Callback Function को Represent करता है, जो कि उस स्थान पर Content Return करता है, जिस स्थान पर WordPress Page/Post Content में उस Callback Function से Associated Tag को Use किया जाता है।

यदि हम उपरोक्त Code Line के अनुसार समझें, तो यहां ‘date’ वह Shortcode है, जिसे किसी WordPress Page/Post में Use किया जाएगा, जिसके स्थान पर वह Content Display होगा, जो showdate() नाम के Callback Function द्वारा Return होगा। इसे समझने के लिए हम निम्नानुसार एक Example Plugin Create कर सकते हैं:

<?php
/*
 *Plugin Name: Shortcode
 *Plugin URI: https://www.bccfalna.com/wpplugins/shortcode/
 *Description: Shortcode Demonstration
 *Author: Kuldeep Chand
 *Version: 1.0
 *Author URI: https://www.bccfalna.com/
 */
 
 add_shortcode('date', 'showdate');
 
 function showdate(){
 	return date("d F Y");
 }

जैसे ही हम इस Plugin को Create करके Activate करते हैं, हमारे Wordpress Engin के साथ [date], नाम का एक Tag यानी Shortcode Register हो जाता है। परिणामस्वरूप इस Shortcode Tag को हम हमारे Wordpress Engin के किसी भी Post/Page या Widget आदि में उस स्थान पर उपयोग में ले सकते हैं, जहां हमें Current Date को Display करना होता है। जैसे:

उपरोक्त चित्र में हमने एक नया Post Create किया है और उस Post में एक Heading2 Element के रूप में [date] Shortcode को Specify करके  Post को Update किया है। परिणामस्वरूप जब हम इस Post को Web Browser द्वारा Render करते हैं, तो हमें प्राप्त होने वाला Output अगले चित्रानुसार दिखाई देता है, जिसमें हमें [date] Shortcode Tag के स्थान पर Current Date दिखाई देता है:

ये Date हमें इसलिए दिखाई देता है, क्योंकि जैसे ही हमारा Plugin Activate होता है, हमारे Plugin का निम्न Statement Execute होता है:

    add_shortcode(‘date‘, ‘showdate‘);

ये Statement [date] नाम के Shortcode के साथ showdate() नाम के Callback Function को Associate कर देता है। परिणामस्वरूप हमने हमारे WordPress Page/Post में जहां कहीं पर भी [date] Shortcode को Use किया होता है, Parsing के दौरान हर उस स्थान पर showdate() Callback Function Call हो जाता है, जिसे हमने हमारे Plugin में निम्नानुसार Define किया है:

function showdate(){
 	return date("d F Y");
}

ये Function Execute होते ही [date] Shortcode वाले स्थान पर Current Date Return कर देता है। परिणामस्वरूप Exactly उसी स्थान पर Current Date Display हो जाता है।

Shortcode की विशेषता ये होती है कि हम हमारे Content में Dynamically Generate होने वाले Content को Display करवा सकते हैं जबकि उस Dynamically Generate होने वाले Content को Shortcode से Associated Callback Function Generate करता है।

इसलिए हमने जितने भी Page/Posts में Shortcode को Place किया होता है, उस हर Page/Post को Open करके Modify करने की जरूरत नहीं होती] बल्कि Shortcode से Associated Callback Function से Generate होने वाले Content को Modify करने मात्र से सभी Page/Posts के Contents Automatically Modify हो जाते हैं।

जिस तरह से हम किसी Function में अलग-अलग तरह के Parameters Pass करके उससे अलग-अलग तरह का Output Generate कर सकते हैं, उसी तरह से हम किसी Shortcode के माध्‍यम से भी Callback Function में Parameters Pass कर सकते हैं और उन Parameters को Callback Function द्वारा उपयोग में लेकर जरूरत के अनुसार अलग-अलग प्रकार का Output Generate कर सकते हैं। जैसे:

        [date dt=”d” mon=”F” year=”Y“]

किसी Shortcode के साथ हम जिस Callback Function को Associate करते हैं, वह Callback Function निम्नानुसार कुल तीन तरह के Arguments Accept कर सकता है:

$attrs Parameter

ये Parameter एक Associative Array होता है अथवा यदि Shortcode के साथ कोई भी Attribute Specify न करने की स्थिति में ये एक Empty String होता है।

$content Parameter

यदि Shortcode के साथ Content को Specify किया गया हो, तो ये Parameter, Enclosed Content को Represent करता है।

$tag Parameter

ये Shortcode Tag होता है जो कि Shard Callback Function की स्थिति में उपयोगी होता है।

इस प्रकार से यदि हम निम्नानुसार तरीके से एक Shortcode को Specify करें:

        [date dt=”d” mon=”F” year=”Y“]

तो इस Shortcode में Specified Attributes निम्नानुसार एक Associative Array के रूप में Convert हो जाता है जो कि Callback Handler Function के $attr Parameter को Pass हो जाता है:

        array( ‘dt‘=>’d‘, ‘mon‘=>’F‘, ‘year‘=>’Y‘)

यानी Shortcode में Specified Attribute के नाम इस Associative Array की Keys बन जाते हैं जबकि Shortcode में Specified Attribute के साथ Placed मान इस Associative Array की Values बन जाते हैं। इस Associative Array के विभिन्न Attributes के साथ प्रक्रिया करने के लिए WordPress हमें shortcode_atts() नाम का एक और API Function Provide करता है।