To add substitutions to your clone, open your clone in the control panel and click Substitution rules in the side menu. You will then see a table where you can manage your substitution rules. The table consists of two text fields, three checkboxes for options, a button to remove or add a rule and arrows that will allow you to change the order of rules.
It takes about 30 to 60 seconds to make changes to substitutions and substitution exclusions. If a rule still doesn't seem to work after two minutes, it's best to check that the rule is completely correct.
How substitutions work
To use substitutions properly, it is important to understand how they work. The most important thing to know is that all rules are applied simultaneously. This may sound confusing, so we'd like to explain it to you using an animation. While evaluating rules, the following rules are used to choose between two conflicting rules:
- If rule a has more characters matched than rule b, then rule a takes precedence over rule b.
- When two rules have the same number of characters matched, the rule higher in the table wins.
Below is an animation in which five (overlapping) rules are applied to a piece of source code. In this animation, the words hit and miss are used to indicate whether or not a rule can match a character. To the right of the rule, you can see how many characters a rule has already matched.
In the animation, you can see that a conflict first arises between the lines
book. In this case, both rules have matched 4 characters and therefore the order is considered. Because
bookcase is above
book, the entire match of
book is rejected and nothing is done with this rule. A moment later, a conflict arises between the rules
bookcase. Both rules have a full match. Because in this case
bookshelf has matched more characters than
book this rule wins and the rule
bookshelf will be applied. After one rule is applied, all other rules will be reset and all must start over.
With each substitution, you have three boxes that you can check. These are options that you can turn on or off. Below we explain what each option does. Note that Regular expression and Single word cannot be checked at the same time.
With the Case insensitive option you make the substitution case insensitive. Please note that case insensitivity will not be adopted when substituting. The example below replaces both ORANGE and ORanGe with oranges:
With the regular expression option, the line is considered a regular expression. You can use this option to create more complex substitutions that, for example, need to take data from the original into the substitution. Regular expressions provide within Clonable the ability to use match groups in the replacement (e.g.
$2, etc.). For more information on regular expressions within Clonable, please read this article. This option cannot be used in combination with Single word.
The Single word option is used when you want to create a substitution for a single word and prevent it from also being substituted when it is part of a larger word or url, for example. If the original of your substition contains a space (and thus consists of multiple words), this option is often useless. Also, if your word is not part of another word on your clone and does not appear in non-text elements such as urls or script you can leave this option off. This option cannot be used in conjunction with Regular expression.
Substitutions with HTML
If you want to create a substitution for a piece of text containing different formatting (for example, a bold word), you cannot simply use the text as original. Text with different formatting contains HTML tags in the source code which must therefore also be part of the substitution rule. Check out this article if you want to know more about how to handle HTML in substitutions.
Even if you don't see a clear difference in formatting, there may be HTML tags in the text you want to substitute. Also, some characters may be encoded so that the source code differs from what you see. For example, instead of a space you can use
and instead of
& you can use
&. Therefore, always check the source code if a line does not seem to work.
While making substitutions, you may encounter a number of pitfalls that cause your rules to not work. We have listed the most common ones below.
Rules with domain names in the original
If the original of your rule contains the domain name of your clone, it is important to replace it with the domain name of the original site. This is necessary because replacing the domain name is also a substitution rule applied with your own rules. So when your rule is executed, it still says the original domain name.
White space in substitutions
When you create substitutions, you must also make sure that the whitespace matches exactly. This is especially important in multi-line substitutions. Therefore, always make sure to use the original through the view-source option of your browser and not through what you see or through the developer tools.
It often happens that special characters such as
> are HTML-encoded in the source code as
>. You must then use the encoded variant for your substitution rule in the original to ensure that the rule works. You can read more about HTML in your substitution rules in this article.