- Constructor and initialization
- Method: setup
- Installation and Configuration
- Q: How do you handle the ATO's requirements for BAS and GST?
- Q: What happened to the Petty Cash/Private Use columns in the Payments input screen?
- Q: What's the basic design of the code?
- Q: How do I configure things?
- Q: Why is it in the AU namespace?
Business::AU::Ledger - A simple, web-based, payments/receipts manager
A CGI script:
#!/usr/bin/perl use Business::AU::Ledger; Business::AU::Ledger -> new -> run;
Business::AU::Ledger is a pure Perl module.
It is based on
It provides a web-based interface to a database of payment, receipt and reconciliation transactions.
The database schema is shipped in docs/schema.png.
This version is being released as 0.80 rather than the 1.00 I wanted, because of the following missing features.
AFAICT, the transactions themselves are reliably stored and retrieved from the database.
Nevertheless, I do not regard this code as production-ready, because of this TODO list.
These items are not listed in any particular order:
These are simply not coded yet.
- REST-style usage
The code uses the CGI::Application standard way of specifying state via the 'rm' hidden CGI form field.
I would prefer to switch to REST-style usage of the path info to transmit such information.
This would make it easy to use FCGI::ProcManager to speed things up.
- Allow specific transactions to be deleted
There is no Delete button displayed. You need to blank out all fields and submit the transaction.
Another column containing Delete buttons makes the display wider :-(.
- Handle split cheques
Another tab on the screen needs to be designed and coded for these.
- Categories and Types
The lists for Category and Type of transaction are loaded into the database at initialization time from text files.
There is no way for the user to update these lists.
- Petty Cash
How, exactly, to handle Petty Cash?
I personally don't use it, but I assume some people do.
- Co-dependent fields
Given one of the Private Use % and $ columns, the other can be calculated. Perhaps only get user input for one of them.
- In-situ Updates
Performing an in-situ update of a displayed transaction requires knowing the id of each.
- Test Data
It would be good to have a command-line script which jammed a few transactions into the database for testing purposes.
- Non-web interface
The POD should explain how to use the given modules to circumvent the web interface.
Constructor and initialization
new(...) returns an object of type
This is the class's contructor.
Usage: Business::AU::Ledger -> new.
This method lists the valid run modes, which are:
Installation and Configuration
There are several steps in the installation process:
- Install the database server
You will edit .htledger.conf, as explained below, to tell Business::AU::Ledger how to connect to the database.
- Install the Perl module Business::AU::Ledger
This is the same as installing any other Perl module.
Note, however, that you will always need to download the distro from CPAN, because other installation and configuration steps use files not installed in the Perl module tree.
Note, also, that installing the module will install a file called .htledger.conf in Perl's module tree, and in the next few steps you may wish to edit that file. In this case, the file's permissions become relevant.
- Install the HTML templates
Unpack the distro, and copy (recursively) the directory htdocs/assets/ to your web server's doc root directory.
If you do not wish to use the recommended directory structure, put the contents of htdocs/assets/css/business/au/ledger/ and htdocs/assets/templates/business/au/ledger/ anywhere you want, and edit the file lib/Business/AU/Ledger/.htledger.conf (css_url and tmpl_path) to match.
- Install the YUI (see FAQ below)
Download YUI from http://developer.yahoo.com/yui/ and install it in your web server's doc root directory.
Then, if necessary, edit lib/Business/AU/Ledger/.htledger.conf, where it says yui_url=/yui.
- Install lib/Business/AU/Ledger/.htledger.conf
Installing the module will have installed the version of .htledger.conf as shipped within the distro.
If you edit your local copy of .htledger.conf, you must use your edited copy to overwrite the version installed automatically.
Specifically, the database credentials in this file will need to be edited, since several programs use them to connect to the database.
- Install the CGI script ledger.cgi
Copy cgi-bin/ledger.cgi into your web server's cgi-bin directory, and mark it as executable.
- Initialize the database tables
In the unpacked distro dir, run:
perl scripts/create.tables.pl perl scripts/populate.tables.pl
Check that this worked by logging on to your database server, via the command line say, and running:
select * from tx_details
You should get 15 rows output.
- Point your web client at http://127.0.0.1/cgi-bin/ledger.cgi
To start, you must specify the first month of your financial year.
After that, click on Payments or Receipts, then on the name of a month.
Lastly, click on Initialize to display any transactions already in the database for that month.
Q: How do you handle the ATO's requirements for BAS and GST?
ATO is Australian Tax Office.
BAS is Business Activity Statement, the basic document by which many businesses report turnover details.
GST is Goods and Services Tax.
The answer is: I don't (for which I'm extremely grateful).
That is, I run my business in such a way as to simply not need to account for those details. I do this by performing contract programming services via a contract with Freelance Global ( http://www.freelance-global.com/ ), an organization operated by my accountant (M. Kelson).
Organizations wishing to hire me sign a contract with Freelance, not with me directly. Hence I avoid the need to manage BAS- and GST-related components of financial transactions.
However, I do understand they are important, and will eventually add those features if those of you needing them give me the support I need.
Q: What happened to the Petty Cash/Private Use columns in the Payments input screen?
A: I don't use those fields. If they vanished from one version to the next, it's because I commented them out in assets/templates/business/au/ledger/monthly.tabs.js, and forgot to re-enable them before releasing the new version. Sorry!
Commenting them out means the required display width is narrower, and so I can use a bigger screen font.
You can safely just uncomment lines 57 .. 60 of that file.
Q: What's the basic design of the code?
A: MVC (Model, View, Controller).
The Model component is implemented in Business::AU::Ledger::Database and Business::AU::Ledger::Database::*.
The View component is in Business::AU::Ledger::View and Business::AU::Ledger::View::*.
The Controller is this module, Business::AU::Ledger.
Q: How do I configure things?
A: See lib/Business/AU/Ledger/.htledger.conf.
See also the previous section 'Installation and Configuration'.
See also the discussion below regarding the AU namespace.
A: YUI, the Yahoo! User Interface Library ( http://developer.yahoo.com/yui/ ).
I'm using V 2.7.0 of YUI.
A: Don't be ridiculous.
Q: Why is it in the AU namespace?
A: Some of the code, a very small amount, depends on the Australian taxation system.
In fact, one reason for the Options tab (one day) is to allow for tax years which don't start in July the way ours do. The default value for the month which starts each financial year can also be set in .htledger.conf.
There are, of course, various place where Australian-specific output is generated. Here I'm referring to the columns in the Payments and Receipts tabs.
Of course, the pop-up menus for various columns contain data specific to the ATO's classification system. See the files in the data/ directory, which initalize the corresonding database tables.
Business::AU::Ledger was written by Ron Savage <email@example.com> in 2009.
Home page: http://savage.net.au/index.html
Australian copyright (c) 2009, Ron Savage. All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of the Artistic or the GPL licences, copies of which is available at: http://www.opensource.org/licenses/index.html