Adding custom placeholders

To create a new placeholder, you have to do two things:

1. Create a new class that implements \WPDesk\ShopMagic\Placeholder\Placeholder interface.
2. Inform the ShopMagic that a new placeholder is available.

Creating a new placeholder class

As interface \WPDesk\ShopMagic\Placeholder\Placeholder requires some more in-depth knowledge about Event->Placeholder interactions, we've created some intermediary abstracts to help you with the most common uses.

An abstract class already implements most of the required methods.

• For placeholders that require order data, we've prepared \WPDesk\ShopMagic\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder.
• For placeholders that require user data, we've prepared \WPDesk\ShopMagic\Placeholder\Builtin\UserBasedPlaceholder.
• For placeholders that require some new kind of data, you can extend \WPDesk\ShopMagic\Placeholder\BasicPlaceholder.

Creating a new placeholder that depends on the order data

To facilitate the creation of an order-dependant placeholder, it's best to extend \WPDesk\ShopMagic\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder class and override two primary methods: get_slug and value.

The get_slug method defines the shortcode for the placeholder. It should be in the {{order.placeholder_name}} format.

To further facilitate and standardize the naming convention, you can use a parent::get_slug method that returns a prefix based on the data required by the placeholder.

Example

A placeholder with shortcode {{order.some_name}} can have a slug defined as:

public function get_slug() {
    return parent::get_slug() . '.some_name';
}

or

public function get_slug() {
    return 'order.some_name';
}

The value method should return a value to substitute a placeholder shortcode. The value method receives only parameter: - optional array $parameters with the values of placeholder parameters.

Example

To substitute for {{order.download_url}} the order download url, you can use:

public function value( array $parameters ) {
    return $this->get_order()->download_url();
}

To add fallback for shortcode when download url is not available, you can use {{order.download_url | fallback:'https://shopmagic.app/' }}

public function value( array $parameters ) {
    $download_url = $this->get_order()->download_url();

    if ( empty( $download_url ) && ! empty( $parameters['fallback'] ) ) {
        return $parameters['fallback'];
    }

    return $this->get_order()->download_url();
}

Informing the ShopMagic plugin about a new placeholder

To integrate a newly created placeholder class, you should use a filter shopmagic/core/placeholders and add a new class to the placeholder hashmap.

Example

Let's create a new placeholder with a name {{order.nice_id}} that shows an interesting order id in the format "Your order id is: 11".

As we need the order to get the order id, that class depends on the WooCommerce WC_Order data.

namespace YourNamespace;

class NiceOrderId extends \WPDesk\ShopMagic\Placeholder\Builtin\WooCommerceOrderBasedPlaceholder {

    public function get_slug() {
        return parent::get_slug() . '.nice_id';
    }

   /**
    * @param array $parameters
    *
    * @return string
    */

    public function value( array $parameters ) {
        return "Your order id is: {$this->get_order()->get_id()}";
    }
}

Then we need to inform the ShopMagic placeholder factory using the shopmagic/core/placeholders filter.

/**
 * @param \WPDesk\ShopMagic\Placeholder\Placeholder[] $hashmap Hashmap with built in placeholders.
 *
 * @return \WPDesk\ShopMagic\Placeholder\Placeholder[] Hashmap with appended placeholder.
 */

function integrate_custom_shopmagic_placeholder( array $hashmap ) {
    require_once(__DIR__ . '/path/to/placeholder/class/if/no/autoloading/used.php');

    $hashmap[] = new \YourNamespace\NiceOrderId();
    return $hashmap;
}

add_filter('shopmagic/core/placeholders', 'integrate_custom_shopmagic_placeholder');