D 2019-02-11T19:54:34.489
L Filters
N text/x-markdown
P 47076e32927c3576995e9081096bbcf5555f8511
U tinus
W 3827
# 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 matching filter 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 there is no `Command` field, or it is empty, the file's contents will be passed as-is to the preview engine. This allows previewing any file format.
* Otherwise, the `Command` will be run.
How the plugin communicates with the command depends on the presence of the `%1` and `%2` symbols, as follows:
* If the `Command` field does _not_ contain the symbol `%1`, then the plugin will pipe the editor's contents into the command's input stream.
* Otherwise, 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. But if the file contains changes that haven't been saved, it will write the contents to a temporary file, and replace `%1` with that temporary file name.
As for the output:
* If the `Command` field does _not_ contain the symbol `%2`, then the plugin will use the command's output stream to display the preview.
* If the `Command` field _does_ contain the symbol `%2`, then the plugin will replace that by a temporary file name; and when the command finishes, it will use the contents of that file to display the preview.
Note that the output has to be a format that can be displayed by the Shell Document engine (basically, by Internet Explorer).
And last but not least, keep in mind that Notepad++ will not respond while a file command is run, so do try to keep it fast.
## 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 92b0a65d13ad7b3a55aedf705d91a889