J1.5:Regular expressions in parameter arguments

The "J1.5" namespace is an archived namespace. This page contains information for a Joomla! version which is no longer supported. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Some parameter arguments take regular expressions as values. For example, the filter and exclude arguments for the filelist and imagelist parameter types. This is enormously powerful, but it requires you to know at least a little regular expression syntax to be able to use it effectively.

Described here are some examples of simple regular expressions that you might want to use in the context of template parameters. A complete reference to regular expression syntax is beyond the scope of this book, but can be found online at http://www.php.net/manual/en/book.pcre.php

Simple filter string

Suppose you want to use the filelist parameter type to list the files in a given directory. There are many files in the directory but you only want those with a '.php' extension to be listed. Then you would use this argument in the <param> element

filter = “\.php”

The first thing to note is the leading backslash character. This is needed because the “.” character has a special meaning in regular expressions and that is not what is intended here. The backslash character tells the regular expression parser to treat the next character (which is the “.”) as just an ordinary character and not to give it the special meaning that it normally does.

The effect of this filter string is to only include those files that have the characters “.”, “p”, “h” and “p”, in that order, anywhere in the file name.

Anchoring to the end of the string

In the above example, if there is a file called configuration.php-dist then it would be included in the list because “.php” occurs in the middle of the string. Perhaps you don't want that, in which case you can use this instead

filter = “\.php$”

The “$” tells the regular expression parser that the string “.php” must occur at the end of the file name. So configuration.php will be included, but configuration.php-dist will not.

Anchoring to the start of the string

Suppose you want to list those files which start with the string “joomla” then you would use

filter = “^joomla”

The “^” tells the regular expression parser that the string following must occur at the start of the file name.

Anchoring to both ends of the string

Suppose you want to list all those files whose names begin with “joomla” and end with “.php”, but you don't care about what is in between. Then you can use

filter = “^joomla(.*)\.php$”

Here you will recognise the “^” character as anchoring the start of the string, and the “$” as anchoring the end of the string. The “(.*)” indicates that any number of characters, including no characters at all, are acceptable in that position. Breaking this down a little, the “.” will match any single character; the “*” indicates that the preceding character (in this case the “.”) can occur any number of times, including zero; and the brackets serve to separate the substring from the rest of the string.

Case sensitivity

It is important to note that regular expression strings are case sensitive. Suppose you have some file names that begin with “Joomla” instead of “joomla”. These would not be included if you used the string in the previous example. To allow for the first character of the file name to be either upper or lower case you can use

filter = “^[Jj]oomla”

Here the “[Jj]” indicates that either “J” or “j” should be matched. The brackets (“[]”) indicate a “character class” and should contain list of characters that are to be matched. If you want to include all filenames beginning with the letters “s”, “t”, “u” or “v” then you could use

filter = “^[stuv]”

Actually you can shorten this a little by using a range specification

filter = “^[s-v]”

If you want to make this case insensitive then use

filter = “^[s-vS-V]”

Filtering a list of extensions

Suppose you want to filter your list of files so that only those files with specific extensions are included. For a single extension you can just use

filter = “\.php$”

But what if you want to filter several different extensions? For example, to only include file names ending in “.php”, “.html” or “.txt” you can use

filter = “\.php$|\.html$|\.txt$”

The “|” character indicates an alternative, so “this|that” will match with “this” or “that”.

You might notice that the imagelist parameter type is exactly the same as the filelist parameter type with this filter string

filter = “\.png$|\.gif$|\.jpg$|\.bmp$|\.ico$”