Home

Awesome

⇉📺⇉ pyscFilteredViewer

This is a helper-script for Notepad++ using PythonScript. It runs the active file in Notepad++ through a filter to convert it to HTML, then launches that HTML in the default browser. This filtering process can be run automatically with every save of your file in Notepad++, or you can do it just on-demand.

This is useful for code that has embedded documentation that can be easily extracted and rendered to HTML (such as POD in Perl), or when editing marked-up text like a Markdown file. Anything that you can meaningfully convert to HTML, where you want to be able to edit the non-HTML source but render the final HTML in your browser is fair game.

Table of Contents

Installation

Installation Prerequsisites

Installation Procedure

  1. Download the latest release of pyscFilteredViewer from https://github.com/pryrt/pyscFilteredViewer/releases/latest.
  2. Extract the pyscFilteredViewer folder from the zipfile into the PythonScript scripts\ location:
    • %AppData%\Notepad++\plugins\config\PythonScript\scripts\pyscFilteredViewer\ is the most common location.
    • If you have a portable version of Notepad++, or if you want these scripts to be available to all users on the machine, rather than just the current user, please see docs/AlternateInstall.md
  3. If you had Notepad++ open, close and reload Notepad++ .
    • This will cause Notepad++ and PythonScript to see the new scripts
    • You can see them in the Plugins > PythonScript > Scripts menu
  4. Run Plugins > PythonScript > Scripts > pyscFilteredViewer > pyscfvEditConfig to configure this utility: see Configuration (below) for configuration details

Scripts

Configuration

The first time you run any of the scripts (I recommend pyscfvEditConfig as the first of these scripts you run), it will create a configuration file called pyscFilteredViewer.ini. (If it finds a PreviewHTML filters.ini file, it will copy that to the new location and name. See Inspiration / Justification (below) for the connection with PreviewHTML.)

The configuration file is used to set the filter-command on a per-file-type basis (where a file-type is based on either the Language that Notepad++ has set for the file, or the file extension). Each file-type needs its own section in the config file.

The default configuration file looks something like:

; pyscFilteredViewer Config File (compatible with PreviewHTML Filters.ini file)
; Everything after ; are comments, and will help you read/understand the ini file
[IniFile]                                          ;   => this is the name of the section; it must be unique.  Typically, based on the language
Extension=.ini .cfg                                ;   => space-separated list of filename extensions, including the period.
Language=INI                                       ;   => this is the name of the language (from Notepad++'s perspective): for a UDL, use your "UserName" from the UDL dialog
; the 'Command=' line below is the filter command;
;   the first part of the command should be the full path to the command
;       if it has spaces in the path, it MUST have quotes around it
;       if it does not have spaces in the path, it still MAY have quotes around it
;   %1 is the name of the active file/buffer; it is in quotes "%1" because the path might contain spaces, and windows needs the quotes to know it's a single filename
;   the command must result in the HTML being dumped to STDOUT
Command="%AppData%\Notepad++\Plugins\Config\pyscFilteredViewer\ExampleConverterCommand.bat" "%1"
; this example command just wraps the text of the INI file in HTML XMP tags, so the browser will render it as plaintext inside an HTML file

NOTE: you technically only need one of either Language or Extension, since one is usually enough to define a file-type. But if both are defined, pyscFilteredViewer will first try to match on Language, and then on Extension.

Configuring Keyboard Shortcut(s)

If you want to be able to use one or more of these scripts with a keyboard shortcut, use the Plugins > PythonScript > Configuration... dialog to add the script(s) to the Menu items list, then Settings > Shortcut Mapper > Plugin Commands, filter for Python, and edit the keyboard shortcut for the appropriate script(s).

Once you are ready to replace PreviewHTML with pyscFilteredViewer, I highly recommend mapping the PreviewHTML shortcut (Ctrl+H) to pyscfvToggleFilterOnSave (see Filter On Save, below).

Filtering

You can either filter your file on demand, using One-time Filtering, or you can make it filter every time you hit SAVE in Notepad++ using Filter On Save.

One-time Filtering

This will take the active file, filter it as defined in the Configuration, and the resulting filtered file will be displayed in your default browser. With one-time filtering, it will immediately delete the temporary HTML file -- so if you try to hit RELOAD or REFRESH in your browser or viewer, it won't find the file. To reload the file, you will need to close the old version in your viewer, and re-run the one-time filter from Notepad++.

Filter On Save

If you want to keep updating the filtered file (usually HTML) every time you change the source, you need to "register" the FilterOnSave action, using the pyscfvRegisterFilterOnSave script. This will register a "hook" such that every time Notepad++ saves a file, it will run the filter. If the filter hasn't been run on this file yet, it will launch the filtered file in the appropriate viewer. If the filter had been run on this file before, then you will have to move to the viewer (usually, the web browser) and refresh the appropriate page (or find a browser or viewer that can watch for changes in the file, and automatically refresh itself).

Once you are done (or want to be able to edit and save files without having the filter run every time), you can use pyscfvUnRegisterFilterOnSave to un-register / un-hook the filter from the file-save event.

As an easier interface (and the one I recommend), you can use the pyscfvToggleFilterOnSave script to automatically determine whether it should enable or disable the FilterOnSave. Using this script to toggle filtering to the temporary file is the most like the PreviewHTML behavior, and it's the script I have associated with PreviewHTML's Ctrl+H keyboard shortcut.

As a bonus feature, to help you keep track of whether or not the filter is on, the Status Bar will be edited to show ⇉📺⇉ before the Language name when the live filter is active, and will remove that prefix when the filtering is turned off.

Inspiration / Justification

PreviewHTML

This was inspired by the PreviewHTML plugin for Notepad++, which was designed to embed an HTML-previewer in Notepad++. But the more-useful-to-me feature was that you could apply a filter program to the current file, and it would filter into HTML, which would then be rendered in the PreviewHTML window. Unfortunately, PreviewHTML hasn't been updated to work with 64-bit Notepad++ (though the developer has been working on it on and off for more than a year, as of Jan 2019), and I'd really like to transition to 64bit as my main editor.

Since I primarily care about the filter-to-a-viewer format, and would be willing to use an external viewer (like my default web browser), I realized I could implement the pass-the-current-file-through-a-filter feature using PythonScript, and then launch the filtered HTML file in the user's default web browser.

I have kept the configuration file compatbile with PreviewHTML's filters.ini -- and, in fact, if you already have that plugin installed, pyscFilteredViewer will copy the PreviewHTML filters.ini configuration file for its own use

Pork2Sausage

It has been pointed out to me that this is also similar to Don Ho's Pork2Sausage plugin, which is one of the developer's demonstration plugins for Notepad++. Pork2Sausage will grab the contents of the active file, run a conversion on those contents, and overwrite the old version with the new: this is great for encoding or decoding base64 text, or similar actions, where you want it to happen in-place. But when you are editing a Markdown document, and want to see what the equivalent HTML looks like in your browser, you don't want to replace the Markdown; when editing Perl source code, and just want to render the embedded POD as HTML, you don't want to replace the whole script with the HTML.

Future Features

Some day, there may be:

Feel free to make feature suggestions and bug reports. I do not guarantee they will make it in, but if I can think of a way to do it (or if you help with the development), there's a good chance I'll incorporate it.