mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2026-09-20 16:42:02 +00:00
Initial commit
This commit is contained in:
Jermolene
@@ -1,6 +1,8 @@
|
||||
modified: 20141122200310516
|
||||
created: 20181001170605910
|
||||
modified: 20181001171639702
|
||||
tags: TableOfContents
|
||||
title: HelloThere
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
Welcome to the developer documentation for TiddlyWiki (https://tiddlywiki.com/). It is currently a work in progress as material from two different sources is adapted and merged in addition to original content being added:
|
||||
|
||||
@@ -22,5 +24,6 @@ Welcome to the developer documentation for TiddlyWiki (https://tiddlywiki.com/).
|
||||
** SyncAdaptorModules
|
||||
** WidgetModules
|
||||
** WikiRuleModules
|
||||
*Original developer documentation
|
||||
* New developer documentation
|
||||
** HookMechanism
|
||||
** [[External Shell Tasks]]
|
||||
|
||||
@@ -0,0 +1,131 @@
|
||||
created: 20181001171604072
|
||||
modified: 20181001184306738
|
||||
title: External Shell Tasks
|
||||
type: text/vnd.tiddlywiki
|
||||
|
||||
!! Introduction
|
||||
|
||||
It can be difficult for experienced developers to become proficient in working with TiddlyWiki's code: besides requiring a good understanding of JavaScript, the internals are built around relatively unusual concepts and techniques that are likely to be unfamiliar to most.
|
||||
|
||||
However, many software developers are very familiar with using and creating text-based command line tools that adhere to the Unix philosophy of using stdin/stdout for input and output, allowing tools to be chained together in powerful ways.
|
||||
|
||||
The external task mechanism allows Unix-style tasks to be registered and executed by TiddlyWiki under Node.js. Execution can be triggered via a server command or via a message propagated from the browser.
|
||||
|
||||
!! Configuration
|
||||
|
||||
External tasks must be registered in the `tiddlywiki.info` file of a wiki folder. For example:
|
||||
|
||||
```
|
||||
{
|
||||
"description": "Edition demonstrating external tasks",
|
||||
"plugins": [
|
||||
],
|
||||
"themes": [
|
||||
"tiddlywiki/vanilla",
|
||||
"tiddlywiki/snowwhite"
|
||||
],
|
||||
"includeWikis": [
|
||||
"../tw5.com"
|
||||
],
|
||||
"external-tasks": {
|
||||
"stats": {
|
||||
"path": "./demo-tasks/stats.js",
|
||||
"input": {
|
||||
"format": "json-raw-tiddlers"
|
||||
},
|
||||
"environment": {
|
||||
"MY_VARIABLE": "value"
|
||||
},
|
||||
"output": {
|
||||
"format": "json-raw-tiddlers"
|
||||
},
|
||||
"timeout": 100
|
||||
},
|
||||
"mimic": {
|
||||
"path": "./demo-tasks/mimic.js",
|
||||
"arguments": ["ngram-length"],
|
||||
"input": {
|
||||
"format": "rendered-text"
|
||||
},
|
||||
"environment": {
|
||||
"MY_VARIABLE": "value"
|
||||
},
|
||||
"output": {
|
||||
"format": "text",
|
||||
"tiddler": {
|
||||
"title": "HelloThere",
|
||||
"type": "text/plain"
|
||||
}
|
||||
},
|
||||
"timeout": 100
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
!!! Task Configuration Properties
|
||||
|
||||
TBD
|
||||
|
||||
!!! Input Formats
|
||||
|
||||
The available input formats are:
|
||||
|
||||
* `raw-text` - concatenated raw text of the tiddlers
|
||||
* `rendered-text` - concatenated rendered text of the tiddlers
|
||||
* `rendered-html` - concatenated rendered html of the tiddlers
|
||||
* `json-raw-tiddlers` - raw tiddlers in JSON
|
||||
* `json-rendered-text-tiddlers` - rendered tiddlers in JSON
|
||||
|
||||
!!! Output Formats
|
||||
|
||||
The available output formats include:
|
||||
|
||||
* `raw-text` - raw text
|
||||
* `json-raw-tiddlers` - raw tiddlers in JSON
|
||||
|
||||
!! Usage
|
||||
|
||||
External tasks can be invoked via the `--exec` command, or via a widget message propagated from the browser to the server.
|
||||
|
||||
!!! `--exec` Command
|
||||
|
||||
The `--exec` command triggers the execution of an external task. The parameters are:
|
||||
|
||||
```
|
||||
tiddlywiki <wikifolder> --exec <taskname> <filter> <arguments>...
|
||||
```
|
||||
|
||||
The ''taskname'' identifies the task to be run, and must match the name defined in the `tiddlywiki.info` file.
|
||||
|
||||
The ''filter'' identifies the tiddlers to be passed to the external task
|
||||
|
||||
The remaining ''arguments'' are passed through to the external task.
|
||||
|
||||
!!! `tm-exec-task` Message
|
||||
|
||||
TBD
|
||||
|
||||
!! Examples
|
||||
|
||||
The edition `editions/externaltasksdemo` in the TiddlyWiki5 repo contains a demo wiki that invokes sample tasks.
|
||||
|
||||
!!! Mimic
|
||||
|
||||
The `mimic.js` example is a simple command line tool that accepts source text via stdin and outputs a sort of statistical parody of the input text. It is written without any knowledge of TiddlyWiki, and so serves as an example of using an existing text-based tool with TiddlyWiki.
|
||||
|
||||
```
|
||||
tiddlywiki editions/externaltasksdemo/ --exec mimic '[[Alice in Wonderland]]' 5 4000 --build index
|
||||
```
|
||||
|
||||
View the resulting wiki at `editions/externaltaskdemo/output/index.html`: the tiddler "HelloThere" will contain a garbled version of the "Alice in Wonderland" text.
|
||||
|
||||
!!! Stats
|
||||
|
||||
The `stats.js` example is a simple command line tool that accepts source text via stdin and outputs a sort of statistical parody of the input text. It is written without any knowledge of TiddlyWiki, and so serves as an example of using an existing text-based tool with TiddlyWiki.
|
||||
|
||||
```
|
||||
tiddlywiki editions/externaltasksdemo/ --exec stats '[[Alice in Wonderland]]' --build index
|
||||
```
|
||||
|
||||
View the resulting wiki at `editions/externaltaskdemo/output/index.html`: the tiddler "HelloThere" will contain statistics about the "Alice in Wonderland" text.
|
||||
Reference in New Issue
Block a user