Tutorial:

Introduction

ReReplacer is a Joomla! component (and system plugin).

ReReplacer enables you to search and replace virtually anything in your website on-the-fly.

It functions on the HTML level of your website, so you can replace any piece of HTML you can find

You can search for stuff and replace it with something else. Or remove it (by replacing it with nothing).

ReReplacer supports the powerful Regular Expressions.

Setting up a replacement

In ReReplacer you add a new item for every type of replacement you need.

All you need for a ReReplacer item to function is a name and something to search for. You can make it replace the searched text with something else, or make it remove it.
Optionally you can tweak how and where the replacement is done by a multitude of extra settings.

Simple replacement

We'll start with a very simple word replacement. Let's say you want to replace all occurrences of Cats with Dogs.

  1. So first step is to create a new item in the ReReplacer component.
  2. Give it a name, like: 'Cats to Dogs'.
  3. Then in the Search field place: Cats
  4. And in the Replace field place: Dogs
  5. Save the item

And that's it! You just created your first replacement.

To test this replacement, create an article and place the word 'Cats' in it a couple of times. Then view the article in your frontend website. And you should see that all occurrences of 'Cats' have been replaced with 'Dogs'.

Lists

You can place multiple searches into one ReReplacer item.

Let's say you not only want to replace 'Cats' with 'Dogs', but also 'Kittens'.
All you have to do is place a comma separated list in the search: Cats,Kittens

Don't forget to switch on the 'Treat as Lists' option!

All words in the search list will get replaced by the replace string

But what if you want to replace 'Cats' with 'Dogs', but replace 'Kittens' with 'Puppies'?

Then you simply make a list in the replace field too.

So search for:

Cats,Kittens

And replace with:

Dogs,Puppies

Note: do not place spaces after the comma's in a list search, unless you want to replace the space before the word too

Word Search & Case sensitivity

With above examples, you may have noticed, not only does the word 'Cats' get replaced, but also 'cats' and also the part 'cats' in other words. So 'Copycats' becomes 'CopyDogs'.

You might want that and then it's fine. But if not, you have a couple of settings to make the search smarter.

Firstly you can switch on the Word Search option. Then the search will only match the word 'Cats' as a standalone word. But it will also match 'cats' and 'CATS' as words.

So you might also want to make it Case Sensitive. If you switch on that option, it will only match 'Cats' and not 'cats' or 'CATS'.

Dynamic Tags

Here is an overview of extra codes and dynamic tags you can/should use in different situations.
Note: The user tag places data from the logged in user. If the visitor is not logged in, the tag will be removed.

SyntaxDescriptionInput exampleOutput exampleNormalRegExSearchReplace
[[comma]] Use instead of a comma. Use normal commas to create lists. [[comma]] , Yes No Yes Yes
[[space]] Use instead of leading and trailing spaces (otherwise they will get stripped upon saving). [[space]]   Yes Yes Yes Yes
[[user:id]] The id number of the user. [[user:id]] 465 Yes Yes No Yes
[[user:username]] The login name of the user. [[user:username]] peter Yes Yes No Yes
[[user:name]] The name of the user. [[user:name]] Peter van Westen Yes Yes No Yes
[[user:…]] Any other available data from the user or the connected contact. [[user:misc]]

I am in charge of buying fruit. If you sell good fruit, contact me.

Yes Yes No Yes
[[date:…]] Date using php strftime() format. [[date:%A, %d %B %Y]] Friday, 17 August 2018 Yes Yes No Yes
[[random:…-…]] This places a random number within the given range. [[random:0-100]] 83 Yes Yes No Yes
[[counter]] This places the number of the occurrence.
If your search is found, say, 4 times, the count will show respectively 1 to 4.
[[counter]] 1 Yes Yes No Yes
Use to escape dynamic values (add slashes to quotes). \\1 "It\'s a string!" No Yes No Yes
… Convert text within tags to uppercase. \1 "IT'S A STRING!" No Yes No Yes
Convert text within tags to lowercase. \1 "it's a string!" No Yes No Yes

Search Areas

Under the Search Areas tab you will find a number of settings to control in what areas on the page the replacement should be done.

Enable in area

The main setting under this tab is the Enable in area settings.
Here you define in what major area on the page the replacement should be done.

If you don't know what to choose, leaving this to Everywhere is usually fine.

  • Articles (and Categories)
    Only in articles from the article manager. So not in forum articles, for instance. And also not in articles shown through modules.
  • Content (not in modules)
    In the main area of your site. So in all components, but not in modules and other elements outside the main area.
  • Head (not in body)
    Only in the head section of the html (the top part containing the title and other meta tags).
  • Body (not in head)
    In the whole site except the head of the html.
  • Everywhere
    In the whole site, so also in the head of the html.

Some more in-depth information about the underlying process. Skip this part if it is too complex for you.

The choice you make here not only determines in what area the replacement is done, but also at what stage in the rendering process of the page the replacement is done.

During the rendering of the page, ReReplacer gets triggered 3 times.

  • Content Prepare
    This is the stage where the articles are prepared for further handling.
    Replacements using area Articles (and Categories) will be run at this stage.
  • After Dispatch
    At this stage the main content for the page has been generated. This concerns the 'component' area. So this does not include any modules yet.
    Replacements using area Content (not in modules) will be run at this stage.
    PS: After this stage it is no longer possible to add scripts/styles to the page through php commands.
  • After Render
    The is the last stage in the process, before the final html gets passed to the browser. So this includes all the html, including the 'componet' area, all modules and the 'head' section of the html (which contains the site title, meta tags and possible script and style tags). All other Replacements will be run at this stage. So Body (not in head), Head (not in body) and Everywhere.

Regular Expressions

ReReplacer supports the use of powerful regular expressions to search and replace. This opens up endless possibilities. You can do virtually everything with ReReplacer.

Example

I'll explain with another example.

Let's say you want to create your own little dynamic tag to place images of animals quickly and easily. So '{animal Cat}' will place your Cat.jpg image, and '{animal Dog}' will place Dog.jpg, etc.

The search field should contain:

\{animal (.*?)\}

And the replace field something like:

<img src="/images/animals/\1.jpg" alt="\1" />

And don't forget to switch on the 'Regular Expressions' option!

I'll explain the search a little:

In regular expressions there are a lot of special characters that have special meanings. To search for the actual character, you need to 'escape' it with a backward slash.
The { and } have special meanings in regular expressions, so to match the actual { and } you need to escape \{ and \}.

The (.*?) has a few funky bits of magic going on. This regex satement is used very often. It pretty much means: grab all the text (till you find the character after this statement: '}').
The ( and ) make sure that all that the statement matches is stored so you can use it in the replacement.

So then we come to the replacement. That is pretty much all standard html, except the \1 part. That refers to the captured bit in the search: (.*?). And contains the value 'Cats' or 'Dogs' or whatever you placed inside the {animal} tag in your article.

More on Regular Expressions

For documentation on regular expressions, ReReplacer comes with a Regular Expressions Cheat Sheet (under the Dynamic Tags section in the ReReplacer item edit view).

For more info on Regular Expressions: http://www.regular-expressions.info/reference.html
For testing them: http://gskinner.com/RegExr, http://regexpal.com, http://www.phpliveregex.com

Handle with care!

Because you can replace/remove all kinds of things, you can potentially break your site. It is not wise replacing words like 'html', 'body' or (parts of) words that are used in inline scripts.

However, the cool thing is: all replacements are not permanent. So when you turn off the plugin or remove the replacement, your website is back to the original state.

Also, there are some nifty features enabling you to replace stuff without replacing in fragile areas like inside tags and outside the html body.

Replace with PHP Pro only

The Pro version of ReReplacer gives you the ability to replace with dynamic php code. Now you can replace simple words or pieces of html with complete php code snippets.

Example

Say you want to replace a tag containing a userid, username or name with a table containing some details of the user, like name, email address and registration date.

So we can use these tags: [usertable 123], [usertable peter] or [usertable Peter van Westen]

Like explained in the Regular Expression example, we can create the dynamic search string like:

\[usertable (.*?)\]

In the replace field we can place the required php code inside <?php an ?> tags:

<?php
$query = $db->getQuery(true)
->select('name, email, registerDate') ->from('#__users') ->where('id = ' . $db->q('\1') . ' OR username = ' . $db->q('\1') . ' OR name = ' . $db->q('\1')); $db->setQuery($query); $user = $db->loadObject(); if ($user) { echo ' <table> <tr> <td>Name:</td> <td>' . $user->name . '</td> </tr> <tr> <td>Email:</td> <td>' . $user->email . '</td> </tr> <tr> <td>Registered on:</td> <td>' . $user->registerDate . '</td> </tr> </table> '; } ?>

For long blocks of php/html you can also choose to place the code in an external file and simply include it.

So in the replace field you can place:

<?php
$myvar = '\1';
include JPATH_SITE . '/myfiles/file.php';
?>

With above code, you can use the php variable $myvar in the external file. Of course, you can name it anything you want.

Item Settings

ReReplacer is packed with options, giving you control over how it works and behaves.

Here is the full list of the options you can find in the ReReplacer item settings:

Details

Published You can use this to (temporarily) disable this item.
Title Give the item a name.
Description Give the item a short description telling you what it actually does. Everything following '---' will not be displayed in the list view.
Category Choose a category from the list.
Use an XML File Select to use an xml file instead of the search/replace fields. With an xml file you can define multiple searches within one file.
Regular Expressions Select to treat the searches and replaces as regular expressions.
Treat as List If selected, the search and replace strings will be treated as lists. Use comma's to separate the different list items. You must use [[comma]] to match actual comma's.

If not selected, comma's will be interpreted as normal comma's and the search and replace strings will not be treated as list.
Word Search Only handle whole words. It is considered a whole word if it is not preceded or followed by a letter.

So 'foo' is not found in 'foobar' or 'foot', but is found in 'foo3' and 'foo-bar'.
Use 'newline' modifier When this modifier is used, a dot meta character (.) in the pattern matches all characters, including newlines.
Case sensitive If selected, the searches will be case sensitive. So 'word' will not match 'WORD' or 'Word'.
Thorough If selected, the search will also replace new matches created by the replacement.

Do not use this if your replacement always creates a new match. If you do anyway, ReReplacer will only do the replacement for that match 100 times and then move on to the next match.
Treat as PHP Select to treat the replacement as PHP code.

Search Areas

Enable in area The replacement will only be done in the content, title and author name of the article(s).

The replacement will only be done in the content, title and author name of the article(s).

Options: Articles (and Categories), Content (not in modules), Head (not in body), Body (not in head), Everywhere
Enable in title If enabled, the replacements will also be done in the article titles.
Enable in feeds If enabled, the replacements will also be done in the website's feeds.
Enable in Admin Enabled in Admin! If your search/replace has errors, it could prevent you from entering your administrator! Are you sure?
Enable in edit forms Also replace in edit forms?
Only enable this if you really need to and you know what you are doing. Generally you do NOT want replacements to be done inside the input fields of edit forms.
Only between (start/end) The search will only take place between the given (html) code. This only works if both the start and end field are entered.

The search will be done within the smallest possible part between the start and end codes.
Example:
If you replace 'x' by 'y' between '123' and '456':
123 xxx 123 xxx 456 xxx 456
will be replaced by:
123 xxx 123 yyy 456 xxx 456

(You cannot use regular expressions in these fields.)

Tags

Enable in HTML tags If enabled, the replacements will also be done within HTML tags. You can also choose to do the replacements only within tags. This regards the actual tags <...>, not what is between a open and close tag.
Limit to tag selection If enabled, the replacements will only be done within selected tags and tag parameters. Otherwise searches will be done within all tags.
Tag selection A list of permitted tags and parameters to do the searches in. This regards the actual tags <...>, not what is between a open and close tag.
Use an asterisk to permit all tags/parameters. The syntax of this list is like this:

tag_name_1[parameter_name_1, parameter_name_2] tag_name_2[parameter_name_1, parameter_name_2]

Example (permits search in the values of the 'alt' and 'title' of all tags, permits search in the whole 'a' tag):

*[alt,title] a[*]

Publishing Assignments Pro only

ReReplacer - Publishing Assignments

The last tab in the item edit view contains an enourmous amount of assignment options.

By using the assignment options, you can determine where or when a replacement is done.

This way you can - for example - create replacements only for certain user groups. Or only available during certain seasons. Or only withing certain extensions (components).

The last field in that tab is an Else field. You can optionally tell ReReplacer to replace your search with something else in case the assignments do not mach.
For example, you can replace [WELCOME] with a specific welcome text for all your registered users, and with some other text for non-registered users (guests).
Or replace {price} with $10 in the winter and $12 for the other seasons.

You can also leave the Else field empty to make it remove the searched content in case the assignments do not match.

Configuration Settings

There are also some global configuration settings to control stuff for the ReReplacer component.

Show search and replace fields Select whether to show the search and replace fields in the list by default.
Contact Database Table The contact table is used in case you use the dynamic user tag.

If you use a 3rd party contact extension, you can change what contact database table to use. This only works for tables where the user id is stored in the user_id field.
Show Update Notification If selected, an update notification will be shown in the main component view when there is a new version for this extension.
Show Copyright If selected, extra copyright info will be displayed in the admin views. Regular Labs extensions never show copyright info or backlinks on the frontend.
Free vs Pro:

Create unlimited replacements
Case sensitive searches
Use Regular Expressions

Replace with PHP::You can place PHP code in the replacement. This can create truely dynamic replacements.
Use XML files::Have a lot of replacements that are very alike? Place them in one XML file instead of loads of separate replacement items.
Search between options::Make the replacement only happen between ceratain content/html.
Limit/disable in tags options::Define exactly in what tags the replacement should/shouldn't happen.
Advanced publishing assignments::Make assignments only happen on the pages or in the situations you want.

Examples:

As you will see with all these replacements, you are the one that decides what to search for and what to replace it with.

These are just some examples to get an idea of what you can do. You are of course free to modify these to fit your needs.

Simple text/html replacements

These are some examples of straight-forward text replacements.

Shortcut for Company details

With this example you can place 'COMPANY DETAILS' anywhere in your content and it will get replaced by nicely styled details, including links and images. Saves a lot of time!

Usage:

COMPANY DETAILS

Result:

Regular Labs
www.RegularLabs.com
Follow me on Twitter
Like me on Facebook

Search:

Enable the Case sensitive option.

COMPANY DETAILS

Replace:

<strong>Regular Labs</strong><br>
<a href="https://www.regularlabs.com">www.RegularLabs.com</a><br>
<a href="https://twitter.com/RegularLabs" target="_blank"><img src="https://regl.io/logo_twitter.png">Follow me on Twitter</a><br>
<a href="https://www.facebook.com/regularlabs" target="_blank"><img src="https://regl.io/logo_facebook.png">Like me on Facebook</a>

Add styling to words

This example adds a span with a classname to all occurrences of 'My Company Name'.
Once you have a classname, you can style it any way you want through css. Like changing the text color and size. Adding borders and backgrounds. Or even adding icons before or after it.

Search:

My Company Name

Replace:

<span class="my-special-class">My Company Name</span>

This replacement can however replace itself multiple times, as the result also contains what you are searching for.
I recommend you make sure the search text is not inside the final replaced output.
For instance, you can add extra spaces which your browser will ignore anyway, like:

<span class="my-special-class">My   Company   Name</span>

 

Or make this smarter via Regular Expressions.
In the following example, it will only replace 'My Company Name' if it is not followed by a < character.

Enable the Regular Expressions option.

Search:

My Company Name([^<])

Replace:

<span class="my-special-class">My Company Name</span>\1

Translating words to your desired language

In Joomla, pretty much all texts are taken from Language Files. This makes Joomla and extensions easily translatable.
However, not all extensions implement this correctly everywhere.

The best solution is of course to notify the extension developer and have it get fixed. But this does not always happen.
Instead of hacking the code of the extension, you can easily fix this through ReReplacer.

In this example we will be changing the word 'Cart' used in a shopping extension, for example, to 'Basket'.

Search:

class="shopping-cart">Cart</a>

Replace:

class="shopping-cart">Basket</a>

So the 'trick' here is to just add some unique html found surrounding the word in the html output of your page.

Note: With the Pro version of ReReplacer you can assign replacements to languages. This way you can make a different replacement per language.

Changing texts used in extensions to something else

The best solution is to see if these can be changed via the Language Overrides.

If not, see the above example.

Complex html replacements

These are some examples of more complex replacements done with the help of Regular Expressions.

Changing layout of extensions

Let's say you have an extension that outputs an image, then a paragraph of text and then a button. But you want this flipped around. So first the button, then the text, then the image.

In many cases - if the extension is coded well - this can be achieved via template overrides. However this is often quite some work and sometimes not possible.
With ReReplacer you can manipulate the output html in pretty much any way you want.

Ok, so let's take this as the html you find in the html output of your website.

<div class="panel">
	<img src="/path/to/some/image.png" alt="My Image">
	<p>Some text</p>
	<a href="/some/url.html" class="btn">Click here</a>
</div>

And you want this instead:

<div class="panel">
	<a href="/some/url.html" class="btn">Click here</a>
	<p>Some text</p>
	<img src="/path/to/some/image.png" alt="My Image">
</div>

No doing this via a simple text replacement will not work, because the text, image and url of the button are dynamic.

So we can use Regular Expressions.

Search:

(<div class="panel">)\s*(<img [^>]*>)\s*(<p>.*?</p>)\s*(<a [^>]* class="btn">.*?</a>)\s*(</div>)

Replace:

In the search, we are placing the different parts in groups, by surrounding stuff in parentheses (...).
We can then reference the captured text in these groups via \1, \2, \3, etc.
So all we need to do in the replacement is rearrange the order:

\1 \4 \3 \2 \5

Dynamic plugin-style tags

ReReplacer makes it possible and easy to make your own little custom plugin-style tags.
This means you can place a simple little text like {mytag} in your content that (usually dynamically) gets replaced with something more complex.

The below examples will use this curly bracket syntax. But you can implement it in whatever syntax you want.
So instead of {mytag} you might want to use something like [[mytag]] or __MYTAG__ or something completely different.
Because YOU write what to search for, YOU decide what the syntax of the tag should be.

Icon tag

This tag makes it easy to place font based icons.

Icon packages like Icomoon or Font Awesome give you a great way of placing icons on your site.
However, if you want to place these in your content, you generally have to switch to the html view and mess around in there.
Also, your editor might not even show the icon and maybe even strip it away when saving the article or item.
This tag solves that.

PS: Here is an overview of all the Icomoon icons available in Joomla!

Usage:

{icon joomla} {icon eye} {icon image} {icon star}

Result:

Search:

Enable the Regular Expressions option.

{icon (.*?)}

Replace:

<span class="icon-\1"></span>

Joomla Language string tag

This tag enables you to place language strings in your content. These will be passed through the Joomla language strings.

This requires the use of PHP code in the replacement, which is only available in the Pro version of ReReplacer.

Note: This will only work for language strings in language files that are loaded on the page. If you have your own custom language file you want to load, you need to force-load it in the php replacement.

Usage:

{translate JGLOBAL_SECRETKEY_HELP}

Result:

If you have enabled two factor authentication in your user account please enter your secret key. If you do not know what this means, you can leave this field blank.

Search:

Enable the Regular Expressions option.

{translate (.*?)}

Replace:

Enable the Treat as PHP option

<?php echo JText::_('\1'); ?>

Youtube video tag

Usage:

{youtube IEe7wbxez34}

Result:

Search:

Enable the Regular Expressions option.

{youtube (.*?)}

This search is very simple, but also very 'stupid'. It will not remove any surrounding <p> tags. And it doesn't check for the correct syntax in the youtube id.
This is a more complex but better Regular Expressions search:

(?:<p>)?\{youtube(?:\s|&nbsp;|&#160;)+([a-z0-9-_]+)\}(?:</p>)?

Replace:

<iframe width="200" height="113" src="https://www.youtube.com/embed/\1" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>

Vimeo video tag

Following the example for the Youtube tag above, you can do the same for a Vimeo tag.

Usage:

{vimeo 227088346}

Result:

Search:

Enable the Regular Expressions option.

{vimeo (.*?)}

Or better:

(?:<p>)?\{vimeo(?:\s|&nbsp;|&#160;)+([a-z0-9]+)\}(?:</p>)?

Replace:

<iframe width="200" height="113" src="https://player.vimeo.com/video/\1" frameborder="0" allowfullscreen></iframe>

Youtube modal popup tag

Instead of placing the video directly into your content (like done in the examples above), you might want to have it pop up in a modal. You can use ReReplacer to output Modals tags.
Note: The plugin ordering is important. When using ReReplacer to output code that needs to be handled by other Joomla plugins, make sure you order the ReReplacer system plugin before the others.

Usage:

{youtube IEe7wbxez34}

Result:

Search:

Enable the Regular Expressions option.

{youtube (.*?)}

Or better:

(?:<p>)?\{youtube(?:\s|&nbsp;|&#160;)+([a-z0-9-_]+)\}(?:</p>)?

Replace:

{modal url="https://www.youtube.com/embed/\1?autoplay=1&amp;rel=0"}
<img src="//img.youtube.com/vi/\1/mqdefault.jpg" alt="" />
{/modal}

Vimeo modal popup tag

Following the example for the Youtube tag above, you can do the same for a Vimeo tag.

Usage:

{vimeo 227088346}

Result:

Search:

Enable the Regular Expressions option.

{vimeo (.*?)}

Or better:

(?:<p>)?\{vimeo(?:\s|&nbsp;|&#160;)+([a-z0-9]+)\}(?:</p>)?

Replace:

Note: There is no way to directly link to the Vimeo thumbnail image. So you can either create your own, or use this custom php script.

{modal url="https://player.vimeo.com/video/\1?autoplay=1"}
<img src="/path/to/my/vimeo_image.php?id=\1" alt="" />
{/modal}

With ReReplacer you can replace whatever you want in your entire site.

It can work on the entire output of your site, so you can also do replacements in things like the meta tags.

Some ideas where you can use ReReplacer for:

  • Create your own custom tags ([mytag]some text[/mytag] becomes some text).
  • Tweak the output of Joomla! without changing the core joomla or extension files.
  • Filter bad words on your site.
  • Temporarily hide text from your website, without actually removing it.
  • Remove redundant whitespace from your code, making your website load faster.
  • Use abbreviations in your content and replace them with the full text (J! becomes Joomla!, COMP becomes My Very Long Company Name®).
  • Quickly place whole blocks of text by only typing one word. For instance, you can use [stats] and replace it with a piece of Google Statistics code. Or [footer] to put a fixed bit of text under articles. You can change the replacement in one place (in ReReplacer) and your whole website is updated!
  • etc...

You have the ability to use powerful Regular Expressions to search and replace. This opens up endless possibilities. You can do virtually everything with ReReplacer.