Introduction

ApLo is an application that displays HTML output of helper apps or scripts. It is intended to provide a functionality similar to TextMate1's web view for TextMate2.

Alternatively it provides a web preview functionality.

Controlling ApLo

ApLo is controlled via *.aplo files, we will call the command files. These files can be auto-generated by scripts, or manually produced and reused. The command files have a very simple format:

VarName=Some value here

There is no special treatment of whitespace. Everything from the start to the first equal sign is a variable name, everything following the first equal sign until the end of the line is the value of that variable. Lines not containing an equal sign are allowed. That makes it possible to add comments, they just can't contain an equal sign.

Scripts can very easily produce such files and launch ApLo. Here is an example that also forwards the entire current environment, useful for TextMate based scenarios:

#!/bin/sh

aploPath=/tmp/aplo$$.aplo

APLO_PARSER_PATH=/my/parser/which/creates/html
APLO_WINDOW_NAME=${APLO_WINDOW_NAME:-$(basename "$TM_PROJECT_DIRECTORY")}
APLO_CWD=${APLO_CWD:-"$TM_PROJECT_DIRECTORY"}
APLO_DELETE_FILE=1

EXPORT APLO_PARSER_PATH APLO_WINDOW_NAME APLO_DELETE_FILE

env>$aploPath
open $aploPath

Note how the above example makes use of TextMate2's new .tm_properties: you can set APLO_WINDOW_NAME and/or APLO_CWD in your project-specific .tm_properties to override the defaults in the example.

For all command files generated on the fly like in the above example please observe the above convention of using /tmp/aplo$$.aplo ($$ evaluates to the PID of the calling app) as the command file path, and outside of debugging please set APLO_DELETE_FILE to clean up this file.

Variables used by ApLo

NOTE: Either APLO_PREVIEW_HTML_FILE or APLO_PARSER_PATH must be given!

APLO_PREVIEW_HTML_FILE

When this variable is given the ApLo window switches to web preview mode. It will show the HTML file given, and also enables the web inspector.

APLO_PARSER_PATH

This is the only mandatory variable. It must contain the path to a script (or binary) that will emit the HTML displayed by ApLo. All variables contained in the command file will be passed to the script in the environment.

The script will be launched 3 times:

script -css
script -js
script

The first two calls allow the script to provide CSS or JavaScript to be included in the header of the HTML displayed in the ApLo window.

On the last call script should start producing HTML to be displayed. The script should just emit lines to be displayed, and no HTML header or footer. The HTML produced should not contain any elements that span across lines (as defined by a \n).

Due to a quirk in WebViews any JavaScript to be executed inline must be on a line that begins with <script type="text/javascript"> and ends with </script>, example:

<script type="text/javascript">toggleVisibilityOfElementsNamed('levelID00007');</script>

If you make use of javascript or CSS and run into problems, it is possible to debug the WebView windows. To do so quit ApLo, then in a terminal window execute this line:

defaults write com.bitart.ApLo WebKitDeveloperExtras -bool true

Now you can right- or control-click the ApLo window in question and use the Inspect Element to view the HTML, CSS, debug javascript etc.

APLO_WINDOW_NAME

This variable set's the window name for the ApLo output window. Any subsequent invocations using the same APLO_WINDOW_NAME will use the same window, any processes attached to the window will be killed first. ApLo will also store the windows size and location, so that any named window will always appear at the same location.

APLO_CWD

If set, ApLo will use the value as the current working directory for the parser script.

APLO_DELETE_FILE

If set to 1, ApLo will delete the command file after reading it. This should be used for all command files generated on the fly.

APLO_KEEP_WINDOW_CONTENTS

If set to 1, ApLo will not erase preexisting contents in the window designated by APLO_WINDOW_NAME.