{"id":767,"date":"2008-03-28T12:35:30","date_gmt":"2008-03-28T10:35:30","guid":{"rendered":"http:\/\/planetozh.com\/blog\/2008\/03\/wordpress-25-shortcodes-api-overview\/"},"modified":"2008-03-29T11:44:18","modified_gmt":"2008-03-29T09:44:18","slug":"wordpress-25-shortcodes-api-overview","status":"publish","type":"post","link":"https:\/\/planetozh.com\/blog\/2008\/03\/wordpress-25-shortcodes-api-overview\/","title":{"rendered":"WordPress 2.5 ShortCodes API Overview"},"content":{"rendered":"

WordPress 2.5 comes with a very handy API that plugin authors should love: shortcodes, ie. BBcode-like tags, that are parsed when found in post contents. The API is very easy to use, and well done enough that it's relatively foolproof.<\/p>\n

Shortcode types<\/h2>\n

The API allows for all the possible combinations and forms you'd think of: selfclosing or open tags, attributes with single or double quotes.<\/p>\n

\n\n\t\t
\n\n\t\t
\n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
code<\/div>\n\n\t\t\n\t\t
\n\n\t<\/div>\n\t\n\t
\n\t\t
  1. [tag]<\/div><\/li>\n
  2. [tag \/]<\/div><\/li>\n
  3. [tag attribute="value" \/]<\/div><\/li>\n
  4. [tag attr1='value1' attr2="value2" ]<\/div><\/li>\n
  5. [tag]enclosed content[\/tag]<\/div><\/li>\n
  6. [tag attr="value"]enclosed content[\/tag]<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

    The Concept<\/h2>\n

    First, you have to define a function that will take care of your shortcodes, their potential attributes, and any enclosed content:<\/p>\n

    \n\n\t\t
    \n\n\t\t
    \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
    php<\/div>\n\n\t\t\n\t\t
    \n\n\t<\/div>\n\t\n\t
    \n\t\t
    1. function<\/span> my_shortcode_func(<\/span>$attr<\/span>,<\/span> $content<\/span>)<\/span> {<\/span><\/div><\/li>\n
    2.     \/\/ $attr is an array of $key=>$value pairs<\/span><\/div><\/li>\n
    3.     \/\/ $content is a string containing the enclosed content<\/span><\/div><\/li>\n
    4.     \/\/ ... do something with $attr and $content<\/span><\/div><\/li>\n
    5.     \/\/ return the expected result<\/span><\/div><\/li>\n
    6. }<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

      Then, to register your new shortcode so that [tag attr="value"]content[\/tag] is processed as wished by my_shortcode_func(), you just add:<\/p>\n

      \n\n\t\t
      \n\n\t\t
      \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
      php<\/div>\n\n\t\t\n\t\t
      \n\n\t<\/div>\n\t\n\t
      \n\t\t
      1. add_shortcode(<\/span>'tag'<\/span>,<\/span> 'my_shortcode_func'<\/span>)<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

        All API functions<\/h2>\n

        The API comes with a set of mostly self explanatory functions you can use:<\/p>\n

        \n\n\t\t
        \n\n\t\t
        \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
        php<\/div>\n\n\t\t\n\t\t
        \n\n\t<\/div>\n\t\n\t
        \n\t\t
        1. add_shortcode(<\/span>'tag'<\/span>,<\/span> 'function_name'<\/span>)<\/span>;<\/span> \/\/ register a new shortcode<\/span><\/div><\/li>\n
        2. remove_shortcode(<\/span>'tag'<\/span>)<\/span>;<\/span> \/\/ unregister<\/span><\/div><\/li>\n
        3. remove_all_shortcodes(<\/span>)<\/span>;<\/span> \/\/ just as it says<\/span><\/div><\/li>\n
        4. $return<\/span> =<\/span> do_shortcode(<\/span>$content<\/span>)<\/span>;<\/span> \/\/ apply shortcodes to content without echoing anything<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

          Examples<\/h2>\n

          [tag1] → Some Longer Text<\/h3>\n
          \n\n\t\t
          \n\n\t\t
          \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
          php<\/div>\n\n\t\t\n\t\t
          \n\n\t<\/div>\n\t\n\t
          \n\t\t
          1. function<\/span> shortcode_example1(<\/span>)<\/span> {<\/span><\/div><\/li>\n
          2.     return<\/span> 'Some Longer Text'<\/span>;<\/span><\/div><\/li>\n
          3. }<\/span><\/div><\/li>\n
          4. add_shortcode(<\/span>'tag1'<\/span>,<\/span> 'shortcode_example1'<\/span>)<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

            [tag2 param="something"] → Some Longer Text and something<\/h3>\n
            \n\n\t\t
            \n\n\t\t
            \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
            php<\/div>\n\n\t\t\n\t\t
            \n\n\t<\/div>\n\t\n\t
            \n\t\t
            1. function<\/span> shortcode_example2(<\/span>$attr<\/span>)<\/span> {<\/span><\/div><\/li>\n
            2.     return<\/span> 'Some Longer Text and '<\/span>.<\/span>$attr<\/span>[<\/span>'param'<\/span>]<\/span>;<\/span><\/div><\/li>\n
            3. }<\/span><\/div><\/li>\n
            4. add_shortcode(<\/span>'tag2'<\/span>,<\/span> 'shortcode_example2'<\/span>)<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

              [tag3]something[\/tag3] → You just said "something", didn't you ?<\/h3>\n
              \n\n\t\t
              \n\n\t\t
              \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
              php<\/div>\n\n\t\t\n\t\t
              \n\n\t<\/div>\n\t\n\t
              \n\t\t
              1. function<\/span> shortcode_example3(<\/span>$attr<\/span>,<\/span> $content<\/span>)<\/span> {<\/span><\/div><\/li>\n
              2.     return<\/span> "You just said '$content<\/span>', didn't you ?"<\/span>;<\/span><\/div><\/li>\n
              3. }<\/span><\/div><\/li>\n
              4. add_shortcode(<\/span>'tag3'<\/span>,<\/span> 'shortcode_example3'<\/span>)<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

                [tag4 any attribute]something[\/tag4] → Attributes: {list of attributes}. Content: {content}<\/h3>\n
                \n\n\t\t
                \n\n\t\t
                \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
                php<\/div>\n\n\t\t\n\t\t
                \n\n\t<\/div>\n\t\n\t
                \n\t\t
                1. function<\/span> shortcode_example4(<\/span>$attr<\/span>,<\/span> $content<\/span>)<\/span> {<\/span><\/div><\/li>\n
                2.     $attributes<\/span> =<\/span> ''<\/span>;<\/span><\/div><\/li>\n
                3.     foreach<\/span> (<\/span>$attr<\/span> as<\/span> $key<\/span>=><\/span>$value<\/span>)<\/span> {<\/span><\/div><\/li>\n
                4.         $attributes<\/span> .=<\/span> "$key<\/span>: $value<\/span>\\n<\/span>"<\/span>;<\/span><\/div><\/li>\n
                5.     }<\/span><\/div><\/li>\n
                6.     return<\/span> "Attributes: $attributes<\/span><br\/>Content: $content<\/span>"<\/span>;<\/span><\/div><\/li>\n
                7. }<\/span><\/div><\/li>\n
                8. add_shortcode(<\/span>'tag4'<\/span>,<\/span> 'shortcode_example4'<\/span>)<\/span>;<\/span><\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

                  Experiment and read more<\/h2>\n

                  Test and experiment: all the examples above are gathered into this simple Shortcodes plugin example<\/a> (rename as shortcodes.php and put in your plugin directory). It's interesting to try to break things with unexpected attributes or enclosed content: the API is pretty foolproof and should ignore things just as you'd thought it should.<\/p>\n

                  Read more : the whole API can be found in wp-includes\/shortcodes.php and is relatively well commented. Jacob Santos also has a nice and detailed overview of the API<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"

                  WordPress 2.5 comes with a very handy API that plugin authors should love: shortcodes, ie. BBcode-like tags, that are parsed when found in post contents. The API is very easy to use, and well done enough that it's relatively foolproof. Shortcode types The API allows for all the possible combinations and forms you'd think of: […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[21],"tags":[2,10,287,245],"class_list":["post-767","post","type-post","status-publish","format-standard","hentry","category-published","tag-code","tag-php","tag-shortcodes","tag-wordpress"],"_links":{"self":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/767","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/comments?post=767"}],"version-history":[{"count":0,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/posts\/767\/revisions"}],"wp:attachment":[{"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/media?parent=767"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/categories?post=767"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/planetozh.com\/blog\/wp-json\/wp\/v2\/tags?post=767"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}