If you know a little php, adding the power of Magic Data token and symbol processing to your own blocks, packages and themes is trivial and can easily be incorporated with a few lines of code. For example, the Magic Data Templates addon provides direct processing of Magic Data symbols within the standard Content and HTML blocks.

Important: This howto has been updated to use best practices for Magic Data 2.9.5+.

If you want to provide similar integration with your own blocks, templates or addons, you can do so with simple calls to a standard MagicDataSymbolsHelper.

Magic Data is known to be installed

If you know an up-to-date copy of Magic Data is already installed on a site, the simplest way is to use the symbols helper provided by Magic Data.

$mdsh = Loader::helper('md_evaluate', 'jl_magic_data');
$text = $mdsh -> fill_and_template($text);

Any Magic Data tokens within $text will then be expanded.

That is it, if your block, package or theme knows Magic Data is installed, you can simply use the above two lines of code and do not need to read any further.

Magic Data may not be installed

For blocks, packages or themes that need to also work without Magic Data, a simple solution would be to test for the Magic Data package being installed before using the code snippet above.

However, by using a helper within your own package, any repeated tests for installation can be avoided and the overall evaluation can be more efficient. The first snippet of code is similar, save that a symbols helper is loaded from your own package.

$mdsh = Loader::helper('magic_data_symbols', 'your_package_name');
$text = $mdsh -> fill_and_template($text);

Now your package code will be completely independent of whether Magic Data is installed or not. Just copy this helper file into your package helpers/ folder.

class MagicDataSymbolsHelper {

  static $md_pkg;
  static $mdsh;

  public function __construct(){
    MagicDataSymbolsHelper::$md_pkg  = Package::getByHandle('jl_magic_data');
  if (is_object(MagicDataSymbolsHelper::$md_pkg)){
      MagicDataSymbolsHelper::$mdsh = Loader::helper('md_evaluate', 'jl_magic_data');
    }
  }

  public function confirm_installed(){
    return is_object(MagicDataSymbolsHelper::$mdsh);
  }

  public function fill_and_template($content){
    if ($this->confirm_installed()){
      return MagicDataSymbolsHelper::$mdsh->fill_and_template($content);
    }
    return $content;
  }
}

You can also define this helper as a root level helper. Rather than re-enter the code, just help yourself to a copy of the helper from Magic Data Templates and adjust the package name to suit where you load it.

Developers who have used earlier versions of this code may notice the method is now called fill_and_template(). This method includes optional wrapping of the content from Magic Data styling symbols for 'inner' and 'outer' styles. The previous method fill() remains valid, but will not apply any Magic Data styling to content.

Your block or addon package is now Magic Data enabled. On systems where Magic Data is not installed, the text will simply be returned un-processed. Where Magic Data is installed, any tokens found within the text will be processed by Magic Data and you can display the processed text.

If you want to be more sophisticated, you can use the method confirm_installed() to enable/disable edit dialogue options or dashboard options for including Magic Data with your addon.

The code on this page is free to use for any developer wanting to integrate with Magic Data. For the helper, just copy the file from Magic Data Templates.

Read more How-tos by JohntheFish.