Adding custom placeholders
To create a new placeholder, you have to do two things:
- Create a new class that implements
\WPDesk\ShopMagic\Placeholder\Placeholder
interface. - 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');