Documentation of django-expense

This documentation covers the django-expense, a simple personal expense tracker application for Django.

For sample screenshots or detailed description see User guide.

The source code of the project is hosted on bitbucket.org/szunyog/django-expense and the latest version of this documentation can be found on django-expense.readthedocs.org.

Contents

Installation

Before installing django-expense, you’ll need to have a copy of Django already installed. Django version 1.8 is required.

Note

If you need Django 1.3 support, use version 0.2.2.

For further information, consult the Django download page, which offers convenient packaged downloads and installation instructions.

Installation from source code and using development server

Getting the code

If you would like to try out the latest in-development code, you can obtain it from the django-expense repository, which is hosted at Bitbucket and uses Mercurial for version control. To get the latest code and documentation type the following commands:

hg clone http://bitbucket.org/szunyog/django-expense/

This will create a copy of the django-expense Mercurial repository on your computer.

Or you can download the source code from the downloads page. Use the tip tag for the latest release.

Starting the development server

A sample test project is included into the source tree, so if you want to try you can simple start this test project, to do this you need to enter the following commands:

cd testapp
python manage.py syncdb
python manage.py runserver

Note

The development server is configured to use sqlite database, so required packages should be installed.

Installation from package

Download the package

You can download the source code from the downloads page. Use the tip tag for the latest release.

Install

Once you’ve downloaded the package, from a command line in that directory, type:

python setup.py install

Note

On some systems you may need to execute this with administrative privileges (e.g., sudo python setup.py install).

Required settings

Begin by adding 'django.contrib.admin and expense to the INSTALLED_APPS setting of your project:

For example, you might have something like the following in your Django settings file:

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.sites',
    'django.contrib.admin',
    'expense',
    # ...other installed applications...
)

Once you’ve done this, run manage.py syncdb to install the model used by the default setup.

Setting up URLs

Expense application working on Django admin interface, so you have to enable it in your urls.py:

from django.conf.urls import include, url
from django.contrib import admin
from django.contrib.auth import views as auth_views


urlpatterns = [
    url(r'^expense/', include('expense.urls')),
    url(r'^admin/', include(admin.site.urls)),
    url('^login/$', auth_views.login,
        {'template_name': 'login.html'})

]

Note

Using this URL configuration your django admin site will be in the root.

Setting up login

The expenses app requires authentication. It has a custom login form. To set up the default login url set the LOGIN_REDIRECT_URL variable in your settings.py:

LOGIN_REDIRECT_URL = '/expense/add'

User guide

Introduction

Django expense has two types of user interface, one is integrated into the Django’s admin interface and the other is a custom one designed to the simplest as possible to be able to use it with mobile devices.

Admin site

When you finished installation, django-expense will appear on your Django admin site. From the admin menu you can edit three types of entities:

• Type: These are the Expense basic types such as income, outcome, savings etc... or you can use as bank account as well.
• Categories: These are the sub-categories under each type such as outcome/household, etc...
• Expenses: These are the expense items.

Main screen, expense list

The Expense change_list view is extended by a simple report, this page by default shows your expenses for the current month and summarizes your items by categories. Using the filters of the right hand side you can change the default filter expressions. You can filter the list by:

• Users: Individual user or all.
• Date: Month, year, all time.
• Category

The following figure shows the main screen of the application:

Add expense screen

Expenses can be added on this screen. The user field is defaulted with the currently logged on one, otherwise it is a default django admin screen.

Custom/Mobile interface

The custom interface is based on a Bootstrap desing, especially on the Holo theme.

It supports the following views:

Add

Here, you can store your expenses.

Log

On the log view, the recorded entries are visible:

Monthly report

Summarized monthly report. The displayed data is filtered by the actual month and aggregated by categories.

There is navigation bar on the bottom of the page to select other months.

Changelog

Version 0.5.1

• added hidden categories

Version 0.5.0

• Added custom ui
• removed charts from the admin ui

Version 0.4.0

• Change code to work with Django 1.8
• Fix code formatting

Version 0.3.0

• Upgraded minimum Django version to 1.4
• Replaced filterspec.py with filters.py, reflecting the new mechanism for custom filters for the admin interface in Django 1.4
• Corrected some English throughout the code

Version 0.2.2

• Fix y axis text orientation on bar charts.
• Fix documentation copy/paste errors.
• Integrate sphinx version with application version number.

Version 0.2.1

• Changed label orientation on bar charts to avoid text overlapping.

Version 0.2.0

• Added charts, using flot jQuery library.
• Updated documentation with screen shoots.
• Fixed expense screen appearance with django 1.3.
• Added test application into the source tree to make trying/testing easier.
• Added initial data.

Version 0.1.0

• Initial data structure.
• Basic administration interface with customized change list view.

License

Django-expense is licensed under the New BSD License:

Copyright (c) 2007-2011, Tibor Tóth
All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    1. Redistributions of source code must retain the above copyright notice, 
       this list of conditions and the following disclaimer.
    
    2. Redistributions in binary form must reproduce the above copyright 
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.

    3. Neither the name of django-expense nor the names of its
       contributors may be used to endorse or promote products derived
       from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.