Update of "Filters"
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: 690a415ba55cb0ce7de7698ba7dbf8704b57e679
Page Name:Filters
Date: 2019-02-11 18:58:09
Original User: tinus
Mimetype:text/x-markdown
Parent: 097fd1061e4cfdb190d8d4b6251a3c285b8f5bc8 (diff)
Next 47076e32927c3576995e9081096bbcf5555f8511
Content

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 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 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).

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 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>