User Guide

ReReplacer

Download Free Buy Pro   € 30

1) Introduction

This guide provides in-depth information about ReReplacer and will tell you:

  • what it does
  • how to install it
  • how to set-up and use it

2) What is ReReplacer?

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.

3) 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.

3.1) 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'.

3.2) 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

3.3) 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'.

 

4) 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="http://images.nonumber.nl/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 view 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 Syntax Help button). 

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

5) 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.

6) Combining ReReplacer and Sourcerer

With Sourcerer you can place php code in your content.

When you combine ReReplacer and Sourcerer you can replace stuff 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 Sourcerers {source} tags with the required php code inside:

{source}<?php
$query = $db->getQuery(true);
$query->select('name, email, registerDate');
$query->from('#__users');
$query->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>
    ';
}
?>{/source}

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

So in the replace field you can place:

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

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

7) 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.
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 an XML File PRO ONLY Select to use an xml file instead of the search/replace fields. With an xml file you can define multiple searches within one file.
XML File (from root) PRO ONLY The path of the XML file relative to the root of the website.
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 commas to separate the different list items. You must use to match actual commas.

If not selected, commas will be interpreted as normal commas 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.

Search Areas

Enable in area Select where to do the searches.

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.

Body (not in head)
In the whole site exept the head of the html (like in title and other meta tags)

Everywhere
In de whole site, so also in the head of the html.
Enable in title If enabled, the replacements will also be done in the article titles.
RR_ENABLE_IN_AUTHOR RR_ENABLE_IN_AUTHOR_DESC
Enable in feeds text RR_ENABLE_IN_FEEDS_DESC}
Enable in Admin If enabled, the replacements will also be done in the Administrator.

Be careful!
Only activate this if you really need to.
If your search/replace has errors, it could prevent you from entering your administrator!
Only between (start)
Only between (end) PRO ONLY
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 PRO ONLY

Enable in 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

Matching Method Should all or any assignments be matched?

ALL
Will be published if ALL of below assignments are matched.

ANY
Will be published if ANY (one or more) of below assignments are matched.
Assignment groups where 'Ignore' is selected will be ignored.
Show Assignments Select whether to only show the selected assignments. You can use this to get a clean overview of the active assignments.

Menu Items

Menu Items Select the menu items to assign to.
Also on child items Also assign to child items of the selected items?
Include no Itemid Also assign when no menu Itemid is set in URL?

Home Page

Unlike selecting the home page (default) item via the Menu Items, this will only match the real home page, not any URL that has the same Itemid as the home menu item.

This might not work for all 3rd party SEF extensions.

Date & Time

The date and time assignments use the date/time of your servers, not that of the visitors system.

Date

Start Publishing Enter the date to start publishing
Finish Publishing Enter the date to end publishing

Seasons

Seasons Select seasons to assign to.
Hemisphere Select the hemisphere your website is located in

Months

Months Select months to assign to.

Days of the week

Days of the week Select days of the week to assign to.

Time

Start Publishing Enter the time to start publishing.

Format: 23:59
Finish Publishing Enter the time to end publishing.

Format: 23:59

Users

User Group Levels

User Groups Select the user groups to assign to.

Users

User IDs Enter the user ids to assign to. Use commas to separate ids.

Languages

Languages Select the languages to assign to.

Geolocating

Geolocating is not always 100% accurate. The geolocation is based on the IP address of the visitor. Not all IP addresses are fixed or known.

geoPlugin is used for geolocating.

Continents Select the continents to assign to.
Countries Select the countries to assign to.
Regions / States Select the regions / states to assign to.

Templates

Templates Select the templates to assign to.

URL

URL matches Enter (part of) the URLs to match.
Use a new line for each different match.
Use Regular Expressions Select to treat the value as regular expressions.

Url parts will be matched using regular expressions. So make sure the string uses valid regex syntax.

Operating Systems

Operating Systems Select the operating systems to assign to. Keep in mind that operating system detection is not always 100% accurate. Users can setup their browser to mimic other operating systems.

Browsers

Browsers Select the browsers to assign to. Keep in mind that browser detection is not always 100% accurate. Users can setup their browser to mimic other browsers
Mobile Browsers

Components

Components Select the components to assign to.

Joomla! Content

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Articles Select the articles to assign to.
Article Keywords Enter the (meta) keywords to assign to. Use commas to separate the keywords.

FLEXIcontent

Page types Select on what page types the assignment should be active.
Tags Enter the tags to assign to. Use commas to separate the tags.
Types Select the types to assign to.

K2

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Types Select the types to assign to.
Items Select the items to assign to.

ZOO

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Items Select the items to assign to.

Akeeba Subscriptions

Page types Select on what page types the assignment should be active.
Levels Select the levels to assign to.

HikaShop

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Products Select the items to assign to.

RedShop

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Products Select the items to assign to.

VirtueMart

Page types Select on what page types the assignment should be active.
Categories Select the categories to assign to.
Products Select the items to assign to.

Cookie Confirm PRO ONLY

Cookies allowed Assign to whether cookies are allowed or disallowed, based on the configuration of Cookie Confirm (by Twentronix) and the visitor's choice to accept or decline cookies.

Custom PHP

Custom PHP Enter a piece of PHP code to evaluate. The code must return the value true or false.

For instance:

$user = JFactory:‍:getUser();
return ( $user->name == 'Peter van Westen' );

Else

Else Select whether to replace with something else if assignments are not matched.
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).

8) Requirements

ReReplacer will only work correctly if your setup meets these requirements:

  • Up-to-date version of Joomla:
    • Joomla 2.5.10 or higher
    • Joomla 3.2.2 or higher
  • PHP 5.3+ ( No PHP 5.2 support! )
  • PHP mbstring (Multibyte String) functions enabled
  • MySQL 5+

Important: I can only provide support for setups that:

  • meet the above requirements;
  • do not have extension files or Joomla! core files which have been altered in any way.

9) Installation

You can either install ReReplacer by using the core extension manager available in the Joomla! Administrator Control Panel, or by using the powerful NoNumber 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.

9.1) NoNumber Extension Manager

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

Please see the User Guide for the NoNumber Extension Manager for more detailed information...

NoNumber Extension Manager

9.2) Joomla! Extension Manager

To install via the Joomla! Extension Manager, just follow these steps (based on Joomla 2.5 setup):

  1. Download the extension zip.
  2. Log into your Joomla administrator
  3. In the menu, choose: Extensions >> Extension Manager
  4. Under 'Upload Package File' select the extension zip.
  5. Click on 'Upload & Install'
Joomla! Installer

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

10) Uninstallation

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

If you no longer use any NoNumber extensions, you can also uninstall the NoNumber Framework plugin by using the Joomla! core extension manager.