Placeholders

Pimcore Placeholders are usefull when you have a text (e.g. a wysiwyg editor) and you want to embedd dynamic values within this text.

Most of the time you will use Placeholders in combination with Email Documents and the Pimcore_Mail Class.

The Syntax of a Placeholder is "%PLACEHOLDERNAME(PARAMETERKEY,JSON-CONFIG);"

Example usage

Lets assume you have a text "Thank you for the order of "PRODUCTNAME"" and you want replace "PRODUCTNAME" with the real Product name.

The following code-snippet replaces the Placeholder "%Object(...);" with the Product name.

$text = 'Thank you for the order of "%Object(object_id,{"method" : "getName"});"';
$placeholder = new Pimcore_Placeholder();

$params = array('object_id' => 73613,
                        'locale' => 'de_DE');
echo $replaced = $placeholder->replacePlaceholders($text,$params);

More detailed:

The replacePlaceholders() method accepts 3 parameter:

When you call the replacePlaceholders() method, it determines the placeholders and creates the corresponding placeholder object.

Create your own Placeholders

You can also create your own placeholder. By default it is assumed that your individual placehodlers are located in /website/lib/Website/Placeholder/YourPlaceholder.php .
If you want to change the default placeholder location you can call "Pimcore_Placeholder::setWebsiteClassPrefix(...)" to change the location (make sure you set them before any individual placeholder is called).

E.g. "Pimcore_Placeholder::setWebsiteClassPrefix('Website_Tool_');" -> the placeholder location would be "/website/lib/Website/Tool/YourPlaceholder.php"

Now we assuem that we want to create a simple Placeholder that replaces the data of a person.

Therefore we create a new class that extends "Pimcore_Placeholder_Abstract". Our class has to implement at least 2 methods "getTestValue()" and "getReplacement()".
Note: The getTestValue() is currently not in use but in upcoming releases it will be used for test replacements.

The "getReplacement()" method has to return the value that sould be used for the replacement of the placeholder.
The "getTestValue()" method sould return a value for testing purpose.

<?php
class Website_Placeholder_Person extends Pimcore_Placeholder_Abstract
{

    public function getTestValue()
    {
        $value = '';
        switch ($this->getPlaceholderKey()) {
            case 'firstName' :
                $value = 'Homer';
                break;
            case 'lastName' :
                $value = 'Simpson';
                break;
            //...
        }
        return '<span class="testValue">' . $value . ' </span>';
    }

    public function getReplacement()
    {
        $value = $this->getValue();

        //$document would contain the document that we passed as third parameter to the replacePlaceholders() method
        $document = $this->getDocument();

        switch ($this->getPlaceholderKey()) {
            case 'firstName' :
                return ucfirst($value);
                break;
            case 'lastName'  :
                return ucfirst($value);
                break;
            case 'salutation' :
                if ($value == 'mr') {
                    return 'Dear mr.';
                } elseif ($value == 'mrs') {
                    return 'Dear mrs.';
                }
                break;
        }
    }
}

Example usage:

    public function ownPlaceholderAction(){
        $this->disableViewAutoRender();
        $text = '%Person(salutation); %Person(firstName); %Person(lastName); thank you for your order.';
        $placeholder = new Pimcore_Placeholder();

        $params = array('firstName' =>'Pim',
                        'lastName' => 'Core',
                        'salutation' => 'mr');

        $replaced = $placeholder->replacePlaceholders($text,$params,Document::getById(1));
        echo $replaced;
    }

As all Placeholders must extend the class Pimcore_Placeholder_Abstract there are some getters you can use in your Placeholders.