Regular expressions in parameter arguments
From Joomla! Documentation
Revision as of 15:58, 16 August 2008 by Chris Davenport
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 </source lang="xml"> filter = “^joomla(.*)\.php$” </source>
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 the “.”) can occur any number of times, including zero; and the brackets serve to separate the substring from the rest of the string.
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$”