Shortcodes:Override Plugin Shortcodes

From e107 Wiki
Jump to: navigation, search

e107 Wiki: English | Русский | Deutsch | Français | Magyar | Português | Български | Česky | Nederlands | Ελληνικά | Italiano | Norske | Polska | Slovenščina | Español | Svenska | Translate: Wiki | Page

logo_wiki.png

Current Release 1.0.4 | e107.org | Download | Changelog | Forum | Plugins | Themes | RSS Feed of Latest Changes | Atom Feed of Latest Changes


e107 Shortcode Guide
Main page > I : First Aid > II : Development > III : Administration > IV : How To's > V : Plugin Writing > VI : Theming & Shortcodes



Contents

Warning

This is an example of customising e107 base code, albeit a minor one. Only follow this procedure if you KNOW WHAT YOU ARE DOING.

Scope

There are a lot of ways to use and implement shortcodes. This discussion relates to overriding shortcodes in a shortcodes.php file such as content_shortcodes.php from Content Management Plugin by lisa.

Why Override?

Suppose you want to make a minor change to a shortcode or add a new shortcode to a plugin for use in a template. You can modify the plugin shortcode file directly but you will have to make multiple changes during each upgrade. After parsing, the shortcodes file is stored as an array. You can easily add to this array and override/add new shortcodes.

The Code Change

At the top of the shortcode file, add the following one-line of code:

$shortcodes_variable = array_merge ($shortcodes_variable, $tp -> e_sc -> parse_scbatch("your_shortcode_file.php"));

You then create your_shortcode_file.php with the name of the existing shortcode if you want to override or the name of a new shortcode.

Example from Content Management

At the top of my content_shortcodes.php file I have the following:

if (!defined('e107_INIT')) { exit; }
include_once(e_HANDLER.'shortcode_handler.php');
$content_shortcodes = $tp -> e_sc -> parse_scbatch(__FILE__);
//KMD custom code below
$content_shortcodes = array_merge ($content_shortcodes, $tp -> e_sc -> parse_scbatch(THEME."KMD_shortcodes.php"));
//

I also created a "KMD_shortcodes.php" file in my theme directory which looks something like:


<?php
if (!defined('e107_INIT')) { exit; }
include_once(e_HANDLER.'shortcode_handler.php');
$KMD_shortcodes = $tp -> e_sc -> parse_scbatch(__FILE__);

//returns the author's name without a hyperlink
SC_BEGIN CONTENT_AUTHOR_NOLINK
global  $row, $aa, $CONTENT_AUTHOR_NOLINK;
$author_array	= $aa -> getAuthor($row['content_author']);
$CONTENT_AUTHOR_NOLINK = $author_array[1];
return $CONTENT_AUTHOR_NOLINK;
SC_END

...lots of other shortcodes...

?>

And that is pretty much it.

Troubleshooting

Keep in mind that - as always - you cannot always add shorcodes to every variable in a template. You have to look at the source code to make sure that the variable is ultimately parsed. For example, look for a line like:

$content_type_table_string .= $tp -> parseTemplate($CONTENT_TYPE_TABLE, FALSE, $content_shortcodes);

So if your shortcode puts out {MY_SNAZZY_SHORTCODE} on the screen instead of the HTML you were expecting, you probably have declared a variable that isn't parsed.

e107 developers: I'm begging you...

Finally, a couple of quick unsolicited opinions/requests for the e107 developers.

Use Shortcodes and Templates

Shortcodes are a great way to separate the display from the code. Please use them wherever possible and declare your variables containing HTML-generated code in templates. Look at lisa's example with Content Management. Although his template system was difficult for me to follow at first, his approach is absolutely the way to go.

Enable Formatting

Always, always, always return the shortcode variables as (from the example above)

$CONTENT_AUTHOR_NOLINK = $author_array[1];
return $CONTENT_AUTHOR_NOLINK;
and not
$ret = $author_array[1];
return $ret;

That way we can format them as in Shortcodes:Formatting. Again, lisa has done a great job with this in Content Management.

Enable shortcode overriding/extending

The custom code above can be added to any shortcode.php file along the lines of "if file exists extend this array with...."

Allow shortcodes to be added to all template variables

Parse ALL of your template variables containing HTML with $tp->parseTemplate. This way we can add shortcodes anywhere we want and can cut down on the number of customisations. There are other ways to add shortcodes but it will be must easier for everyone if we develop a consistent approach.

Sorry for the rant.

WARNING

Changes to e107 base code may be lost when you upgrade. Take lots of notes about your code change! Post Upgrade you will need to re-implement the changes if you still wish to use them. This will make the upgrade process for you much slower. You are advised to leave e107 base code alone, instead, use a plugin from a verified source.