Once ReReplacer is installed, you will be able to access it via the Regular Labs - ReReplacer menu link under Components. This brings you to the component view, which lists all the replacements you created.

To set up a replacement, you simply create a new item.

All you need for a ReReplacer item to work is a Title (for your personal reference) and something to Search for. You can make it Replace the searched text with something else, or simply remove it (by replacing it with nothing).

Optionally you can assign items to simple categories, which can then be used to filter by in the list view. And you can tweak how and where a replacement is done with 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, the first step is to create a new item in the ReReplacer component.
  2. Give it a Title, like: "Replace Cats with 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. You should see that all occurrences of 'Cats' have been replaced with 'Dogs'.

Multiple Replacements

Let's say you don't only want to replace 'Cats' with 'Dogs', but you also want to replace 'Kittens'.

You can do multiple searches into a single ReReplacer item, thanks to the "Treat as List" setting.

With this feature switched on, you will be able to enter a list of multiple words to search for, separated with a comma. For example: Cats,Kittens.

All the words in the search list will then 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

The various words in the "Search" field will be replaced with their respective word in the "Replace" field.

Notes:

  • Do not place spaces after the comma in a list search, unless you want to replace the space before the word too.
  • When the "Treat as List" setting is enabled, you must use [[comma]] to match actual commas.
  • When the "Treat as List" setting is not enabled, commas will be interpreted and matched as normal commas.

Word Search & Case Sensitivity

With above examples, you may have noticed, not only does the word 'Cats' get replaced, but also 'cats' (lowecase), as well as the part 'cats' inside 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" setting. Then the search will only match the word 'Cats' as a standalone word (it won't match cases where the string is preceded or followed by a letter).

But it will still match 'cats' (lowercase) and 'CATS' (uppercase) as words.

So you might also want to make it Case Sensitive. If you switch on that setting, the search will only match 'Cats', and it won't match 'cats' or 'CATS'.

Settings

Title Give the item a name.
Status You can use this to (temporarily) disable this item.
Description Give the item a short description telling you what it actually does. Everything following '---' will not be displayed in the list view.
Category Select or create a category to be displayed.
Search Normal search: A comma separated list of strings or a single search. Keep in mind that spaces are matches too. So don't place spaces after the commas when making a list (unless you want to match words with a leading space).

Regular Expression search: You can use all regular expression syntaxes known by php.
Replace Normal search: A comma separated list of strings. If no list is given, all searches will be replaced with this.
Regular Expression search: You can use the numbered back references (like: \1, \2).

Leave empty to remove the search(es).
Use 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.
Use 'newline' modifier When Regular Expressions is set to 'Yes':
When this modifier is used, a dot meta character (.) in the pattern matches all characters including newlines. Without it, newlines are excluded.
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 'cat' is not found in 'cats' or 'category', but is found in 'cat2' and 'cat-flap'.
Case sensitive If selected, the searches will be case sensitive. So 'cat' will not match 'CAT' or 'Cat'.
Maximum Replacements Set the maximum number of replacements to do.
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.
Strip Wrapping Paragraphs Select to always remove paragraph tags directly wrapping the search string.
Replace with PHP Select to be able to use PHP code in the replacement. You do still need to surround your PHP code with the PHP tags.