#+title: Trees

[[https://intver.org/][https://img.shields.io/badge/versioning-intver.org-blue.svg?style=for-the-badge]]

Generate a static HTML/CSS/JS page that allows users to walk through a decision tree.

#+html: <img src="trees.webp" />

* Install

Assuming [[https://github.com/babashka/bbin][bbin]] is installed:

#+begin_src sh
bbin install io.github.bzg/trees
#+end_src

* Run

You can try it against the =config-example.yml= file provided in this repository:

: ~$ trees config-example.yml

This generates =index.html=.  You can pass another output file name as
a second argument:

: ~$ trees config-example.yml output.html

Display the installed version with =trees -v= (or =--version=).

* Configuration

See =config-example.yml= for a complete, commented example.  Main
top-level options:

| Option                   | Description                                              |
|--------------------------+----------------------------------------------------------|
| =locale=                   | UI language: =en= (default), =fr=, =de= or =sv=                  |
| =framework=                | CSS framework (see below)                                |
| =css-theme=                | CSS theme (see below)                                    |
| =header=                   | Page header: =title= and =subtitle=                          |
| =footer=                   | Page footer: =text= and =contact=                            |
| =mail-to=                  | Email address for sending results                        |
| =display-back=             | Show a back link on each page (default: =true=)            |
| =display-summary=          | Show the summary of answers on final pages               |
| =chronological-summary=    | List the summary in answer order (default: latest first) |
| =display-score=            | Show the score result on final pages                     |
| =display-score-details=    | Show raw score values                                    |
| =display-unconditionally=  | Extra text always shown along with the score             |
| =score-variables=          | Score variables and their initial values                 |
| =conditional-score-output= | Score-dependent messages on final pages                  |
| =ui-strings=               | Override built-in UI strings (e.g. =redo=, =mail-subject=)   |
| =tree=                     | The list of decision tree nodes                          |

* CSS frameworks

Set =framework= in your config file.  The default is =pico=.

| Framework | Value |
|-----------+-------|
| [[https://picocss.com][Pico 2]]    | =pico=  |
| [[https://purecss.io][Pure CSS]]  | =pure=  |
| [[https://bulma.io][Bulma]]     | =bulma= |

* Themes

When using Pico, you can set a theme with =css-theme=:

#+begin_src yaml
css-theme: "doric"
#+end_src

The =css-theme= option accepts:

- A pico-themes name (e.g. =ashes=, =doric=, =swh=)
- An =http(s)://= URL to a remote CSS file
- A =file:///= URL to a local CSS file
- A local =.css= file path

Available themes from [[https://github.com/bzg/pico-themes][pico-themes]]: =swh=, =org=, =doric=, =lincoln=, =teletype=, =ashes=.

For backward compatibility, =theme-url= and =theme= are still supported.

* Requirements

=trees= is written as a [[https://clojure.org][Clojure]] [[https://babashka.org][Babashka]] script and we recommend
installing it with [[https://github.com/babashka/bbin][bbin]]. Install everything:

#+begin_src sh
brew install babashka/brew/bbin
#+end_src

For detailed installation instructions:

- [[https://clojure.org/guides/install_clojure][Install Clojure]]
- [[https://github.com/babashka/babashka#installation][Install babashka]]
- [[https://github.com/babashka/bbin#installation][Install bbin]]

* Contributing

- Send a [[mailto:~bzg/dev@lists.sr.ht][bug report]] with =[BUG] trees: <SHORT EXPLICIT BUG DESCRIPTION>=
- Send a [[mailto:~bzg/dev@lists.sr.ht][patch]] with =[PATCH] trees: <COMMIT SUMMARY>=
- Send a [[mailto:~bzg/dev@lists.sr.ht][feature request]] with =[FR] trees: <FEATURE REQUEST>=
- Share any [[mailto:~bzg/dev@lists.sr.ht][other question or idea]]

You can also [[mailto:bzg@bzg.fr][send me an email]] and support my work on [[https://liberapay.com/bzg/][liberapay]].

* Intentional Versioning

This project uses [[https://intver.org][Intentional Versioning]], here are the three audiences:

- =Users= : end users who use trees
- =Integrators= : external packagers
- =Maintainers= : maintainers of the codebase

* Support the Clojure(script) ecosystem

If you like Clojure(script), you can support the ecosystem by making a
donation to [[https://www.clojuriststogether.org][clojuriststogether.org]].

* License

The code in this repository is licensed under [[LICENSES/EPL-2.0.txt][EPL-2.0]].