Skip to content

Latest commit

 

History

History
279 lines (233 loc) · 13.2 KB

User-Guide.md

File metadata and controls

279 lines (233 loc) · 13.2 KB
Raw

User guide (for end-users)

Note that the following options are only necessary if you are not using the graphical "Exec" toolbarbutton of the Executable Builder component of WebAppFind. The Executable Builder component can be used to associate default file types to (web) applications without your needing to find the path of these executables as WebAppFind otherwise requires.

WebAppFind is triggered through command line arguments passed to a WebExtensions browser (in technical terms, via WebSockets set up by the native messaging component of the add-on) and handled by the WebAppFind add-on.

Alternatively, executables may be built which bake in specific data. This executable building may be done through WebAppFind itself, whether by its command line or its graphical ExecutableBuilder component which leverages this command line).

The executables that are built then may either be associated to files of certain file extensions or content types, or these executables may themselves be invoked (with fewer arguments) from the command line.

Building an (AppleScript) executable from command line (build-openwith-executable) that can be used with "Open with..." to interact with WebAppFind

In addition to using the graphical Executable Builder (the "Exec" button in the toolbar of the add-on), one may also build executables from the command line. Executables can provide the convenience of not needing to pass as many arguments to the command line or not using the command line at all.

The method should be "build-openwith-executable". See the "Arguments" section for the other arguments.

An AppleScript file can be generated by invoking the native-app executable (or script) added by the installer with the arguments below, allowing one to pass predetermined or run-time parameters through WebAppFind, along with a local file to be opened by a number of methods ("open with", as a default file association, as a droplet onto which files are placed (including if placed conveniently on one's dock), command line, or with a specific file optionally baked into the script).

You may then either follow the instructions in "Command line usage of executables built by WebAppFind" or follow "Usage of the executables on your OS desktop" to use "Open with" or to associate a specific file or all files of a certain extension with the web app that will be chosen as a result of running this executable.

Alternatively or in addition, you can drag this file to your Dock, Favorites, etc. so as to be able to drop files onto it for opening (or to just click it to open any hard-baked file or to get the file dialog otherwise).

See executable-builder/README.md for more.

Command line usage of executables built by WebAppFind

In place of a local file, if the generated AppleScript is called with no arguments (including when placed on the dock), a file selector may pop-up to determine the file whose contents will be sent to your web applications.

If the AppleScript is invoked on the command line, one can invoke with:

osascript ./webappfind-as.app /Users/brett/myFile.txt

or to bring up the file selector (assuming the executable includes this), just:

osascript ./webappfind-as.app

Usage of the executables on your OS desktop

The following option is only available if you already have a WebAppFind-capable executable (e.g., built through ExecutableBuilder or the build-openwith-executable command line instruction) but have not used ExecutableBuilder to associate the app with "Open with..." or to set the app as the default application for files of a given type.

You must first install the WebExtensions add-on (and installer) so that the following steps will work (the add-on has not yet been submitted to the Add-ons site, so for now, you will have to build the add-on from source).

  1. Right-click on a file and...
    1. If you want to use WebAppFind without disturbing your defaults for that file extension, select "Open With"->"Other..." and if you want to always open that particular file with WebAppFind, you can also check "Always Open With" in the resulting dialog. (Alternatively, you can select "Get Info" (command-I) and change the value in the "Open with" pull-down and then the file can just be double-clicked in the future--assuming you did not already use Executable Builder to do this for you.)
    2. If you always want to use WebAppFind when handling files with the same extension as this file (and just be able to double-click such files when opening them in the future), you can select "Get Info" (command-I) and change the value in the "Open with" pull-down and then click "Change All.." to apply to all such files of that file extension.
  1. Navigate to an executable built following the instructions in the section "Executable builder"
  2. Select "Ok".
  3. If you used "Open with" (as per step 1.1 above), your file should have already opened with WebAppFind. If you opted for "Get Info" in step 1 you should now be able to double-click the file (or any file possessing the same extension if you followed step 1.2) to open it with WebAppFind.

If an edit permission is granted and open and then disabled in the same session, it will keep having save access (though within that window session only). One must currently close any open tabs for that web application if one no longer wishes to allow access (though as noted elsewhere in this documentation, the app only has access to the files to which you granted access).

Pass data to web app for one-off usage (command line)

In order to pass a file into the add-on (which can use any arguments and its heuristics to determine the specific website to open and in what manner), the native-app.js file should be invoked with --method=client and optionally with --file="...", --mode="view|edit", --site="http://...", --args="...".

The available arguments are similar to the executable (AppleScript) building commands (where relevant, e.g., there is no "baking in" for such one-off usage), except that method should be client (instead of build-openwith-executable).

See the "Arguments" section for the other arguments.

Example

node native-app.js --method=client --file="path/to/my/file" --mode=view --binary=true --site=http://example.com --args='{"a":1, "b":2}'

(The executable installed by the installer may be referenced in place of node native-app.js, e.g., ~/Library/Application Support/Mozilla/NativeMessagingHosts/native-app.)

Arguments (for executable-building or one-off invocation)

  • method - Required. Must be set to "build-openwith-executable" for building executables which bake in the behavior, or must be "client" for one-off passing of instructions.
  • executableName - Name (used in "Open with...")
  • executablePath - Path for executable.
  • id - Value for CFBundleIdentifier, uniquely identifying app to the OS.
  • file - Optional hard-baking of a file. If this argument is not included, the generated script will check for the presence of an argument to the script to serve as the file to pass to the web application. If no argument is passed to the generated script, its absence will trigger a file dialog. Any file will be opened according to the mode.
  • string - Hard-coded string to pass to app (in place of file); if true, "true", or "on", the string will be accepted as an argument at run-time rather than being baked in. The string may be empty in which case, this executable/instruction may simply end up opening open a URL rather than adding any predefined data to it.
  • mode - Optional (fundamental) mode for invoking the web app on your contents, either "view" (readonly), "edit" (read and write), "shell", or "none". Default is "view".
  • binary - Optional to indicate a program needing to open a file in binary mode (as an array), such as may be usable by images, sound files, or videos.
  • site - Baking in of a specific site to invoke with the designated file's contents. Currently required.
  • extensions - Array used for CFBundleTypeExtensions; the items are file extensions, e.g., "html".
  • contentTypes - Array used for CFBundleTypeOSTypes; the items are OS content types, e.g., "public.html".
  • extensionsDefaults - Array of extensions to pass to addOrReplaceExtensionHandler. See launchServiceHandlers.js.
  • contentTypesDefaults - Array of contentTypes to pass to addOrReplaceContentTypeHandler. See launchServiceHandlers.js.
  • args - Optional JSON object as arguments to pass to the web applications onmessage listener data object (under args). Any customModes property must be an array and is reserved per Registered-custom-modes; its string items indicate modes supplementary to the fundamental mode (e.g., "source" to indicate opening in a mode to view the file type's source code as opposed to just viewing its rendered output).
  • log - Whether to log to stdout
  • filePicker - Whether to show a file picker
  • fileSelectMessage - When the generated script does not have a baked-in file and no file argument is passed to it, this argument will determine the message shown in the resulting file dialog.
  • fileSelectType - When the generated script does not have a baked-in file and no file argument is passed to it, this argument, if present, will have the script insist on a particular file type in the resulting file dialog. Must be an extension string without the leading period (e.g., "js" for ".js" JavaScript files) or a Uniform Type Identifier, e.g., "public.image" or "com.apple.iwork.pages.sffpages".

Creating URL shortcuts

This functionality is not quite WebAppFind-related, but is provided as a convenience.

node native-app.js --method=urlshortcut --path=/path/to/create.webloc --url="http://example.com"

Tools and Comparisons

For tips for using with other tools and comparison to other similar tools, see Tools-and-Comparisons.

Adding as Quick Action extension

Recent versions of MacOS (e.g., Mojave) allow one to have "Quick Actions" display on the Finder, making the commands easier to access than right-clicking to find the desired item within the Services submenu.

You can get this behavior by following the instructions in the Usage video for creating a service (now renamed within Automator as a "Quick Action") and then, while on the desktop, select a file type supported by that service (e.g., an HTML file if your web app can open HTML files) and ensure your item is selected when clicking on ... More and Customize (i.e., within System Preferences -> Extensions -> Finder).