Developing locally
Build and view a tool on your own machine with new-tool.py and dev-proxy.py.
The clone of the repository holds two scripts. new-tool.py turns a collection into a tool, dev-proxy.py shows it in the browser, with the data of your instance. Both need Python 3 and nothing else. This way you see every change at once, without a push.
The way in four commands
cd flow-tools
git pull --rebase origin draft
./new-tool.py aufgaben
./dev-proxy.py --tool tools/aufgaben
Then open http://127.0.0.1:3000/ in the browser. When you like the state, deliver it as a draft:
git add . && git commit -m "aufgaben" && git push
Creating a tool: new-tool.py
./new-tool.py <collection> copies the template tools/example/ to tools/<collection>/, sets name and title, enters the collection in tool.json under uses and points app.js at it.
In doing so the script fetches the schema of the collection from the instance. A misspelled name, a missing read permission and an expired token show up right there and not only in the browser.
| Option | Meaning |
|---|---|
--name | name of the directory and of the address. Default: the name of the collection |
--title | title of the tool. Default: the title of the collection |
--into | target directory. Default: tools |
--backend | address of the instance, outside a clone |
--token-file | file holding the access token |
The template is generic: it reads the schema and builds form and table from it. A field added later appears by itself. Whatever your tool should do differently, you change in app.js and style.css.
Viewing the tool: dev-proxy.py
./dev-proxy.py --tool tools/<name> serves the files from your directory and forwards every call under /api/ to the instance. The proxy adds your access token to those calls.
| Option | Meaning |
|---|---|
--tool | directory of the tool (required) |
--port | port on your machine. Default: 3000 |
--check | only checks the delivery rules and starts nothing |
--backend | address of the instance, outside a clone |
--token-file | file holding the access token |
The code of your tool stays exactly as it ships. It sends JSON to relative paths. On your machine the proxy adds the token, in the instance the session cookie travels along. Your code needs no “local or not” switch.
The proxy sets the same content security policy as the instance. So an inline script already fails locally.
Where address and token come from
Inside a clone neither script needs --backend or a token: both read the address of the instance from git remote get-url origin, and the token too if it is in that address. This is how setup.sh sets it up.
Outside a clone you state both:
export FLOW_TOKEN=flowpac_pat_...
./new-tool.py aufgaben --backend https://<instance>
./dev-proxy.py --tool tools/aufgaben --backend https://<instance>
Why a proxy is needed
A tool and the data interface must have the same origin. A fetch from another port does not carry the session cookie, and the instance deliberately answers without CORS headers. So the proxy puts both under one origin: your files and the interface at http://127.0.0.1:3000.
Why the proxy listens on 127.0.0.1 only
The proxy signs every call with your token. Whoever reaches it acts in the instance under your name. That is why it listens on the loopback of your machine only. On a network address it would be an open door to the instance. Do not change that, and do not forward the port.
What is different locally
flow.js reports errors in the browser to the instance only under /t/<name>/. Locally they appear in the console of the browser.