Skip to content

Commit

Permalink
[doc] Edit install/update instructions and site URL in README; Fix re…
Browse files Browse the repository at this point in the history
…ferenced Linux install/log paths.
  • Loading branch information
mpaperno committed Dec 27, 2022
1 parent 3ca2be1 commit 81fc00e
Show file tree
Hide file tree
Showing 3 changed files with 45 additions and 22 deletions.
35 changes: 23 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
# Dynamic Script Engine Plugin for Touch Portal

![plastic](https://img.shields.io/static/v1?style=flat&labelColor=5884b3&color=black&label=made%20for&message=Touch%20Portal&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAetJREFUeNp0UruqWlEQXUePb1HERi18gShYWVqJYGeXgF+Qzh9IGh8QiOmECIYkpRY21pZWFnZaqWBhUG4KjWih4msys8FLbrhZMOfsx6w1e9beWjAYBOMtx0eOGBEZzuczrtcreAyTyQSz2QxN04j3f3J84vim8+cNR4s3rKfTSUQQi8UQjUYlGYvFAtPpVIQ0u90eZrGvnHLXuOKcB1GpkkqlUCqVEA6HsVqt4HA4EAgEMJvNUC6XMRwOwWTRfhIi3e93WK1W1Go1dbTBYIDj8YhOp4NIJIJGo4FEIoF8Po/JZAKLxQIIUSIUChGrEy9Sr9cjQTKZJJvNRtlsVs3r9Tq53W6Vb+Cy0rQyQtd1OJ1O9b/dbpCTyHoul1O9z+dzGI1Gla7jFUiyGBWPx9FsNpHJZNBqtdDtdlXfAv3vZLmCB6SiJIlJhUIB/X7/cS0viXI8n8+nrBcRIblcLlSrVez3e4jrD6LsK3O8Xi8Vi0ViJ4nVid2kB3a7HY3HY2q325ROp8nv94s5d0XkSsR90OFwoOVySaPRiF6DiHs8nmdXn+QInIxKpaJclWe4Xq9fxGazAQvDYBAKfssDeMeD7zITc1gR/4M8isvlIn2+F3N+cIjMB76j4Ha7fb7bf8H7v5j0hYef/wgwAKl+FUPYXaLjAAAAAElFTkSuQmCC)
[![Made for Touch Portal](https://img.shields.io/static/v1?style=flat&labelColor=5884b3&color=black&label=made%20for&message=Touch%20Portal&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAA4AAAAOCAYAAAAfSC3RAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAetJREFUeNp0UruqWlEQXUePb1HERi18gShYWVqJYGeXgF+Qzh9IGh8QiOmECIYkpRY21pZWFnZaqWBhUG4KjWih4msys8FLbrhZMOfsx6w1e9beWjAYBOMtx0eOGBEZzuczrtcreAyTyQSz2QxN04j3f3J84vim8+cNR4s3rKfTSUQQi8UQjUYlGYvFAtPpVIQ0u90eZrGvnHLXuOKcB1GpkkqlUCqVEA6HsVqt4HA4EAgEMJvNUC6XMRwOwWTRfhIi3e93WK1W1Go1dbTBYIDj8YhOp4NIJIJGo4FEIoF8Po/JZAKLxQIIUSIUChGrEy9Sr9cjQTKZJJvNRtlsVs3r9Tq53W6Vb+Cy0rQyQtd1OJ1O9b/dbpCTyHoul1O9z+dzGI1Gla7jFUiyGBWPx9FsNpHJZNBqtdDtdlXfAv3vZLmCB6SiJIlJhUIB/X7/cS0viXI8n8+nrBcRIblcLlSrVez3e4jrD6LsK3O8Xi8Vi0ViJ4nVid2kB3a7HY3HY2q325ROp8nv94s5d0XkSsR90OFwoOVySaPRiF6DiHs8nmdXn+QInIxKpaJclWe4Xq9fxGazAQvDYBAKfssDeMeD7zITc1gR/4M8isvlIn2+F3N+cIjMB76j4Ha7fb7bf8H7v5j0hYef/wgwAKl+FUPYXaLjAAAAAElFTkSuQmCC)](https://www.touch-portal.com)
[![GitHub release (latest by date including pre-releases)](https://img.shields.io/github/v/release/mpaperno/DSEP4TP?include_prereleases)](https://github.com/mpaperno/DSEP4TP/releases)
![Supported Platvorms](https://img.shields.io/badge/platforms-windows%20|%20osx%20|%20linux-AA7722)
[![GPLv3 License](https://img.shields.io/badge/license-GPLv3-blue.svg)](LICENSE.GPL.txt)
<!-- <img alt="Lines of code" src="https://img.shields.io/tokei/lines/github/mpaperno/MSFSTouchPortalPlugin?color=green&label=LoC&logo=cplusplus&logoColor=f34b7d"> -->
[![Discord](https://img.shields.io/static/v1?style=flat&color=7289DA&&labelColor=7289DA&message=Discord%20Chat&label=&logo=discord&logoColor=white)](https://discord.gg/FhYsZNFgyw)
<!-- <img alt="Lines of code" src="https://img.shields.io/tokei/lines/github/mpaperno/DSEP4TP?color=green&label=LoC&logo=cplusplus&logoColor=f34b7d"> -->


**A complete, standalone, multi-threaded JavaScript environment available as a plugin
Expand All @@ -14,13 +15,13 @@ for use with [Touch Portal](https://www.touch-portal.com/) macro launcher softwa

<div class="hide-on-site">

**Visit [https://mpaperno.github.io/DSEP4TP/](https://mpaperno.github.io/DSEP4TP/) for all details, including this README.**
**Visit [dse.tpp.max.paperno.us](https://dse.tpp.max.paperno.us) for all details, including this README.**

</div>

----------
<div class="darkmode_inverted_image">
<img align="right" src="https://mpaperno.github.io/DSEP4TP/images/logo/banner_420x105.png">
<img align="right" src="https://dse.tpp.max.paperno.us/images/logo/banner_420x105.png">
</div>

## Features
Expand Down Expand Up @@ -59,7 +60,7 @@ global Value or a plugin State and will be replaced by Touch Portal with the act
* Send an image to use as a Touch Portal button icon. E.g. with dynamic image name:
* `File.read("images/status_icon_${value:MyVariable}.png", 'b').toBase64()`
* Get an image from the Internet for a button icon:
* `Net.request("https://mpaperno.github.io/DSEP4TP/images/logo/icon_64.png").get().base64()`
* `Net.request("https://dse.tpp.max.paperno.us/images/logo/icon_64.png").get().base64()`
* Read any number of lines from a file, starting from beginning, end, or a specific line number. E.g. read the last 5 lines of a log with a dynamic name:
* `` File.readLines(`../logs/console-${new Date().format("yyyyMMdd")}.log`, 5, -1)) ``
* Extract a value from a JSON object in a file:
Expand Down Expand Up @@ -113,17 +114,27 @@ Note: As with all plugins, this requires the Touch Portal Pro (paid) version to
just do that and skip to step 5. There is also a [short guide](https://www.touch-portal.com/blog/post/tutorials/import-plugin-guide.php) on the Touch Portal site.
3. Import the plugin:
1. Start/open _Touch Portal_.
2. Click the "gear" icon at the top and select "Import plugin..." from the menu.
2. Click the Settings "gear" icon at the top-right and select "Import plugin..." from the menu.
3. Browse to where you downloaded this plugin's `.tpp` file and select it.
4. Restart _Touch Portal_
* When prompted by _Touch Portal_ to trust the plugin startup script, select "Yes" (the source code is public!).
5. That's it. You should now have the plugin's actions available to you in Touch Portal.
4. When prompted by _Touch Portal_ to trust the plugin startup script, select "Trust Always" or "Yes" (the source code is public!).
* "Trust Always" will automatically start the plugin each time Touch Portal starts.
* "Yes" will start the plugin this time and then prompt again each time Touch Portal starts.
* If you select "No" then you can still start the plugin manually from Touch Portal's _Settings -> Plug-ins_ dialog.
4. That's it. You should now have the plugin's actions available to you in Touch Portal.

### Updates

Unless noted otherwise in the notes of a particular release version, it is OK to just re-install a newer version of the plugin "on top of"
a previous version without uninstalling the old version first. Either way is OK, just keep in mind that uninstalling the plugin via Touch Portal
will also remove any current log files as well.

### Update Notifications

_Watch_ -> _Custom_ -> _Releases_ this repository (button at top) or subscribe to the [ATOM feed](https://github.com/mpaperno/WASimCommander/releases.atom) for release notifications.
In GitHub (with an account) you can _Watch_ -> _Custom_ -> _Releases_ this repository (button at top right).

Or subscribe to the [ATOM feed](https://github.com/mpaperno/DSEP4TP/releases.atom) for release notifications.

Release announcements are also made in the Touch Portal Discord Server room [#dynamic-script-engine](https://discord.com/channels/548426182698467339/750791488501448887)
Release announcements are also made in the Touch Portal Discord Server room [#dynamic-script-engine](https://discord.gg/FhYsZNFgyw)

Or use the provided [example script](@ref example_fetch_and_notify) to check for new versions right from Touch Portal!

Expand All @@ -132,7 +143,7 @@ Or use the provided [example script](@ref example_fetch_and_notify) to check for
-------------
## Documentation

[Full Documentation & Examples @ https://mpaperno.github.io/DSEP4TP/](https://mpaperno.github.io/DSEP4TP/) - includes this README as well.
[Full Documentation & Examples @ dse.tpp.max.paperno.us](https://dse.tpp.max.paperno.us) - includes this README as well.

</div>

Expand Down
6 changes: 3 additions & 3 deletions doc/pages/Basic.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ JavaScript scripts, like a **mini Web browser** or a continuously-running Node.j
**An engine instance can persist for the life of the plugin** (that is, it exists as long as the plugin keeps running).
* This is an important distinction vs., say, running a Node.js script from a Touch Portal action (using Run an Application or Run a batch file actions, for example).
In the latter case the script has no way of saving information (data) between executions (not easily, anyway), plus every time it starts it will need to re-create
it's complete environment, including starting node[.exe] itself and so on. A persistent environment like this plugin provides has no startup "cost" after the initial
it's complete environment, including starting Node itself and so on. A persistent environment like this plugin provides has no startup "cost" after the initial
creation, and allows for easily saving data, or "state" (lower case!), between runs.
It's more like a Web browser that stays open and can re-run any loaded scripts on demand w/out restarting the whole thing.

Expand Down Expand Up @@ -62,9 +62,9 @@ So in general the procedure for using any of these results is:
this will crate the new State in Touch Portal.
3. Now go back and finish setting up your button/event once the new State has been created and will be available in the various places you can select States from.

Alternately:
Alternately (once you understand the actions described on the next page):
1. Create the Touch Portal State first with a simple JavaScript expression: `TP.stateCreate("dsep.MyNewStateName", "Description of My New State")`
2. Using the ["one-time script"](@ref plugin_actions_one-time-script) actin is perfect for this.
2. Using the ["one-time script"](@ref plugin_actions_one-time-script) action is perfect for this.

OK, enough of that, let's get to the Actions!

Expand Down
26 changes: 19 additions & 7 deletions doc/pages/Status.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,11 +28,11 @@ There is also:

## Logging

The plugin logs operational message to a file. Two, actually. They are both located in your Touch Portal configuration folder, in the 'plugins' subfolder;
the path looks like:<br/>
The plugin logs operational message to a file. Two, actually. They are both located in your Touch Portal configuration folder, in the 'plugins/DSEP4TP' subfolder;
the path looks like this:<br/>
* Windows: `C:\Users\<User_Name>\AppData\Roaming\TouchPortal\plugins\DSEP4TP\logs`
* Mac: `~/Documents/TouchPortal/plugins/DSEP4TP/logs`
* Linux: `~/TouchPortal/plugins/DSEP4TP/logs`
* Linux: `~/.config/TouchPortal/plugins/DSEP4TP/logs`

The two log files are:

Expand All @@ -52,10 +52,14 @@ You can also "tail" a file using operating system utilities. For example (showin
```ps
Get-Content -Tail 10 -Wait $Env:APPDATA\TouchPortal\plugins\DSEP4TP\logs\console.log
```
- [OS X](https://ss64.com/osx/tail.html) or [Linux](https://ss64.com/bash/tail.html) terminal
- [OS X](https://ss64.com/osx/tail.html) terminal
```shell
tail -F -n 10 ~/Documents/TouchPortal/plugins/DSEP4TP/logs/console.log
```
- [Linux](https://ss64.com/bash/tail.html) terminal
```shell
tail -F -n 10 ~/.config/TouchPortal/plugins/DSEP4TP/logs/console.log
```

### Plugin Log

Expand All @@ -72,15 +76,23 @@ insidious is going wrong.
The logs are rotated daily. The previous days' log is renamed with a date stamp and a new one is started.
By default the last 3 days' worth of logs are kept (the current one + 3 historical logs).

You can force a rotation of the logs by going to the plugin's executable directory (`DSEP4TP/bin`) in a terminal/command window and run the plugin (w/out starting it) with the following command:<br />
* Windows: `DSEP4TP.exe -f1 -j1 -rx`
* Mac/Linux: `./DSEP4TP -f1 -j0 -rx`
You can force a rotation of the logs by going to the plugin's install directory (*)
in a terminal/command window and run the plugin (w/out starting it) with the following command:<br />
* Windows: `bin/DSEP4TP.exe -f1 -j1 -rx`
* Mac: `./DSEP4TP.app/Contents/MacOS/DSEP4TP -f1 -j0 -rx`
* Linux: `./bin/DSEP4TP -f1 -j0 -rx`
* Optionally add a `-k N` switch to the command line to keep `N` number of logs instead of the default 3. Clear out all old logs by using `-k 0`
* Use `-h` to see all command-line options.

The log files have an "emergency limit" of 1GB in case something goes haywire. If this limit is reached, further logging to that file is
disabled until the plugin is restarted.

(*) Plugin install location:
* Windows: `C:\Users\<User_Name>\AppData\Roaming\TouchPortal\plugins\DSEP4TP`
* Mac: `~/Documents/TouchPortal/plugins/DSEP4TP`
* Linux: `~/.config/TouchPortal/plugins/DSEP4TP`


<span class="next_section_button">
Read Next: [Scripting Syntax and Caveats](Scripting.md)
</span>

0 comments on commit 81fc00e

Please sign in to comment.