slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: web update

Browse Source
This commit is contained in:
Simon Michael 2011-09-28 00:54:30 +00:00
parent 602ccceeec
commit 5cc6a1fe22
1 changed files with 13 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
MANUAL.md
View File

@ -775,11 +775,12 @@ Examples:
#### web #### web
The web command runs a HTTP server providing a web-based user interface The web command (an add-on provided by the hledger-web package) runs a web
server providing a web-based user interface
([release demo](http://demo.hledger.org), ([release demo](http://demo.hledger.org),
[latest demo](http://demo.hledger.org:5001)). [latest demo](http://demo.hledger.org:5001)). The web UI provides
The web UI provides reporting, including a more useful account register reporting, including a more useful account register view, and also data
view, and also data entry and modification. entry and editing.
web-specific options: web-specific options:
@ -793,55 +794,17 @@ custom url scheme when running hledger-web behind a reverse proxy as part
of a larger site. Note that the PORT in the base url need not be the same of a larger site. Note that the PORT in the base url need not be the same
as the `--port` argument. as the `--port` argument.
**Warning:** Warning: unlike other hledger commands, `web` can alter existing journal
Unlike other hledger commands, `web` can alter existing journal data, via data, via the edit form. A numbered backup of the file will be saved on
the edit form. A numbered backup of the file will be saved on each edit, each edit, normally (ie if file permissions allow, disk is not full, etc.)
normally (ie if file permissions allow, disk is not full, etc.) Also, Also, there is no built-in access control. So unless you run it behind an
there is no built-in access control. So unless you run it behind an
authenticating proxy, any visitor to your server will be able to see and authenticating proxy, any visitor to your server will be able to see and
overwrite the journal file (and included files.) overwrite the journal file (and included files.)
**Support files** hledger-web disallows edits which would leave the journal file not in
valid [hledger format](#the-journal-file). If the journal file becomes
hledger-web requires certain support files (images, stylesheets, unparseable by other means, hledger-web will show an error until the file
javascript etc.) to be present in a particular location when it has been fixed.
runs. Specifically, they need to be in a `web` directory, under the
`.hledger` directory, under the current directory when you start
hledger-web. To make this easy, hledger-web will auto-create these files
in `./.hledger/web/` if they do not exist. Currently, after doing this
it will exit, with a notice explaining what happened, and you'll have to
run it a second time.
The above is a compromise to satisfy certain technical constraints, but
there is an advantage: you can easily customise the web UI's appearance
(even while it is running) by editing these files. This is useful eg for
integrating with an existing site. You can also run with different
customisations by starting hledger-web from a different current
directory. Note this means you should be aware of where you start
hledger-web from, otherwise it may just create a new copy of the support
files and ignore your stylings. To keep things simple you might choose to
always run it from the same place, eg your home directory.
Also note that when you upgrade hledger-web in future, these files will
need to be upgraded too, probably by removing them and letting them be
recreated. So if you do customise them, remember what you changed; a
version control system such as darcs will help here.
**File changes are detected**
As noted, changes to the support files will take effect immediately,
without a restart. This applies to the journal data too; you can directly
edit the journal file(s) (or, eg, commit a change within a version control
system) while the web UI is running, and the changes will be visible on
the next page reload.
**Malformed edits are rejected**
The journal file must remain in good [hledger format](#the-journal-file) so
that hledger can parse it. The web add and edit forms ensure this by not
allowing edits which would introduce parse errors. If a direct edit makes
the journal file unparseable, the web UI will show the error instead of
data, until the file has been fixed.
Examples: Examples: