For Developers

The Text Placeholder and Replacements add-on works out of the box. The following chapter provides a guide for developers on how to manipulate the replacing on a PHP level. It is no programming needed what so ever to use the add-on.

You can add, remove and change placeholder and their replacements by using the "Replacements" model class. All changes done by this class are only valid for the current page call. They are not saved in the database, unlike the values entered through the dashboard menu page. But you can overwright or remove entries from the menu page for the current page call. The class gives you even the possibility to replace HTML code.

To load the class use: Loader::model('replacements', 'text_placeholder_replacements');


Here are the functions the class Replacements provides:

    /**
     * Returns the placeholder and replacments in an array [["placeholder", "replacement", "raw", "reg"], ...] .
     *
     * The function returns a reference to the live array if you call it like $pairs = &Replacements::getAll().
     * Then you can minipulate it and it gets updated while you add and remove pairs directly or by using
     * the provided functions.
     *
     * @return    array
     */
    public static function &getAll()

    /**
     * Returns the replacement for a given placeholder.
     *
     * @param    $placeholder    the placeholder, including boundaries
     * @return    string
     */

    public static function get($placeholder)
    
    /**
     * Adds a placeholder - replacement pair.
     * Overwrites existing entries with the same placeholder.
     *
     * If $raw is not set, for special characters in the placeholder and replacement is
     * taken care of and html tags are skiped in the search for the placeholder.
     *
     * If $raw is set true, no further adjustments to the placeholder and replacement is done
     * and the whole html code, including tags, gets searched. No special treatment for
     * the search result page of concrete5 is performed. Use the raw setting if you want
     * to manipulate html code. The raw substitutions take place after all none raw entries
     * are replaced.
     *
     * You can provide a regular expression as a placeholder.
     * Regular expressions as placeholder only work if $raw and $reg is set true.
     * The regular expression replacements are performed before any other.
     *
     * @param    $placeholder    the placeholder, including boundaries, or regular expression
     * @param    $replacement    the replacement
     * @param    $raw            the raw setting (optional, default is false)
     * @param    $reg            is the placeholder a regular expression (optional, default is false)
     */     
 
    public static function add($placeholder, $replacement, $raw = false, $reg = false)
    
    /**
     * Removes all entries with the given placeholder.
     *
     * Be aware of that the substitutions take place after the page is fully build
     * and only the placeholder - replacement pairs which exist at this point matter.
     * So if you add a replacement at one point and remove it later on, it will not
     * exist at the moment of the actual substitutions.
     *
     * @param    $placeholder    the placeholder, including boundaries
     */
    public static function remove($placeholder)


Let's say you want to replace the "Built with ..." line at the bottom of the example page of concrete5. For the home page, which uses the default page type, you would open the file default.php of the greek yogurt theme and add the following code to the bottom of the file:

<?php
    Loader::model('replacements', 'text_placeholder_replacements');
    Replacements::add('Built with <a href="https://www.concrete5.org/" alt="Free Content Management System" target="_blank">concrete5 - an open source CMS</a>', 'Built by <a href="http://www.my-website.com" target="_blank">ME</a>', true);
?>

That's it! The same goes for all other page types.