D 2019-02-11T18:58:09.514
L Filters
N text/x-markdown
P 097fd1061e4cfdb190d8d4b6251a3c285b8f5bc8
U tinus
W 2973
# Filters
By default, the preview plugin only displays a preview of HTML or XML files — and for XML files, only when they contain a [processing-instruction][1] for a stylesheet.
Filters are a way to pre-process other files than HTML or XML so they _can_ be previewed.
## Definition
Filters are defined in a special `filters.ini` file in the Config directory. The recommended way to open the filter configuration file is via the menu option.
Each filter is defined in its own section, so by using a section header between square brackets, followed by the language and/or file extension it should work for, and the command line to execute:
[Filter name]
Extension=<.ext>
Language=<Notepad++ language name>
Command=<command line, using %1 for the currently selected file>
To temporarily disable a filter without completely deleting is, you can start the filter name with a '-' hyphen (e.g. `[-Filter name]`); the plugin will then skip that filter.
### Filter selection
The preview plugin [decides][2] whether or not to run each filter based on the file's extension OR the
active highlighter language. The first filter encountered is run, any other matching filters are
ignored.
* The `Language` field should match one of Notepad++'s syntax highlighting language names.
* The `Extension` field may contain one or more comma-separated file extension(s).
* The `Filename` field may contain a file mask (including ‘joker’ or ‘glob’ characters such as `*`, `?`; [see description][3]).
Note that at least one of these three fields must be provided, otherwise the filter will never be used.
### Filter execution
When the plugin has determined that a filter should be used, it will try to run the given `Command` with the current file.
If the editor has no changes, the filter will simply replace `%1` in the `Command` by the full path and filename of the currently selected file name. If the file hasn't been saved yet (e.g. `New 1`), or if the editor contains changes that haven't been saved, it will write the contents to a temporary file, and run the command with that temporary file.
The output of the command will then be used to display the preview. So the output has to be a format that can be displayed by the Shell Document engine, or, basically, by Internet Explorer.
## Example
Check out the [sample filter definition][4] in the plugin's `Config` directory:
<iframe src="raw?ci=publish&filename=Config/PreviewHTML/filters.sample.ini&m=text/plain" style="width:98%;bottom:0px" onload="this.style.height=this.contentDocument.body.scrollHeight +'px';"></iframe>
[1]: https://en.wikipedia.org/wiki/Processing_Instruction#Examples
[2]: /artifact?ci=trunk&filename=src%2FF_PreviewHTML.pas&ln=370-453
[3]: http://docwiki.embarcadero.com/Libraries/XE2/en/System.Masks.MatchesMask#Description
[4]: /artifact?ci=publish&filename=Config/PreviewHTML/filters.sample.ini
Z f9430c513553156a4326a2e593a08a94