ReReplacer

Advanced search and replace for Joomla!

  • Last updated: 26-Nov-2018
  • Version: 8.6.0
  • Types: Component System plugin
  • Joomla rating: 100%

Tutorial for ReReplacer

There is a Free and a Pro version of ReReplacer.
The parts in this tutorial that only concern the Pro version will be marked with: Pro only

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]] Tuesday, 11 December 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
H 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.

Installation

You can either install ReReplacer by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful Regular Labs Extension Manager.

Note: When updating ReReplacer, you do not need to uninstall it first. The package will update all the files automatically.

Keep in mind that when you update to a major new version (or uninstall first), you might lose some configuration settings.

Regular Labs Extension Manager

It is very easy to install/update any Regular Labs Extension using the Regular Labs Extension Manager.

Please see the Tutorial for the Regular Labs Extension Manager for more detailed information...

Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps:

  1. Log into your Joomla administrator;
  2. In the menu, choose: Extensions >> Extensions;
  3. Choose the tab: Install from Web (or enable it if you haven't done so yet);
  4. Select the search field and enter ReReplacer and hit enter;
  5. Click on the ReReplacer listing;
  6. Click on Install;
  7. Click on Install to confirm.
Installer Web

Or if you need to install the Pro version or cannot install via the 'Install via Web' method for some reason:

  1. Download the extension install file (.zip);
  2. Log into your Joomla administrator;
  3. In the menu, choose: Extensions >> Extensions;
  4. Choose the tab: Upload Package File;
  5. Click on the Choose File button and select the extension zip;
  6. Click on Upload & Install.
Installer Upload

If you have problems installing ReReplacer, please try the manual installation process as described here: docs.joomla.org/Installing_an_extension