D 2019-02-11T19:29:33.025
L Filters
N text/x-markdown
P 690a415ba55cb0ce7de7698ba7dbf8704b57e679
U tinus
W 3830
# 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 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 454ee29bca282a6fec03f357b0f103d5