README.md

beanhub-forms

BeanHub Forms was originally developed by BeanHub as a product feature for users to easily define their custom forms and templates for generating Beancount entries. The BeanHub Forms feature was later extracted as a standalone library beanhub-forms and open-sourced under an MIT license. With beanhub-forms, one can define a custom form like this in YAML file format:

forms:
- name: add-xyz-hours
  display_name: "Hours spent on XYZ contracting project"
  fields:
  - name: date
    type: date
    display_name: "Date"
    required: true
  - name: hours
    type: number
    display_name: "Hours"
    required: true
  - name: rate
    type: number
    display_name: "Rate (USD)"
    default: "300"
    required: true
  - name: narration
    type: str
    default: "Hours spent on the software development project for client XYZ"
    display_name: "Narration"
  operations:
  - type: append
    file: "books/{{ date.year }}.bean"
    content: |
      {{ date }} * {{ narration | tojson }}
        Assets:AccountsReceivable:Contracting:XYZ      {{  hours }} XYZ.HOUR @ {{ rate }} USD
        Income:Contracting:XYZ

And then use tools like beanhub-cli command to launch a web app server locally:

bh form server

Then, the user can use the rendered form to input repeating similar Beancount entries easily.

As you can see, the append operation with Jinja2 template as the content is defined in the form doc schema:

- type: append
  file: "books/{{ date.year }}.bean"
  content: |
    {{ date }} * {{ narration | tojson }}
      Assets:AccountsReceivable:Contracting:XYZ      {{  hours }} XYZ.HOUR @ {{ rate }} USD
      Income:Contracting:XYZ

When you submit the form, the form input data will be used for rendering the template and appending the result to the target file.

2023-10-11 * "Hours spent on the software development project for client XYZ"
  Assets:AccountsReceivable:Contracting:XYZ      12 XYZ.HOUR @ 300 USD
  Income:Contracting:XYZ

The file name file can also be a Jinja2 template. The file name books/{{ date.year }}.bean with 2023 the input value in the form will end up as books/2023.bean. This allows you to organize entries by dates or other variables into different files and folders easily.

Read the documentations here.

Sponsor

A modern accounting book service based on the most popular open source version control system Git and text-based double entry accounting book software Beancount.

Install

This library provides schema definition of the forms and the libraries for generating WTForms plus processing the form data. For most users, you don't need to install beanhub-forms. You can install beanhub-cli instead if you only want to use it.

To install this library, simply run

pip install beanhub-forms